Work in progress — this reference is being written in the open. Unfinished pages are excluded from search engines.
Paged · IDML Reference
Layout model

Page items and stacking

What an IDML spread contains, and how the document order of its page items becomes back-to-front z-order at render time.

Intermediate· explanation

Page items are the visible shapes inside a spread, and the order they appear in the XML is their back-to-front stacking order.

In short: Inside a <Spread>, after its pages, come the page items — the visible shapes. The parser recognises five shape types as top-level page items (TextFrame, Rectangle, Oval, GraphicLine, Polygon), plus the <Group> that bundles several of them. The order they appear in the XML is not incidental: the first item is painted first and sits at the back, the last is painted last and sits at the front. That single rule — document order is z-order — is what lets a coloured rectangle act as a backdrop for a text frame declared after it.

The page-item types

A spread's items are sorted into one vector per shape type as the parser walks the XML:

  • <TextFrame> — a frame bound to a story by ParentStory; carries the text.
  • <Rectangle> — an axis-aligned vector frame, or the host for a placed image.
  • <Oval> — the ellipse inscribed in its bounds.
  • <GraphicLine> — a straight line between its bounds' corners.
  • <Polygon> — an arbitrary path, charts and rosettes included.

Each of these is a distinct element with its own geometry and paint attributes; those are documented under Frames & paths. What matters here is that they are siblings inside the spread, and that a <Group> may wrap any combination of them (including nested sub-groups) to apply one opacity, blend mode, or drop shadow to the whole cluster at once.

Document order is z-order

The parser keeps a single flat list of the spread's top-level items in the exact order it met them in the XML. The first item is painted first and therefore sits at the back; the last item is painted last and sits at the front. This back-to-front rule is what lets a coloured rectangle act as a backdrop for a text frame declared after it.

Group members are not duplicated into that top-level list — a group surfaces in it as a single entry, and the renderer brackets the group's members as a unit so the cluster keeps its internal order while compositing against the page as one layer.

Where layers bend the rule

Document order is the within-layer order. When items carry an ItemLayer reference, the layer stacking takes precedence: everything on a back layer paints before everything on a front layer, regardless of the per-shape XML order. Today the renderer treats layers as a flat back-to-front sequence — layer groups (nested layer folders) are flattened rather than honored as a hierarchy.

Parsed, not yet renderedLayer groups are flattened, not nested

Layers in full are covered under Layers.

Frames nested inside a group are handled; deeply nested text frames are counted

The grouping machinery records each group's members and composes their transforms, so grouped shapes render in place. One narrow case is still reported rather than rendered: a <TextFrame> discovered inside a <Group> in certain nestings is counted as a skipped frame so callers can detect the loss instead of silently dropping text.

Parsed, not yet renderedNested-in-group text frames may be reported as skipped

A worked example

The spread below holds two pages, each carrying its own text frame, and shares a master that contributes a header rule to each page. Read the spread part: the two <Page> elements come first, then the page items in document order.

A two-page spread. Each page applies the same master by its Self id, and each carries one text frame; document order within the spread sets the stacking.

Spreads/Spread_uspread.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<idPkg:Spread xmlns:idPkg="http://ns.adobe.com/AdobeInDesign/idml/1.0/packaging" DOMVersion="20.0">
  <Spread Self="uspread" PageCount="2" BindingLocation="1" ShowMasterItems="true" AllowPageShuffle="true" ItemTransform="1 0 0 1 0 0">
    <Page Self="upageL" Name="2" AppliedMaster="umaster" ItemTransform="1 0 0 1 -595.276 0" GeometricBounds="0 0 841.89 595.276" MasterPageTransform="1 0 0 1 0 0"/>
    <Page Self="upageR" Name="3" AppliedMaster="umaster" ItemTransform="1 0 0 1 0 0" GeometricBounds="0 0 841.89 595.276" MasterPageTransform="1 0 0 1 0 0"/>
    <TextFrame Self="uframeL" ParentStory="ustoryL" PreviousTextFrame="n" NextTextFrame="n" ContentType="TextType" AppliedObjectStyle="ObjectStyle/$ID/[None]" Visible="true" Name="$ID/" ItemTransform="1 0 0 1 -537.638 145.8237" FillColor="Swatch/None" StrokeColor="Swatch/None" StrokeWeight="0">
      <Properties>
        <PathGeometry>
          <GeometryPathType PathOpen="false">
            <PathPointArray>
              <PathPointType Anchor="0 0" LeftDirection="0 0" RightDirection="0 0"/>
              <PathPointType Anchor="0 400" LeftDirection="0 400" RightDirection="0 400"/>
              <PathPointType Anchor="480 400" LeftDirection="480 400" RightDirection="480 400"/>
              <PathPointType Anchor="480 0" LeftDirection="480 0" RightDirection="480 0"/>
            </PathPointArray>
          </GeometryPathType>
        </PathGeometry>
      </Properties>
    </TextFrame>
    <TextFrame Self="uframeR" ParentStory="ustoryR" PreviousTextFrame="n" NextTextFrame="n" ContentType="TextType" AppliedObjectStyle="ObjectStyle/$ID/[None]" Visible="true" Name="$ID/" ItemTransform="1 0 0 1 57.638 145.8237" FillColor="Swatch/None" StrokeColor="Swatch/None" StrokeWeight="0">
      <Properties>
        <PathGeometry>
          <GeometryPathType PathOpen="false">
            <PathPointArray>
              <PathPointType Anchor="0 0" LeftDirection="0 0" RightDirection="0 0"/>
              <PathPointType Anchor="0 400" LeftDirection="0 400" RightDirection="0 400"/>
              <PathPointType Anchor="480 400" LeftDirection="480 400" RightDirection="480 400"/>
              <PathPointType Anchor="480 0" LeftDirection="480 0" RightDirection="480 0"/>
            </PathPointArray>
          </GeometryPathType>
        </PathGeometry>
      </Properties>
    </TextFrame>
  </Spread>
</idPkg:Spread>

Frequently asked questions

What are page items in IDML? Page items are the visible shapes inside a spread. The parser recognises five top-level types — TextFrame, Rectangle, Oval, GraphicLine, and Polygon — plus the <Group> element that bundles several of them so one opacity, blend mode, or drop shadow applies to the whole cluster.

How is the stacking order of page items determined? By document order. The parser keeps a single flat list of the spread's top-level items in the exact order it met them in the XML; the first is painted first and sits at the back, the last is painted last and sits at the front. There is no separate z-index attribute — position in the XML is the stacking order.

Do layers change the stacking order? Yes. When items carry an ItemLayer reference, layer stacking takes precedence: everything on a back layer paints before everything on a front layer, regardless of per-shape XML order. Layer groups (nested layer folders) are currently flattened rather than honored as a hierarchy.

Spreads and pages

The IDML Spread and Page elements — the attributes that position a spread on the pasteboard and a page within its spread, and how the parser reads each one.

Master spreads

The IDML MasterSpread element — how a body page points at a master, and how master items get stamped onto body pages at render time.

On this page

The page-item typesDocument order is z-orderWhere layers bend the ruleFrames nested inside a group are handled; deeply nested text frames are countedA worked exampleFrequently asked questions