What is an IDML file?

This document is about the big picture: what an IDML file actually is, how it is structured, and how the IDML-Creator maps that structure to PHP objects. If you already have experience with InDesign documents, you can skim this chapter and jump straight into the Quickstart.

Table of contents

The big picture

IDML stands for InDesign Markup Language. It is an XML-based file format that describes an InDesign document: its pages, its object frames, its text, its colors and its styles. An IDML file is always a ZIP package that contains several XML files. InDesign opens such a package like any other document — and the IDML-Creator writes one for you.

The format is defined by the official idml-specification. Two parts of it matter most for the daily work with this library:

  1. Chapter 4 describes the package structure and what each file inside it means.
  2. Appendix D (datatype.rnc) lists every enumeration value that attributes may use. The IDML-Creator ships most of them as PHP enums — see the enums chapter.

The package structure

When the writer has created your file, the package looks like this:

META-INF/container.xml   defines this ZIP package as an IDML package
designmap.xml            the design map, references all other parts
backingstory.xml         the backing story, holds master and shared content
spread_XXXX.xml          one file per spread, containing the pages and their objects
story_XXXX.xml           one file per story (the text flow)
styles.xml               all paragraph, character, table and cell styles
tags.xml                 the XML tags
preferences.xml          the document settings
metadata.xml             the document metadata

Mapping IDML to the IDML-Creator

Every part of the package has a counterpart in the library. That is why the documentation index follows the same structure:

IDML part IDML-Creator class Chapter
designmap.xml DesignMap designmap
backingstory.xml BackingStory designmap
preferences.xml Preference preference
metadata.xml MetaData metadata
tags.xml Tag designmap
spread_XXXX.xml Spread, Page, Layer pages
styles.xml ParagraphStyle, CharacterStyle, TableStyle, CellStyle, ObjectStyle styling text, styling objects
story_XXXX.xml Story + ranges typography

The Content object is the root that collects every single part — it is the document you hand over to the writer. The easiest way to get one is the Factory:

<?php

use BitAndBlack\IdmlCreator\Factory;

$factory = new Factory();

The factory registers every object you ask it to create immediately in its Content object. You hand that over to the writer at the end — the workflow chapter shows how.