Diagram of linking to a heading in a snippet in another topic

Snippet Cross Reference Work Around in Flare

You probably already know how powerful snippets are in MadCap Flare. They allow you to reuse chunks of content in various places in the same project. You can even include variations of snippets in different places in your project by using snippet conditions in the topics that use snippets.

However, recipe there remains one frustrating issue with using snippets in a topic: linking to (or cross referencing to) content inside a snippet.

In a normal cross reference or link, viagra sale you can use the Flare insert options to create the link. If you are linking to a heading, no rx Flare will even insert the target anchor into the project, and the Insert dialog shows you all the headings in the target topic by default. However, when you use a snippet in the topic, Flare doesn’t look inside the snippets for bookmarks or headings, so using the normal Flare Insert dialog, you can’t create cross references or links to content that is inside the snippet.

This inhibits the usability of snippets, because users might decide to not use snippets when they would still be useful just so they can get links and cross references working to topics that contain snippets.

I discussed this issue with a good friend of mine, Daniel Ferguson, of Write Degree Communications. He’s a fellow Flare contractor (whose work I highly recommend) and he shared a way around this limitation. It involves some manual coding, but it seems to work.

Let’s say you have Topic A and Topic B. Topic B contains one snippet that has two H2 elements. You are working in topic A and want to create a cross reference to the second heading inside the snippet that is used in Topic B. Maybe this illustration will help.

Diagram of linking to a heading in a snippet in another topic

So, what can you do to make this work?

Well, it turns out that the same code that works with regular links and cross references works with snippets, but you have to do the coding by hand.

There are three main steps: (1) Add the bookmark in the snippet; (2) Create the link or Cross Reference; (3) Test it.

Add the bookmark in the snippet

First, open the snippet file and locate the heading that you want to be able to link to. Click  to insert your curser at the beginning of the heading. From Flare’s Insert ribbon, select Bookmark (it’s in the Link section).

Now, give the bookmark an easy name to remember, because you’re going to have to insert it manually again. When you’re finished, save the topic.

If you look at the XML of the snippet, you now have the following:
<a name=”TheNameYouChose”></a>
in context, it probably looks more like this:
<h2><a name=”TheNameYouChose”></a>It’s a brand new day</h2>
Now you’re ready for the next step.

Create the link or cross reference

This is where the manual work comes in. Because Flare won’t let you create the link using the UI, you are going to have to go into the code editor to do this. You can use Flare’s code editor (which is super awesome, starting with Flare 9), or another text editing tool; it doesn’t matter.

Open topic A (in my case, a.htm) in the text editor. Locate the place where you want to create the link or cross reference.

For a cross reference add the following code, adapting it for your specific circumstances:

<MadCap:xref href=”B.htm#TheNameYouChose”>See “It’s a brand new day”</MadCap:xref>.

For a link you can just do this:
<a href=”B.htm#TheNameYouChose”>whatever text should be the link</a>
Now you test it.

Test it

Make sure that topic A and topic B are in the TOC you’re building, and generate the output from Flare. Go check the link/xref. If it is a printed target, it should point you to the correct page. If it is an online target, the link should work.

A few notes

  • Don’t try to edit this cross reference in Flare. It still won’t see the link, so it won’t let you save it as a valid cross reference.
  • If you change the text of the target paragraph, Flare SHOULD change the text of the cross reference, like normally happens with cross references. You will want to check this to ensure it is happening, though, because just because it worked for me doesn’t necessarily mean it will work in all cases for you. This isn’t something that MadCap is testing when they do releases, so like in all software development, there are likely cases in which it won’t work. Just check your output to see that it did. (You can also go to the Tools ribbon, and click Update Cross References. That will let you verify that the text changed without building the output.)
  • If you want to use a special type of cross reference, and have already created classes of XREF for this purpose, you can easily add them to the code. Add the class like you normally would IN THE CODE. Again, you can’t do this in the editor. For example, I have a class of XREF named “AtAGlance”. I would use that class like this:
    <MadCap:xref href=”B.htm#TheNameYouChose” class=”AtAGlance”>See “It’s a brand new day”</MadCap:xref>

Good luck, and let me know if you run into any issues here. If you think this is something you’d like to see Flare support natively in the future, you’re welcome to submit this as a feature request on MadCap’s website (link).

Something that Ferg mentioned when we discussed this earlier that I totally agree with is how glad we are that Flare has an open architecture where you can go into the code to make these kinds of changes, when you need to extend some functionality that isn’t natively supported. We’ve both worked with other authoring tools that don’t give you access to the code, so you can’t make these kinds of edits. In fact, during professional training for another authoring tool, we asked the trainer how to get into the source to make modifications. The trainer looked at us and said, “You can’t. And why would you want to?” So thanks, MadCap, again for an outstanding tool in MadCap Flare.

Also, don’t forget to check out Write Degree Communications. Thanks again, Ferg, for helping me with this issue. If any of you are coming to MadWorld next month in San Diego, you can meet both me and Ferg there. We’re both looking forward to it.

, , , , , , , , ,

7 Responses to Snippet Cross Reference Work Around in Flare

  1. Thomas Tregner April 1, 2014 at 6:51 am #

    There will be ambiguity if the snippet is used in multiple topics. Love the story about the trainer.

    • Paul April 1, 2014 at 11:31 am #

      Hi Thomas; thanks for the comment.

      As long as you don’t use the same snippet in multiple places in the same topic, then there isn’t ambiguity, because you’re not linking to the snippet directly. You’re linking to topic B.htm, and then going to the bookmark inside that topic, which happens to be in a Flare snippet. But the link is to the topic that _contains_ the snippet, so you are okay.

      There would certainly be ambiguity if you were to try to link to the snippet directly, but you can’t do that, for several reasons.

      • Thomas Tregner April 1, 2014 at 12:38 pm #

        Thanks for clarifying. I agree. If someone stays within the bounds you described, they should be fine. My original statement is wrong unless there are two instances of the snippet in the other topic such as placing a warning in two places. It is possible to create the ambiguity you described, two instances of a snippet in a topic, without any complaints from Flare. In an HTML5 output, major browsers won’t complain either. Interestingly, if you use the XHTML Book target type, Flare will generate a unique bookmark in place of the instances of the repeated destination anchor. The real issue with elements with the a tag and name attribute is that Flare doesn’t translate those into something else for HTML5 output or disallow the pattern in the UI.

  2. michelle April 28, 2016 at 12:04 pm #

    There’s another issue here – while the link/xref may work in output, Analyzer flags these as broken bookmarks.

  3. Amit September 15, 2016 at 2:03 pm #

    I like the idea you suggested. But my problem is a little different. I have a situation where I need to link between two snippet files. Snippet A is part of A.htm and Snippet B is part of B.htm and both the HTML files are part of the TOC. I tried linking (at the .flsnp file level) but the Flare compiler did not like it. Any suggestions to get this working?

  4. Samantha Nair October 10, 2016 at 10:12 am #

    Excellent article, Paul. I’ve adapted your solution slightly as my topics contain multiple snippets that cross-reference each other, but the reader needs to remain in the same topic. I was scratching my head for ages before I came across your article, then it was a case of “D’oh, so obvious now!”. As you state, I’m so grateful to Flare’s open architecture that allows this!

  5. Deb (@debdebtig) December 21, 2016 at 11:22 am #

    Exactly what I needed! Thank you so much for posting this.

Leave a Reply