A Flare user sent us a great question about referencing content:

“We want to be able to say that a particular customer issue is addressed by ‘KB article 10249′ rather than by an article named ‘How to do this in our product’, as the title may change, but the number should remain the same.”

After some deliberating here at MadCap Software, we concluded that by inserting a cross-reference (XRef) to a topic and using a format in the MadCap|xref style class, you could pull the linked topic’s file name (with or without extension) or topic title.

For those of you astute single-sourcers out there who read the question and assumed you could just use a variable or snippet to do the job, keep in mind that these wouldn’t be inclusive to a particular topic. You would be able to reference the topic identifier as a variable definition into content, but then the variable’s definition would have the possibility of being overridden at the target level.  You’d also have to maintain a list of all topics/ID’s as a variable tag set, which could get clunky if you’re dealing with a large volume of content.

The XRef method works under a couple of assumptions, though:

  1. You’re on board with storing the topic’s unique ID as either the filename of the topic, or in the “Topic Title” metadata field edited in the Topic Properties.
  2. You have to reference the topic ID using an XRef.

Cross-References in Flare

XRef_Dialog

The Insert-> XRef Dialog, see the XRef Properties section where you can <madcap|xref> style class that pulls the topic {title}.

An XRef is a type of hyperlink, not a single-sourcing element. From the Flare 10 documentation here:

A cross-reference is a navigation link that lets you connect text in one topic to another topic (or a bookmark within a topic). This is somewhat similar to a text hyperlink. However, cross-references differ from hyperlinks in a few ways. They are based on format commands that help you keep the look of links consistent and are especially useful for print output.

More information on using and inserting XRefs in content can be found here.

The details on XRef formatting pertains to what we’re doing here, as it explains how we’re pulling data from the topic (topic title or filename) from the <MadCap|xref> style:

Select "Title" from the Text Commands in the XRef Style Class Editing Dialog
Select “Title” from the Text Commands in the XRef Style Class Editing Dialog

Cross-references let you create automated links that are based on commands you provide. This allows you to keep links consistent and change them in just one place by using the <MadCap|xref> style. Commands are contained in brackets (e.g., {paratext}).

More information on customizing the <MadCap|xref> style class can be found here.

 

Your process will be as follows:

  1. As you’re developing content and adding topics to your project, give each filename a unique ID (can be alpha or numbers), or, after a topic is added to the project, update the topic properties field to contain a topic’s unique ID.
  2. Create an <MadCap|xref> style that injects the cross-referenced topic’s {filename} (with or without extension), or {title} field.
  3. Anywhere you want to reference a topic’s {title} or {filename}, simply Insert->XRef.

I’ve put together a sample project that demonstrates using an XRef with <MadCap|xref> style classes in a CSS file that pulls the appropriate properties.  You can download it here, and build the HTML5 output to see how it all functions.

 

 

About The Author

Jose Sermeno

About Jose Sermeno

With over 10 years of experience in the software industry, Mr. Sermeno brings a wealth of knowledge and expertise to the product evangelist team, helping introduce new users to everything MadCap Software. In his spare time, Jose is the Project Director for San Diego City Robotics, the San Diego community college systems robotics program, and enjoys working in software design and open source hardware development. Prior to joining MadCap in late 2010, Jose ran a Drupal development shop, and was an application manager for Temple University Health System.

Last Modified: November 6, 2014

This entry was posted in MadCap Flare, MadCap Software, Tech Comm, Tips & Tricks. Bookmark the permalink.

Comments

  • Sukumar Jena July 28, 2014 at 1:07 AM

    Hi Jose Sermeno,
    I love this information and this blog. Really amazing !!
    Thanks for this nice blog

  • Ken June 14, 2017 at 2:58 AM

    Hi Jose,
    Like the idea of xrefs, but I can’t seem to find how I can determine the link text myself. I don’t want the title or bookmark paragraph. I want to determine for each bookmark what the displayed text is. How can I do that?

    • Jennifer Morse Jennifer Morse June 14, 2017 at 9:23 AM

      Hi Ken,
      With Xrefs, the text of the actual link is always controlled by the commands, so the topic’s first heading, or an autonumber format. You can change the text before a command. As an example – “For more information…” can be changed to “See…” Linking to the command is how xrefs word by design. If you want to control the link text manually, it would be best to use a hyperlink.

Have Something to Say?

Your email address will not be published. Required fields are marked *