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.
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.
Place content manually
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.
Place content automatically
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.
InDesign recognizes special namespace attributes that can specify paragraph or character styles in XML. For more information, see the XML technical reference guide.
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.
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.
InDesign will list the XML file in the Links panel and display a yellow alert triangle in the panel if the XML file changes.
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.
If you imported XML using the Merge Content option, some elements may already be laid out. When you merge imported content, InDesign automatically flows elements into existing frames if they are identically structured and tagged.
Drag the element onto the page. InDesign creates a frame for the element.
Drag the element onto an existing frame. If the frame contains content, it is replaced by content from the XML data.
Map XML tags to paragraph, character, table, and cell styles.
Apply styles to elements.
Format the selected content manually by choosing text options in the Control panel.
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.
The Map Tags To Styles command reapplies styles throughout a document, sometimes with unwanted results. When you map a tag to a style, text that was previously assigned to one style may be reassigned to another, depending on its XML tag. If you’ve already formatted some text, you might prefer to apply styles manually to prevent your paragraph and character style choices from being overridden.
To import styles, tags, and mapping definitions from another document, click Load, choose a document, and click Open.
To map tags to styles individually, click the Style column adjacent to a tag, and choose a paragraph or character style from the menu that appears. (The paragraph symbol identifies paragraph styles in the menu; an “A” identifies character styles.) Repeat for each tag you want to map.
To automatically map tags to styles with the same names, click Map By Name. Styles with names that are identical to tag names are selected in the Style column. To match, a tag and style must not only have the same name, but the same case; H1 and h1, for example, are not considered a match. (If the same style name exists in two different style groups, Map By Name doesn’t work and you are alerted to rename one of the styles.)
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.
InDesign flows merged XML content into existing frames only. Any element content that doesn’t fit in its frame (or series of threaded frames) becomes overset text.
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 placeholder frames or tables in your document when you want InDesign to automatically merge imported XML into your layout.
InDesign flows merged XML content into existing frames only. Any content that doesn’t fit in the frames provided becomes overset text.
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.
A. Returns and static text added between elements B. Placeholder text
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.
If you merge repeating XML data into your document and instruct InDesign to clone repeating elements, the static text and spacing are also cloned for each instance of the data.
If you want imported XML content to flow from one frame to another, create multiple frames and thread them together.
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.
At a minimum you must have tags for the parent element of the table cells, the table cells, and the element in which the table will reside.
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.
A. Element that will contain all repeated elements B. Element that will be cloned as repeating XML content is imported C. Child elements for data contained in the repeating element
For example, a Chapter element that will contain a series of recipes.
For example, under the Chapter element, you might create a Recipe element. This is the element that will be cloned for each record in the imported XML.
For example, under the Recipe element, you might create Recipename, Ingredients, Instructions, Notes, and Serving elements.
To include labels, returns, or tabs between “field” elements in the repeating XML data, create placeholder elements in the frame the imported content will be merged into. And add spacing or labels as needed between the placeholders.
Importing a sample of the XML content is the easiest way to obtain all the necessary tags and to ensure that the document structure matches the XML file.
If you will be importing repeating data, you only need to create one instance of sample text for the elements that will repeat.
InDesign wraps the placeholder text with the tag, and adds the element to the Structure pane.
When tagging placeholder text, do not select any spacing or static text you want to keep between elements. Tag only the text you want replaced with XML content.
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.)
InDesign will list the XML file in the Links panel and display a yellow alert triangle in the panel if the XML source file changes.
Clone Repeating Text Elements
If you are importing repeating XML, clones a single placeholder element to create a container for each record in the file.
Only Import Elements That Match Existing Structure
Filters the incoming XML, so that elements that do not exist in the Structure pane are not imported.
Do Not Import Contents Of Whitespace-Only Elements
Preserves any spacing or static text inserted between elements in a placeholder frame.
Delete Elements, Frames, And Content That Do Not Match Imported XML
After XML has been imported, deletes any elements or placeholders in your document that were not matched (or replaced) by incoming data.
InDesign merges content into the document starting with the first matching element in the XML file.
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.
Clone Repeating Text Elements
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.)
Only Import Elements That Match Existing Structure
Filters the imported XML content so that only elements from the imported XML file with matching elements in the document are imported.
Import Text Elements Into Tables If Tags Match
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.
Do Not Import Contents Of Whitespace-only Elements
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.
Delete Elements, Frames, and Content That Do Not Match Imported XML
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.
Import CALS Tables As InDesign Tables
Imports any CALS tables in the XML file as InDesign tables.