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, 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, you can use the Flare insert options to create the link. If you are linking to a heading, 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.
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:
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:
For a link you can just do this:
<a href=”B.htm#TheNameYouChose”>whatever text should be the link</a>
Now you 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.