How can I customize an <xref> output?

This forum is for all Flare issues related to styles, stylesheets and XML.

How can I customize an <xref> output?

Postby luvthepug on Mon Apr 29, 2019 4:12 pm

I want to know if there is a way to modify the text of a cross-reference. I am using Flare 2019 and my output is WebHelp and HTML/chm.

BTW, I know I can use an <href> to achieve what I want, but I want the updating features that <xref>s offer and <href>s don't.

Here is my scenario:

I have a top-level book in my TOC called Performance Tests. Each topic under that book is a different test each with its own title. For example, one of the topics has Blahdey Blah Performance Test as the <H1> topic title. So when I use an <xref> to reference that topic, it comes out as "Please refer to the Blahdey Blah Performance Test for more information." Which is fine for this instance.

However, there are instances where I only want the Blahdey Blah part of the title and I don't want to include the words "Performance Test". For example, I also have a topic where I show the entire list of performance tests in the order they should be performed. In that case, I don't want to keep repeating "Performance Test" in each test title in the list. But if I use an <xref>, the complete title including "Performance Test" comes through.

This is how I want my list to look:
Perform the following performance tests in the order shown:
1. Blahdey Blah
2. Yada Yada Yada
3. And So On

But because the words "Performance Test" are part of the <H1> in the topic, this is how it looks using <xref>s:
Perform the following performance tests in the order shown:
1. Blahdey Blah Performance Test
2. Yada Yada Yada Performance Test
3. And So On Performance Test

I don't want the words "Performance Test" repeated every time. Is there a way to exclude part of the text in the <H1> when using it for an <xref>?
luvthepug
Propeller Head
 
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Postby Nita Beck on Tue Apr 30, 2019 4:48 pm

Your description of what you want to achieve is a perfect use case for using hyperlinks, not cross-references. By design, the text of cross-references' text is meant not to be edited. Rather, when it builds output, Flare will use the first heading in a destination topic as a cross-reference's text. The only thing you can change about cross-references is their format. For example, you could have an xref that'll render in online output as "See Title of Your Topic". The same xref rendered in print output could be "For more information, see 'Title of Your Topic' (on page 33)".
Nita
Image
Content Strategist / Information Architect / Flare Consultant: http://beck-communications.com
Manager, Rochester Flare User Group: http://www.facebook.com/RochesterFlareUserGroup
Nita Beck
Senior Propellus Maximus
 
Posts: 3290
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How can I customize an <xref> output?

Postby luvthepug on Wed May 01, 2019 9:18 am

By design, the text of cross-references' text is meant not to be edited. Rather, when it builds output, Flare will use the first heading in a destination topic as a cross-reference's text. The only thing you can change about cross-references is their format.

Thanks, Nita. I was afraid of that. I really wanted to be able to use the <xref> in this case because the test names can change, and to have the auto-update feature of the <xref> is very helpful when that happens.
luvthepug
Propeller Head
 
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Postby ChoccieMuffin on Wed May 01, 2019 9:54 am

