The JSON Dataset

Definitions:

• Global: paper size, background color, header, footer
• Attribute: font, border, margin, padding, color, dir, file
• Primitives: bar, text, box, image, table, form fields

A number of global definitions, attribute and primitive pools followed by a page dictionary consisting of key value pairs called pages.
The page number serves as key for page definitions.

{
	...
	"pages": {
		"1": {...},
		"2": {...},
		"3": {...}
	}
}

You may either create a new PDF file or append or overlay existing pages.

Page Sequence Gaps

There may be gaps in the defined page sequence:

{
	...
	"pages": {
		"1": {...},
		"3": {...}
	}
}

• If you provide an existing input file, missing page definitions implied by page sequence gaps will only be appended but not modified.
  

• If you create a new PDF file, missing page definitions will result in blank pages.

Globals

Global flags & defaults

Global page defaults:

You may also define header and footer as part of the global section.

AttributePools

Different pages may share attributes like colors, fonts etc.
Attribute pools defined outside of the page sequence contain the definitions of named attributes and may serve as templates for inheritance. Eg. you may overwrite the font size or color at page/content level.

You may reference named attributes via name:$myName.

PrimitivePools

Different pages may share primitives like text, images etc.
Primitive pools defined outside of the page sequence contain the definitions of named primitives and may serve as templates for inheritance. Eg. you may overwrite the background color or font for a text at page/content level.

You may reference named primitives via name:$myName.

Page Definition

A number of page defaults, attribute and primitive pools followed by the content element.

Content

Optional attribute and primitive pools followed by arrays for each used primitive containing the positioned primitive instances aka. content elements:

For PDF form creation you may also add form fields:

Guides

You may also define an array of guides supporting you during your page design. A guide is a haircross at a specified position within your content box. You enable your guides using the global guides flag.

Getting Started

We start out by creating a simple page using A6 in landscape mode.
A page has a single content region per default.

We use the predefined coordinate system with its origin in the lower left corner of the content box and add a single text box positioned at (50/100) using 24 point Helvetica:

Border

A content region is surrounded by margin, border and padding.
We define the global border element which serves as default border for all content regions:

Margin And Padding

Let’s add margin and padding to the content region..
We define the global margin and padding elements which serve as default margin and padding for all content regions:

ContentBox

A page has a single content region per default.
The content box is the bounding box of a content region.

We highlight the content box in red by turning on the global contentBox flag. This flag also highlights the crop box in green.

If you have not specified a crop box using crop your crop box defaults to your media box which corresponds to the dimensions of your chosen paper size.

Debug

We highlight the position of all content elements by turning on the global debug flag. This is especially useful during the layout phase when using different alignments:

Origin

The default coordinate system has its origin in the lower left corner of the content box. You may choose either corner of the content box instead.

Warning
This does not change the fact that an elements position usually corresponds to its lower left corner!

Let’s switch the origin to the upper left corner.
We can achieve this using ul or upperleft and are not case sensitive:

Guides

There are a couple of pdfcpu features supporting you throughout your design phase. We already discussed contentbox and debug.

An important part during layout is defining your regions, and using guides lets you visualize them.

A guide is a haircross: a pair of horizontal and vertical lines intersecting at a certain position.

guides is an array of elements wrapping guide positions.
You need to enable guides rendering by turning on the global guides flag.

If you use -1 for one of the position coordinates pdfcpu will apply the center position for content box width/height:

Putting It All Together

Let’s finish up by extending this JSON in order to demonstrate text alignment:

align is an attribute of text.
The possible values are: left, center, right, justify
The default alignment is left.

We want to render a short text in the center of the page with three different alignments. We need three text boxes with corresponding alignment and also want to use different font colors. The rest of the used text attributes value, pos and font are all the same.
Let’s use a named text box defining value, pos and font and call it sample1.

We also want to render a multi line text box using all four possible alignments. This time we will use individual positions, alignment and width. The rest of the used text attributes value, font, bgcol, padding and border are shared.
Let’s use a named text box defining value, font, bgcol, padding and border and call it sample2.

We want to use Helvetica for all text boxes, so we define a named font and call it myFont. Font size and color will be overridden appropriately either within the text pool (texts) or within the final content elements: