Import XML

For detailed information and instructions, click the links below.

After you import XML data, the imported content appears as elements (the basic building blocks of XML) in the Structure pane. InDesign doesn’t create new frames or pages when you import XML.

Append or merge?

You can import XML using one of two modes: append or merge. The method you choose depends on your workflow (manual or automated), how you want to handle existing content in your document, and whether you want advanced options for handling the imported data.

When you append imported content, the existing structure and content of the document are left as is; the new XML content is placed on the bottom of the Structure pane, in the form of elements.

When you merge imported content, InDesign compares the incoming XML with the structure and names of elements already in your document. If the elements match, imported data replaces existing document content, and is merged into correctly tagged frames (or placeholders) in the layout. (Elements for which InDesign can’t find a matching name and hierarchy rank are placed on the Structure pane so that you can place them manually.) Merge mode not only makes automated layout possible, it provides more advanced import options, including the ability to filter incoming text and clone elements for repeating data.

Content layout

After importing XML content, your next step is to place it in your document. You can place content manually, automatically, or by using scripting. The method you choose depends on the content you’re importing, your document’s layout, and your workflow process.

With the manual method, you drag elements from the Structure pane onto the pages of your document or into frames. This method requires little setup or planning. Use this method if the type of content you import varies or if you acquire content from multiple sources.

By planning ahead, you can automate the process of placing XML data in your layout. To place XML content automatically, you first prepare the document by creating tagged placeholder frames to hold incoming XML. As long as the XML structure and tag names for incoming content matches the tag names and structure of the placeholder frames, InDesign can place the imported XML automatically in your document. InDesign can also clone elements to handle repeating data, such as address lists and catalogue material. Use the automatic layout method as part of a structured workflow process to speed production time and efficiency.

About merging

You can place XML data in a document using merge mode or append mode. Merging mode allows you to automate the placement of content. You can also filter data in the XML file to place only certain parts of the content.

Merge incoming XML content when:

• The document contains placeholder frames and you want to fill them with imported XML content.

• The document contains XML content and you want to replace it with imported XML content.

• The document doesn’t contain any XML structure, and you want InDesign to replace the default root with the root of the incoming XML file.

Merge mode compares incoming XML data to elements already in the document. It moves through the file, element by element, comparing incoming elements to existing elements in the following manner:

1.InDesign begins comparing at the root element

• If the root elements of the imported XML file and InDesign document don’t match and the Structure pane contains no existing structure, InDesign replaces the root of the InDesign document with the root of the incoming XML file and imports the file.

• If the root elements don’t match and the Structure pane already contains elements, InDesign appends the file at the end of the existing structure.

• If the root elements do match, the merge (and matching) process moves forward.

2.InDesign moves to the element under the root

Starting with the element just beneath the root in the incoming XML file, InDesign searches for a matching element in the Structure pane. For a match to occur, the incoming XML element must have the same name as an existing element in the Structure pane, and the two elements must exist at the same level in the hierarchy.

• If InDesign finds a matching element in the Structure pane, it replaces the element in the Structure pane with the element from the incoming XML file.

• If InDesign doesn’t find a match, it inserts the incoming element in the Structure pane at the starting point of the search. For example, if the search begins just below the root and a match isn’t found, the incoming element is placed just below the root.

3.InDesign continues to compare elements

Element by element, InDesign continues to compare the incoming XML against the existing structure. The starting point for the search in the Structure pane changes as the search progresses, with each search beginning just below the last element inserted or replaced. InDesign always moves down from the current location; it never places elements above the previous element it inserted or replaced.

Import and append XML data

When you import XML content, the new elements appear in the Structure pane. From there, you can drag elements to place them in your document.

Lay out XML manually

You can manually place XML content in your document layout by dragging elements from the Structure pane to the page or to existing frames. When you place an element, its child elements (and all child elements below those, if any) are placed as well.

In the Structure pane, a structure-specific blue diamond appears on an element’s icon if the element has been placed in the document; elements that haven’t been placed show an unplaced icon.

Map XML tags to styles

XML tags are merely data descriptions; they carry no formatting instructions. As such, you need to format XML content after you import it and lay it out. One way to do that is to map XML tags to paragraph, character, table, or cell styles. For example, the Byline tag could be mapped to the Author character style, so that all imported and placed XML content that is tagged Byline is automatically assigned the Author character style. Mapping tags to styles makes formatting imported XML content easier and less time-consuming.

You don’t need to map every tag to a paragraph or character style. Some elements may not appear in the layout and others may be easier to format one at a time. Moreover, child elements take on the paragraph or character style that is assigned to their parent, which can cause confusion unless you are careful to map parent and child elements separately.

About automatic layout

Using InDesign, you can automatically place imported XML content into a layout. To do this, you first create placeholder frames or tables, and tag them with the same tag names as the XML elements you want to place into them. Then, you import XML content into the placeholders in Merge mode. When tags match by name and by structural hierarchy, InDesign merges the XML content, replacing any existing content in the document.

This technique is useful when you want to use the same layout for different sets of content. For example, a weekly newsletter may have the same layout from week to week, but offer different content with each publication.

In order for imported XML to be merged directly into a layout, your document must meet these requirements:

• Frames (or tables) in the document must be tagged with names identical to elements in the XML file that you intend to import.