Just looking at it from a different direction, do you HAVE to have "Performance Test" in the headings for each of those items? You could rephrase the text around your x-refs to say something like "refer to the Blahdey Blah performance test for more information" where just the bold underlined text is the topic heading. Obviously you'd have to include "Performance Test" in whatever surrounds your x-ref, but it's very manageable, and would mean your x-refs would keep up to date if titles change. (As a tip I don't ever include "For details see" or similar in the x-ref format because I like to be able to expand a bit, which you can't if you've included that gubbins in the x-ref format.)
Started as a newbie with Flare 6.1, now using Flare 2019r1.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
ChoccieMuffin
Senior Propellus Maximus
 
Posts: 2147
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: How can I customize an <xref> output?

Postby luvthepug on Wed May 01, 2019 12:00 pm

Just looking at it from a different direction, do you HAVE to have "Performance Test" in the headings for each of those items?

Yes, unfortunately those titles do need to include the text "Performance Text" in them because there are instances where there is the same name but as an adjustment topic. So there could be both "Blahdey Blah Performance Test" and "Blahdey Blah Adjustment" topic pages. So I do need to include "Performance Test" (and similarly "Adjustment") in the topic titles to distinguish the two topics. (And I don't include any additional text in my <xref> formats...probably my example was misleading.) But thanks for tip anyway.
luvthepug
Propeller Head
 
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Postby ChoccieMuffin on Thu May 02, 2019 9:44 am

luvthepug wrote:
Just looking at it from a different direction, do you HAVE to have "Performance Test" in the headings for each of those items?

Yes, unfortunately those titles do need to include the text "Performance Text" in them because there are instances where there is the same name but as an adjustment topic. So there could be both "Blahdey Blah Performance Test" and "Blahdey Blah Adjustment" topic pages. So I do need to include "Performance Test" (and similarly "Adjustment") in the topic titles to distinguish the two topics. (And I don't include any additional text in my <xref> formats...probably my example was misleading.) But thanks for tip anyway.


That sounds perfect - both the Performance Test topics and the Adjustment topics can have the same text as their h1 and you can handle x-refs in the text to them in the same way - "refer to the performance test Blahdey Blah on page xxx for more information" and "refer to the adjustment Blahdey Blah on page yyy for more information", with the two cross-refs pointing to the relevant topics (which, obviously, are two different topics). The x-ref can contain the page number for printed output or just a link for online output, formatted in your different mediums. As you've already said you have a top-level book for performance tests, I'm guessing you may have another top-level book for adjustments, so even in your TOC if you use the automatic titles, things will still be clear.
Started as a newbie with Flare 6.1, now using Flare 2019r1.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
ChoccieMuffin
Senior Propellus Maximus
 
Posts: 2147
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: How can I customize an <xref> output?

Postby doc_guy on Thu May 02, 2019 4:35 pm

If you always want to have the text "Blahdey Blah" and never "Blahdey Blah Performance Test" you could use the title attribute. I think that is what MadCap will use for the cross reference unless you specifically point to the H1, or if no title attribute is present.
User avatar
doc_guy
Propellus Maximus
 
Posts: 1947
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West

Re: How can I customize an <xref> output?

Postby Nita Beck on Thu May 02, 2019 6:07 pm

Doc_guy: <headslap>Doh! Of course!</headslap>.
Nita
Image
Content Strategist / Information Architect / Flare Consultant: http://beck-communications.com
Manager, Rochester Flare User Group: http://www.facebook.com/RochesterFlareUserGroup
Nita Beck
Senior Propellus Maximus
 
Posts: 3290
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How can I customize an <xref> output?

Postby luvthepug on Thu May 16, 2019 11:26 am

If you always want to have the text "Blahdey Blah" and never "Blahdey Blah Performance Test" you could use the title attribute.

(Sorry, I'm tardy in getting back to my post to check for replies.)
doc_guy, I'm not familiar with using attributes. How would I go about using that feature to accomplish what I want in my scenario?
luvthepug
Propeller Head
 
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Postby doc_guy on Thu May 16, 2019 4:49 pm

In the Content Explorer, right-click on a topic, and select Properties. You see this dialog box:
Image
Enter the title you want to use in the Topic Title box. This will then be used for cross references, breadcrumbs, TOC entries, and entries in the menu proxy.
User avatar
doc_guy
Propellus Maximus
 
Posts: 1947
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West

Re: How can I customize an <xref> output?

Postby luvthepug on Fri May 17, 2019 9:37 am

Ah, OK, since you had referred to it as an "attribute" I was looking in the Attributes Window where there is a setting for "title". I've never done anything in that window. I will try doing it in the file Properties window. Thanks very much doc_guy!
luvthepug
Propeller Head
 
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Postby doc_guy on Fri May 17, 2019 10:29 am

Happy to help! Hope it helps you get to where you want to be.
User avatar
doc_guy
Propellus Maximus
 
Posts: 1947
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West


Return to Styles, Stylesheets and XML

Who is online

Users browsing this forum: No registered users and 3 guests