Styling text

This document is about how to style text. In IDML, all formatting lives in styles — not directly in the text. There are paragraph styles (for whole paragraphs), character styles (for parts of them) and the fonts both of them use. How the styles are applied to real text is described in the typography chapter.

Table of contents

Paragraph styles

Set up a ParagraphStyle object with the Factory — it is registered in the Content object automatically:

<?php

use BitAndBlack\IdmlCreator\Factory;

$factory = new Factory();

$paragraphStyle = $factory->createParagraphStyle();

If you want to set your own unique identifier — which is recommended here — create the ParagraphStyle like that: $factory->createParagraphStyle('UniqueName');. The name is what you will see in the InDesign UI, so give it a readable one like Body or Footnote.

A paragraph style knows how its text looks and how the paragraph behaves. A full example looks like that:

<?php

use BitAndBlack\IdmlCreator\Content\Enum\CornerOptions;
use BitAndBlack\IdmlCreator\Content\Enum\StrokeType;

/** @var \BitAndBlack\IdmlCreator\Content\Color\Color $black a color, created in the "colors" chapter */
/** @var \BitAndBlack\IdmlCreator\Content\Language\Language $language a language, created in the "designmap" chapter */
/** @var \BitAndBlack\IdmlCreator\Content\Color\Color $red a color, created in the "colors" chapter */
$paragraphStyle = $factory->createParagraphStyle('Body')
    ->setPointSize(12)
    ->setLineHeight(18)
    ->setFillColor($black)
    ->setAppliedLanguage($language)
    ->setParagraphShadingOn(true)
    ->setParagraphShadingColor($red)
    ->setParagraphBorderOn(true)
    ->setParagraphBorderType(StrokeType::DASHED)
    ->setParagraphBorderTopRightCornerOption(CornerOptions::BEVEL)
;

A style can be chained so that the following paragraph automatically gets the next style:

<?php

/** @var \BitAndBlack\IdmlCreator\Content\Style\ParagraphStyle $paragraphStyle a paragraph style, created above */
/** @var \BitAndBlack\IdmlCreator\Content\Style\ParagraphStyle $followingParagraphStyle the style that the following paragraph should get */
$paragraphStyle->setNextStyle($followingParagraphStyle);

The deepest properties

A paragraph style exposes more than one hundred properties. The deepest of them mirror the attributes of the <ParagraphStyle> element in the IDML specification (Appendix D, datatype.rnc). One example is the positional form — it decides which glyph of an Arabic or Hebrew character is used:

<?php

use BitAndBlack\IdmlCreator\Content\Enum\Styles\PositionalForm;

/** @var \BitAndBlack\IdmlCreator\Content\Style\ParagraphStyle $paragraphStyle a paragraph style, created above */
$paragraphStyle->setPositionalForm(PositionalForm::INITIAL);

Since IDML-Creator v5.8 this method accepts the PositionalForm enum. The enum values are identical to the strings of previous versions, so existing code keeps working — a deprecation notice tells you to switch. All enum values are gathered in the enums chapter.

Character styles

A character style styles parts of a paragraph — a keyword, a highlighted word. Set it up like the paragraph style:

<?php

/** @var \BitAndBlack\IdmlCreator\Factory $factory the factory, initialized in the "Paragraph styles" section */
$characterStyle = $factory->createCharacterStyle();

Recommended: $factory->createCharacterStyle('UniqueName');

A typical example:

<?php

/** @var \BitAndBlack\IdmlCreator\Content\Color\Color $red a color, created in the "colors" chapter */
/** @var \BitAndBlack\IdmlCreator\Content\Font\FontStyle $myriadProBold a font style, set up like in the "fonts" section below */
$boldRed = $factory->createCharacterStyle('Bold + Red')
    ->setFillColor($red)
    ->setFontStyle($myriadProBold)
;

Like paragraph styles, they can be chained with setNextStyle().

Fonts

Every font consists of a font family and a font style. Those are two different objects in IDML-Creator, and those two can be handled differently in InDesign. Set them up like that:

<?php

use BitAndBlack\IdmlCreator\Content\Font\FontFamily;

/** @var \BitAndBlack\IdmlCreator\Factory $factory the factory, initialized in the "Paragraph styles" section */
$helveticaNeue = new FontFamily('Helvetica Neue');
$helveticaNeueRegular = $factory->createFontStyle($helveticaNeue, 'Helvetica Neue Regular');
$helveticaNeueItalic = $factory->createFontStyle($helveticaNeue, 'Helvetica Neue Italic');

The factory registers both font styles in the content automatically. Family name and style name are required attributes here.

Using fonts in styles

The font family and the font style can be used in styles like that:

<?php

/** @var \BitAndBlack\IdmlCreator\Content\Style\ParagraphStyle $paragraphStyle a paragraph style, created above */
/** @var \BitAndBlack\IdmlCreator\Content\Font\FontFamily $helveticaNeue the font family created above */
/** @var \BitAndBlack\IdmlCreator\Content\Font\FontStyle $helveticaNeueRegular the font style created above */
$paragraphStyle
    ->setFontFamily($helveticaNeue)
    ->setFontStyle($helveticaNeueRegular)
;

/** @var \BitAndBlack\IdmlCreator\Content\Style\CharacterStyle $characterStyle a character style, created above */
/** @var \BitAndBlack\IdmlCreator\Content\Font\FontStyle $helveticaNeueItalic the italic font style created above */
$characterStyle
    ->setFontStyle($helveticaNeueItalic)
;

It's not important here if a font is available on a system!

Sending fonts along

If you want to provide fonts along with your idml files, create a folder Document fonts in the same directory. When opening an idml (or indd) file, InDesign will look for this folder and activate all fonts inside.