Importing articles using path-based sidecar.xml files

There are two main methods for importing articles:

Importing articles from a folder — When you use this method, you specify either "Import a Single Article" or "Import Multiple Articles" in the Import Article dialog box, and you point to a folder containing the source files. With this method, properly structured filenames and folders is essential. When you select "Import Multiple Articles," specifying a sidecar.xml file that includes article metadata is optional; the classic sidecar.xml file needs to be on the same level as the article subfolders. For information about importing articles using this method, see Structuring folders for importing articles.

Importing articles specified in sidecar.xml — When you select "Import Using sidecar.xml" in the Import Article dialog box, you specify a sidecar.xml file that includes specific pathnames to files. This option is especially useful for importing InDesign documents with alternate layouts or for importing files from different locations. This method works only for InDesign CS6 and later.

Here is an example of a path-based sidecar.xml file for a dual-orientation folio. This example includes three different types of articles: an InDesign article with alternate layouts, a pair of _h and _v InDesign documents, and an HTML article.

Unfortunately, the Sidecar.xml Generator tool does not support the creation of the new path-based sidecar.xml format. We recommend that you download and edit the sample sidecar.xml file. Add and remove elements as needed.

Setting up the path-based sidecar.xml file

The entries in the path-based sidecar.xml file include <contentSource> elements that define the location of the source files. For InDesign articles, you specify the location and layout of the source files. For HTML articles, you specify the folder containing the HTML assets.

Each <entry> section defines the location and metadata of an article.

Pathname information (InDesign)

The <contentSource> section is where you specify the type and location of the source files of the article.

For <sourceFormat>, valid values include "indd" for InDesign source files and "html" for HTML source files.

For <customTocIcon>, specify the pathname of the TOC image file, if desired. If you want the TOC image to be generated, omit this element or do not include a value. Use the <customTocIcon> element only for InDesign files, not for HTML files. For HTML files, you simply include the TOC .png file in target folder on the same level as the .html file.

Create <sourceFile_v> sections for articles in vertical-only folios, <sourceFile_h> for articles in horizontal-only folios, or both sections for dual-orientation folios. Specify the pathname of the InDesign file in the <location> element. For documents with alternate layouts, specify the layout name (such as "iPad V") in the <layoutName> element as it appears in the InDesign Pages panel.

The <layoutName> element is required only for InDesign documents with alternate layouts. 

Valid pathname formats:

(Mac OS) /Users/johndoe/Documents/black box.indd
(Windows) C:\Users\johndoe\Documents\black box.indd

Pathname information (HTML)

When you import an HTML article, you specify the folder path in the <sourceFolder> element. The folder you specify should include a .html file, an optional TOC .png file, and other HTML assets in subfolders. Using _v and _h suffixes in the HTML filenames is necessary only if you want to display different HTML content in horizontal and vertical layouts. For example, you could add "index_v.html" and "index_h.html" files in the same folder.

Additional elements

Valid <isAd>, <isFlattenedStack>, and <isTrustedContent> values are “true” and “false.” The <isFlattenedStack> value determines whether Horizontal Swipe Only is turned on, and <isTrustedContent> determines whether the "Allow Access to Entitlement Information" option is selected for an HTML article.

Valid <smoothScrolling> values include “always,” “portrait,” “landscape,” and “never.” The default is “never,” which means scrolling snaps to pages.

Valid <articleAccess> values include "free," "metered," and "protected."

You can use either <byline> or <author> for the Byline metadata.

For <section> entries, specify a string of characters, such as “Lifestyle.”

The order of the <entry> sections determines the order of the articles in your folio when you create your folio or when you update it. The order of elements within each <entry> is insignificant.

Importing articles using path-based sidecar.xml file

Resolving sidecar.xml error messages

Invalid contentSource element in sidecar.xml

This error message appears in the following situations:

• The source files specified are not available or cannot be opened properly.
• The pathname includes one or more invalid characters. For example, if you use Terminal to copy the pathname, spaces in the pathname are preceded by a backslash (\). Remove these backslashes.
• You specified a <customTocIcon> element in an HTML article format.
  

For Import Using sidecar.xml, folderName element is invalid

You specified a classic sidecar.xml file instead of a path-based sidecar.xml file when using the "Import Using sidecar.xml" option. Either specify a path-based sidecar.xml file or use the Import Multiple Articles option as described in Structuring folders for importing articles.

For Import Multiple Articles, contentSource is invalid in sidecar.xml

If this error message appears, you selected Import Multiple Articles to import a folio folder containing a path-based sidecar.xml file. Either use a classic sidecar.xml file with the Import Multiple Articles option, or select the "Import Using sidecar.xml" option and specify the path-based sidecar.xml file.

The portrait/landscape layout for this article could not be found in the associated InDesign document

The value you specified for <layoutName> isn't valid. Open the InDesign document and check the layout name in the Pages panel, and then edit the sidecar.xml file.

Using path-based sidecar.xml files to update metadata

You can include the <metadataUpdateOnly/> element as an immediate child of the <sidecar> element to indicate that new articles are not to be created. If the <metadataUpdateOnly/> element is present, importing the sidecar.xml file updates the metadata of existing articles (as identified by the <articleName> values).

When <metadataUpdateOnly/> is specified, the <sourceFile_v>, <sourceFile_h> and <sourceFolder> elements are optional and are ignored if present.

To update metadata in existing articles, edit the sidecar.xml file, insert the <metadataUpdateOnly/> element immediately after the <sidecar> element, and then import the sidecar.xml file using the "Import Using sidecar.xml" option in the Import Article dialog box.