Page Hooks
XTS provides two hooks that let you run commands at specific points in a page’s lifecycle:
AtPageCreation
Commands inside <AtPageCreation> run when a new page is created, before any content is placed. This is the right place for:
- Background images or stationery
- Watermarks
- Repeating page headers or footers
<DefineMasterPage name="default" test="true()" margin="1cm">
<AtPageCreation>
<PlaceObject row="1" column="1" allocate="no">
<Image href="letterhead.pdf" width="210mm" height="297mm"/>
</PlaceObject>
</AtPageCreation>
</DefineMasterPage>AtPageShipout
Commands inside <AtPageShipout> run when a page is finalized and written to the PDF. This is the place for:
- Page numbers (you now know the final page number)
- Running headers with chapter titles
- Content that depends on what’s on the page
<DefineMasterPage name="default" test="true()" margin="1cm">
<AtPageShipout>
<PlaceObject column="{sd:number-of-columns()}" row="{sd:number-of-rows()}"
hreference="right" halign="right">
<TextBlock>
<Paragraph>
<Value select="sd:current-page()"/>
</Paragraph>
</TextBlock>
</PlaceObject>
</AtPageShipout>
</DefineMasterPage>Combining both
A typical setup uses <AtPageCreation> for the background and <AtPageShipout> for page-dependent content:
<DefineMasterPage name="standard" test="true()" margin="2cm 1cm 1cm 1cm">
<AtPageCreation>
<!-- Company logo in the top-right corner -->
<PlaceObject column="{sd:number-of-columns()}" row="1"
hreference="right" allocate="no">
<Image href="logo.pdf" width="3cm"/>
</PlaceObject>
</AtPageCreation>
<AtPageShipout>
<!-- Page number at the bottom center -->
<PlaceObject column="1" row="{sd:number-of-rows()}" allocate="no">
<TextBlock>
<Paragraph style="text-align: center;">
<Value select="sd:current-page()"/>
</Paragraph>
</TextBlock>
</PlaceObject>
</AtPageShipout>
</DefineMasterPage>When a hook is not needed
For static headers and footers there is a third option that needs no hook at all: the page margin boxes of a CSS @page rule, described in Page setup from CSS. They live in the page margin and never occupy grid cells, whereas a header placed in <AtPageCreation> at row 1 takes that row away from the content. Use a hook when the header needs a table, several paragraphs or values from the data.