Quickstart

Table of contents

• The basic setup
• The document preferences
• A color
• The styles
• The story
• The TextFrame
• Page, Spread and the final composition
• Opening the result

The basic setup

An IDML file is a ZIP package that Adobe InDesign understands. With the IDML-Creator you never build that package by hand — you describe its individual parts with PHP objects and hand them to a Writer at the end.

The core of every document is the Content object. It collects all parts, comparable to the designmap.xml in the final IDML package. The easiest way to get one is the Factory — every object you ask it to create is registered in its Content object automatically:

<?php

use BitAndBlack\IdmlCreator\Factory;

$factory = new Factory();

The document preferences

The Preference object describes the paper. In this guide we create a single-paged A4 document with a 3 mm bleed:

<?php

use BitAndBlack\IdmlCreator\Content\Enum\Unit;

$preference = $factory->getPreference()
    ->setSinglePage(true)
    ->setDocumentFormat(210, 297, Unit::MILLIMETERS)
    ->setDocumentBleed(3, Unit::MILLIMETERS)
;

Note how the unit is passed as the last parameter — numbers stay in points per default, Unit::MILLIMETERS makes them readable.

A color

Colors are needed for text, shapes and strokes. A Color holds a value and a model. Pass the unique identifier — Green, Red — as the first parameter:

<?php

use BitAndBlack\IdmlCreator\Content\Enum\Color\Model;
use Color\Value\CMYK;

$green = $factory->createColor('Green')
    ->setColorValue(
        new CMYK(100, 0, 100, 0)
    )
    ->setModel(Model::PROCESS)
;

$red = $factory->createColor('Red')
    ->setColorValue(
        new CMYK(0, 100, 100, 0)
    )
    ->setModel(Model::PROCESS)
;

This creates the process colors Green and Red and registers them in the content. Keep the names unique, they become the identifiers inside the IDML file.

The styles

In IDML, all formatting lives in styles, not in the text itself. We create a paragraph style for Body text and a character style for Bold + Red words:

<?php

use BitAndBlack\IdmlCreator\Content\Font\FontFamily;

$myriadPro = new FontFamily('Myriad Pro');
$myriadProRegular = $factory->createFontStyle($myriadPro, 'Regular');
$myriadProBold = $factory->createFontStyle($myriadPro, 'Bold');

/** @var \BitAndBlack\IdmlCreator\Content\Color\Color $green the process color created in the "A color" section */
/** @var \BitAndBlack\IdmlCreator\Content\Color\Color $red the process color created in the "A color" section */
$boldRed = $factory->createCharacterStyle('Bold + Red')
    ->setFillColor($red)
    ->setFontStyle($myriadProBold)
;

$paragraphStyle = $factory->createParagraphStyle('Body')
    ->setPointSize(12)
    ->setLineHeight(18)
    ->setFillColor($green)
    ->setFontFamily($myriadPro)
    ->setFontStyle($myriadProRegular)
;

Every style is a separate object that can be reused. The factory registers them all in the content. More in the styling text chapter.

The story

A Story is the text flow. It is built from ranges: a paragraph style range, and inside it, character style ranges. The factory registers the story in the content immediately:

<?php

use BitAndBlack\IdmlCreator\Content\Story\CharacterStyleRange;
use BitAndBlack\IdmlCreator\Content\Story\ParagraphStyleRange;
use BitAndBlack\IdmlCreator\Content\Story\Text;

/** @var \BitAndBlack\IdmlCreator\Content\Style\ParagraphStyle $paragraphStyle the paragraph style created in the "The styles" section */
/** @var \BitAndBlack\IdmlCreator\Content\Style\CharacterStyle $boldRed the character style created in the "The styles" section */
$story = $factory->createStory()
    ->addContent(
        new ParagraphStyleRange(
            $paragraphStyle,
            new CharacterStyleRange(
                null,
                new Text("Hello World! We're happy to have you here! This document was created by ")
            ),
            new CharacterStyleRange(
                $boldRed,
                new Text('IDML-Creator')
            )
        )
    )
;

The TextFrame

A story only exists inside a TextFrame. Place the frame, give it a size and link the story:

<?php

use BitAndBlack\IdmlCreator\Content\Enum\Unit;
use BitAndBlack\IdmlCreator\Content\TextFrame\TextFrame;

/** @var \BitAndBlack\IdmlCreator\Content\Story\Story $story the story created in the "The story" section */
$textFrame = new TextFrame();
$textFrame
    ->setPosition(20, 20, Unit::MILLIMETERS)
    ->setSize(170, 257, Unit::MILLIMETERS)
    ->setParentStory($story)
    ->setColumns(1, 10, Unit::MILLIMETERS)
;

Page, Spread and the final composition

Text frames and shapes live on pages, pages live on spreads. Everything the factory creates is already registered in its content. Only the DesignMap — with a Language on it, which is required so InDesign knows which dictionaries to use — needs this one extra setup. The Tag, the Container and the BackingStory are added automatically by the IDML-Creator, you don't need to create them:

<?php

use BitAndBlack\IdmlCreator\Content\Enum\Spread\PagePosition;
use BitAndBlack\IdmlCreator\Content\Enum\Unit;
use BitAndBlack\IdmlCreator\Content\Enum\Content\Language as LanguageEnum;
use BitAndBlack\IdmlCreator\Content\Language\Language;
use BitAndBlack\IdmlCreator\Content\Page;
use BitAndBlack\IdmlWriter\File\Tree;
use BitAndBlack\IdmlWriter\Writer;

$factory->getDesignMap()
    ->addLanguage(
        new Language(LanguageEnum::ENGLISH_UK)
    )
;

$page = new Page();
$page
    ->setFormat(210, 297, Unit::MILLIMETERS)
    ->addElement($textFrame)
;

$factory->createSpread()
    ->addPage($page, PagePosition::RIGHT)
;

/** @var \BitAndBlack\IdmlCreator\Content\TextFrame\TextFrame $textFrame the text frame created in the "The TextFrame" section */
/** @var \BitAndBlack\IdmlCreator\Content\Preference $preference the preference created in the "The document preferences" section */
$writer = new Writer(
    $factory->getContent(),
    new Tree()
);
$writer->create(__DIR__ . DIRECTORY_SEPARATOR . 'example.idml');

The whole example — extended by a few details — is available under singlePage.

Opening the result

The writer creates a ZIP archive with the .idml extension. InDesign opens it like any other document. Inside the package you find the parts we have described:

META-INF/container.xml   defines this zip as an IDML package
designmap.xml            the design map, references all other parts
backingstory.xml         the backing story
spread_1.xml             the spread with the page and the TextFrame
story_1.xml              the story with the text
styles.xml               the paragraph and character styles
tags.xml                 the tags
preferences.xml          the document settings
metadata.xml             the document metadata

You don't need to touch this structure — but it explains why the API looks the way it does. The Factory took care of all the registering for you: every object it created is part of the content you handed to the writer.