Adobe InDesign and XML: Building a run-in template

Some years ago I ran a series of seminars on working with XML and InDesign using an ‘out-of-the-box’ approach. I put together some notes at the time, and I recently rediscovered them and thought it was time to share them with the rest of the world 🙂  I’m posting them un-edited, so if you spot any glaring errors feel free to send me an email or leave a comment, and I’ll update the  posts accordingly.

Figure 1. Reviewing the structure of a design and assigning tags to content.

Building an InDesign XML run-in template for repeating elements.

The design

Give your data meaningful names, in the Tags panel you’d add new tags for each of the XML elements. Consider using a DTD – Document Type Definition, to quickly insert all of the possible tags into the Tags panel without making any typos. DTD’s also enable you to validate the XML structure you create, or that is imported during XML import, against rules set in the DTD. For example a rule could be that a Dealer may must have nested elements for brand name, description, office details, phone listed in a fixed order.

If you are going to Map Tags to Styles as part of your template design, it is probably a good idea to create matching Tag and Style names in the template, as it makes adding the Tags to the panel a much easier task.

Building the structure

With the design element finished, you’re ready to get started with the build of the Structure and template.

If preferred, select the original Root tag in the Tag panel and rename it to your preferred name. The new name automatically updates the Root element name in the Structure panel.

To view the Tags panel, select Window > Tags. Double click the Root tag and rename it

One thing to keep in mind is that the XML list of car-dealers, when imported, will end up as text in a Text Frame. The default tag for a Text Frame or series of threaded text frames (a story) in case of a multi page or listing, is… you guessed it… the Story tag. This tag is a child tag, which means it is nested within the root tag. In the Structure panel that is indicated by the indentation.

The Story element itself will be the parent of all other elements. When you are basing the development of the InDesign run-in template on a sample document you’ve created, you can automatically add the Story element to the Tags panel and tag the Text Frame – instead of first adding a new Tag to the Tags panel, then adding this element to the Structure.

Figure 2. Adding an element to the Structure.

Automatic Tagging

Why tag things manually when we can do things ‘on-the-fly’ right? Select the Text Frame containing your single car dealer design content, and click the Autotag icon at the bottom of the Tags panel, or select Autotag from the panel menu.

Figure 3. Auto Tag Story

The Story Element is automatically added to the Structure panel and the Text Frame is now tagged.

If the Tag that’s added carries another name, then the default tag for Stories has been changed for the document you’re working on. To verify InDesign’s four default tags used for Story, Table, Cells and Images, select Tagging Preset Options from the Tags panel menu.

Figure 4. InDesign’s default Tagging Preset Options.

Ok, we’ve added one tag, but what about the rest of the XML elements that need to be inserted?

New tags

At this stage the Tags panel displays only the DealersList and Story tags. We need to add quite a few additional tags.

When you’re working with repeating elements, as is the case in this example, you would add a Tag to your Tags panel for the element that is the repeated element. In this example that is the dealer element, as you are going to use this template to run-in a list of all of the individual dealers for different brands of cars.

To add a new tag for the dealer, select New Tag… from the Tags panel menu or click the New Tag icon at the bottom of the panel. Name the Tag “dealer”.

Importing a DTD

I just remembered… isn’t it easier to use a DTD to add all the tags to the InDesign file? Rather than choosing the New Tag command each time, to insert a new tag? Absolutely! So let’s add the remainder of the tags used in this example by importing a DTD. Assuming you have a valid DTD available, select Load DTD… from the Tags panel menu and navigate to the .DTD file and click open… and all of the tags defined as part of the DTD are available.

An easy way to build the rest of the structure for your template and mark-up your template is to highlight content, then apply a tag.

Applying tags

First we need to highlight all of the content of the repeating element you’re working on, next click the repeating element tag (dealer) in the Tags panel to apply it.

Figure 6. Applying the repeating element tag to selected content.

The element will automatically nest below the Story element.

Next, based on the notes on which tags are going to be assigned to what text in your sample, highlight each of those components. I often work in the story editor when doing this as it much easier to see the tags that are marking up your sample content. To see the tags in the Story Editor ensure the Show Tag Markers is enabled from the View > Structure. Also enable Type > Show Hidden Characters, as it is easier to see if you have paragraph returns and other hidden characters selected when you are building your InDesign template.

Remember that your XML does not include paragraph returns and if you want the XML to run-in and replace some of your dummy text, it’s probably best to exclude the paragraph returns when selecting text to be marked with a tag. Doing so will ensure that during run-in those paragraph returns are inserted as per their position in the template.

Figure 7. Applying a tag to selected content.

Next you’re ready to continue marking up the rest of the text, in the story editor highlight the bits of sample text that are part of the template design and click the matching Tag in the Tags panel.

Continue to repeat this tagging process until you’ve completed the markup of text. Any text that needs to automatically be inserted as a prefix or suffix of a Tag, must be placed fully outside the tags. In my example that is the text “your local dealer” and the prefix ‘Phone:’

Once completed, you can replace the sample text with more relevant text for the template.

Figure 8. InDesign template design completed and ready for import of XML.

Import XML

You’ve now created a working InDesign template and can test it with some sample XML. To test the repeating elements function, create a small sample XML file that is extracted from the longer one and Import the XML, then review if you need to make any changes to your template.

To import XML, select File > Import XML or select Import XML from the Structure pane menu.

Ensure that you enable Clone repeating text elements in the XML Import Options and Do not import contents of whitespace-only elements options, and if you only want to import elements that match the structure you created in your template enable this setting as well.

If  the XML file you’re importing contains a reference to an XSLT or if you’ve been supplied an external XSLT you can apply this during import as well.

Most often XSLTs are used to transform any kind of XML to XML that is conform specified requirements. It can leave out elements from the source XML that are redundant and it can be used to sort XML content during import. For instance, in the scenario above, you might want to sort the XML by brand name during import.

Validate XML

Because we imported a DTD earlier as part of our template, we can validate the XML we’ve imported against this DTD.

To validate XML against a DTD, select Validate from the Structure pane menu. Validation can be applied from the Root element, which is the top-most element or from any selected element.

Where validation fails red markers flag invalid Elements in the Structure and a list of validation errors with suggested fixes is listed at the bottom of the Structure panel.