• The structure of the document (as shown in the Structure pane) must parallel the structure of the imported XML file. In other words, the identically named elements must be found in the same locations in the structure hierarchy of both files. To achieve this parallel structure, you may have to rearrange and reorder elements (and their child elements) in the Structure pane or use the Apply XSLT option when you import the XML file.

Work with repeating data

XML is repeating if the same configuration of elements appears multiple times in a row, but contains unique data in each instance. For example, database records are repeating. Addresses in a database table contain repeated information—name, street address, city, state, postal code—for a variety of individuals.

When you import XML content, you can select Clone Repeating Text Elements in the XML Import Options dialog box. Selecting this option tells InDesign to clone the repeated elements in the structure. Cloning allows you to merge repeating XML data into a document without having to create placeholder elements in the Structure pane (or placeholder text in a frame) for every single record. For example, to import an XML address list with 25 entries, create a matching element structure for one entry in the Structure pane. When you import the complete list, InDesign clones that structure to create elements for all 25 entries.

Repeating XML content is flowed as a single story when it is merged into the document. If placeholder frames have been threaded together, the content is flowed from one frame to the next. If there isn’t enough room in the placeholder frame(s) to accommodate the XML content, you can autoflow the remaining content by creating and threading more frames; you don’t have to manually drag elements from the Structure pane into individual frames.

Create placeholders for automatic layout

Create placeholder frames or tables in your document when you want InDesign to automatically merge imported XML into your layout.

You can also create placeholder text to ensure XML data is placed and formatted correctly on the page. Placeholder text can also be used to include tabs, spacing, or labels (called static text) between the XML elements that will appear in a frame.

For example, if you are importing and placing product information, you can separate the name, description, and price of the product with a tab, and include labels such as “Product:” or “Price:” before the placeholder text entries for those elements. When XML data is merged into the frame, static labels, spacing, and tabs are preserved between the content elements.

Create a placeholder frame

Create a placeholder table

You can import XML elements into a placeholder table as well as a placeholder frame. In a table, each cell is represented by an element. InDesign places XML content into the table cell by cell, element by element, starting from the top left corner of the table, matching the element to the tagged cell. When creating placeholder tables, you must tag the table as well as each cell in the table. (Merged cells are considered a single cell.)

Because InDesign doesn’t distinguish between rows and columns when importing, the number of columns in the placeholder must match the number of columns in the imported content. Also, all the table cell elements must be contained within a single table element. In other words, the cells are all sibling elements under the same parent.

Create placeholder structure for repeating data

The same rules for merging XML also apply when merging repeating XML: The structure of the elements in the Structure pane must parallel the structure of the imported XML data, and any placeholder frames must be tagged with the same tag names as the parent elements in the XML file.

Create placeholder text

Import and merge XML

After you have created and tagged placeholder frames, tables, and text—and made sure that your document and the incoming XML file have the same tags and structure—you can import XML content into your layout.

You must use the Merge Content option to import XML into placeholders (or to replace existing content in your document). When merging content, InDesign replaces identically tagged and structured elements in your document with the imported XML elements. You can use additional import options to exclude imported (that is, filter) content that doesn’t match the document structure, to delete document items that aren’t matched or replaced by the imported XML, and to clone repeating XML elements.

If the imported XML file contains elements that are not found in the document, InDesign places these elements in the Structure pane without laying them out in your document.

To successfully merge XML into placeholders, keep these rules in mind:

• Tag placeholders with the identical tag name as the XML element that will replace it (or be flowed into it).

• In placeholder text, make sure any spacing, returns, tabs, or static text is outside the placeholder element tags, but within the parent element for the story.

• When you import the XML, select Do Not Import Contents Of Whitespace-Only Elements. (This preserves spacing and static text if the XML elements you import consist of white spaces only.)

Merge XML into existing content or placeholders

InDesign merges content into the document starting with the first matching element in the XML file.

XML Import options

When importing and placing XML data using the Merge Content option, the XML Import Options dialog box offers the following options:

Links to the XML file so that if the XML file is updated, you can update its XML data in your InDesign document.

Applies a stylesheet to define the transformation of the imported XML. Select Browse (Windows) or Choose (Mac OS) to select an XSLT file (.xsl or .xslt) from the file system. Use Stylesheet From XML, the default option, causes InDesign to use an XSLT processing instruction, if one is present in the XML file, to transform the XML data.

Replicates the formatting applied to tagged placeholder text for repeating content. Create one formatting instance (for example, an address), and then reuse its layout to create other instances automatically. (See Working with repeating data.)

Filters the imported XML content so that only elements from the imported XML file with matching elements in the document are imported.

Imports elements into a table if the tags match the tags applied to the placeholder table and its cells. For example, use this option to place database records into a table when generating price lists or inventory sheets.

Leaves any existing content in place if the matching XML content contains only whitespace (such as a return or tab character). Use this option if you’ve included text between elements in your placeholder frames and you want to preserve this text. For example, when laying out recipes generated from a database, you might add labels such as “Ingredients” or “Instructions.” As long as the parent element that wraps each recipe contains only whitespace, InDesign leaves the label in place.

Removes elements from the Structure pane and the layout of the document if they don’t match any elements in the imported XML file. Use this option to filter data from the document. For example, when importing names and addresses, you might have placeholder text for an element containing the company name. If one of the names doesn’t include the company element, InDesign deletes the element containing the placeholder text.

Imports any CALS tables in the XML file as InDesign tables.