Search Docs
Loading...
Skip to content

Pages

Pages define the format of your designs — every graphic block, text element, and media file lives inside a page. This guide covers how pages fit into the scene hierarchy, their properties like margins and title templates, and how to configure page dimensions for different layout modes.

10 mins
estimated time
GitHub

Pages provide the canvas and frame for your designs. Whether you’re building a multi-page document, a social media carousel, or a video composition, understanding how pages work helps you structure content correctly.

This guide covers:

  • Understanding the scene hierarchy: Scene → Pages → Blocks
  • Creating and managing multiple pages
  • Setting page dimensions at the scene level
  • Configuring page properties like margins and title templates
  • Navigating between pages programmatically

Pages in the Scene Hierarchy#

In CE.SDK, content follows a strict hierarchy: a scene contains pages, and pages contain content blocks. Only blocks attached to a page are rendered on the canvas.

// Create a scene with VerticalStack layout for multi-page designs
let scene = try engine.scene.create(sceneLayout: .verticalStack)


// Configure spacing between pages
let stacks = try engine.block.find(byType: .stack)
let stack = stacks[0]
try engine.block.setFloat(stack, property: "stack/spacing", value: 20)
try engine.block.setBool(stack, property: "stack/spacingInScreenspace", value: true)

When you create a scene with a layout mode like verticalStack, pages are automatically arranged according to that mode. Create pages using engine.block.create(.page), set their dimensions with setWidth() and setHeight(), then attach them to the scene’s stack container with engine.block.appendChild(to:child:).

// Create the first page and set its dimensions
let firstPage = try engine.block.create(.page)
try engine.block.setWidth(firstPage, value: 800)
try engine.block.setHeight(firstPage, value: 600)
try engine.block.appendChild(to: stack, child: firstPage)


// Create the second page with the same dimensions
let secondPage = try engine.block.create(.page)
try engine.block.setWidth(secondPage, value: 800)
try engine.block.setHeight(secondPage, value: 600)
try engine.block.appendChild(to: stack, child: secondPage)

Content blocks must be added as children of a page to render. For graphic blocks, set both a shape and a fill for content to display. Append blocks to the page before configuring their properties.

// Add an image block to the first page
let imageBlock = try engine.block.create(.graphic)
try engine.block.appendChild(to: firstPage, child: imageBlock)


// Create a rect shape for the graphic block
let rectShape = try engine.block.createShape(.rect)
try engine.block.setShape(imageBlock, shape: rectShape)


// Configure size and position after appending to the page
try engine.block.setWidth(imageBlock, value: 400)
try engine.block.setHeight(imageBlock, value: 300)
try engine.block.setPositionX(imageBlock, value: 200)
try engine.block.setPositionY(imageBlock, value: 150)


// Create and configure the image fill
let imageFill = try engine.block.createFill(.image)
try engine.block.setURL(
  imageFill,
  property: "fill/image/imageFileURI",
  value: baseURL.appendingPathComponent("ly.img.image/images/sample_1.jpg"),
)
try engine.block.setFill(imageBlock, fill: imageFill)


// Add a text block to the second page
let textBlock = try engine.block.create(.text)
try engine.block.appendChild(to: secondPage, child: textBlock)


// Configure text properties
try engine.block.replaceText(textBlock, text: "Page 2")
try engine.block.setTextFontSize(textBlock, fontSize: 48)
try engine.block.setTextColor(textBlock, color: .rgba(r: 0.2, g: 0.2, b: 0.2, a: 1.0))
try engine.block.setEnum(textBlock, property: "text/horizontalAlignment", value: "Center")
try engine.block.setWidthMode(textBlock, mode: .auto)
try engine.block.setHeightMode(textBlock, mode: .auto)

Page Dimensions and Consistency#

The CE.SDK engine supports pages with different dimensions. When using stacked layout modes (verticalStack, horizontalStack), the Editor UI expects all pages to share the same size. With the free layout mode, you can set different dimensions for each page in the UI.

// Set page dimensions at the scene level (all pages share these dimensions)
try engine.block.setFloat(scene, property: "scene/pageDimensions/width", value: 800)
try engine.block.setFloat(scene, property: "scene/pageDimensions/height", value: 600)

Set default page dimensions at the scene level using engine.block.setFloat(_:property:value:) with scene/pageDimensions/width and scene/pageDimensions/height. The scene/aspectRatioLock property controls whether changing one dimension automatically adjusts the other. Individual pages can also have their dimensions set directly with setWidth() and setHeight().

Finding and Navigating Pages#

CE.SDK provides several methods to locate and navigate between pages in your scene.

// Get all pages in sorted order
let allPages = try engine.scene.getPages()
print("All pages:", allPages)
print("Number of pages:", allPages.count)


// Get the current page (nearest to viewport center or containing selection)
let currentPage = try engine.scene.getCurrentPage()
print("Current page:", currentPage as Any)


// Find pages using the block API
let pagesByType = try engine.block.find(byType: .page)
print("Pages found by type:", pagesByType)

Use these methods based on your needs:

  • engine.scene.getPages() returns all pages in sorted order
  • engine.scene.getCurrentPage() returns the page containing the current selection, or the page nearest to the viewport center
  • engine.block.find(byType: .page) finds all page blocks in the scene

Page Properties#

Each page has its own properties that control its appearance and behavior. These are set on the page block itself, not on the scene.

Margins#

Page margins define bleed areas useful for print designs. Enable margins and configure each side individually:

// Enable and set margins for print bleed on the first page
try engine.block.setBool(firstPage, property: "page/marginEnabled", value: true)
try engine.block.setFloat(firstPage, property: "page/margin/top", value: 10)
try engine.block.setFloat(firstPage, property: "page/margin/bottom", value: 10)
try engine.block.setFloat(firstPage, property: "page/margin/left", value: 10)
try engine.block.setFloat(firstPage, property: "page/margin/right", value: 10)

Set page/marginEnabled to true to enable margins, then use page/margin/top, page/margin/bottom, page/margin/left, and page/margin/right to configure each side.

Safety Inset#

The safety inset is the inward inset from the page edge that content must stay inside. It is the counterpart of the bleed margin, which extends outward. Print shops cut with a tolerance, so text and logos placed too close to the edge can be trimmed off.

Set page/safetyEnabled to true, then use page/safetyInset/top, page/safetyInset/bottom, page/safetyInset/left, and page/safetyInset/right to configure each side. Every inset defaults to 0, so set a value as well as enabling the area.

The safety inset is authoring state, and nothing it draws reaches an export.

The guide appears while a drag is in the safety inset or comes near the safety line, and goes away when the drag ends. A move or resize with the arrow keys shows it the same way for 1.6 seconds, without snapping. The engine shades the band between the page edge and the line, draws the line itself, and lets the dragged block snap to it. Set page/safetyRevealDuringTransform to false to draw the guide on every page all the time instead.

Set the guide colors with the page/safetyFillColor and page/safetyFrameColor settings; a fully transparent page/safetyFrameColor hides the line and turns its snapping off.

Exclusion Area#

An exclusion area marks a region of a page that content must stay out of: a window on an envelope, a spine on a book cover, a glue flap on a box, an address panel on a mailer. Where the safety inset is one inset per page, a page can carry any number of exclusion areas, each with its own position, size and rotation.

Create one with the //ly.img.ubq/exclusionArea block type and append it to a page. An exclusion area is a graphic, so it takes a shape, a fill, a stroke and the ordinary transform, and you can put the artwork of the obstruction into it. A new exclusion area is a rectangle with no fill and shows a striped pattern, so it is visible at once. Assign a fill to replace the stripes.

An exclusion area is authoring state. The engine washes it in page/exclusionAreaFillColor and frames it in page/exclusionAreaFrameColor, neither of which reaches an export, and a fully transparent page/exclusionAreaFrameColor hides the frame. An exclusion area is left out of an export as well: set includedInExport to true on the exclusion area to put its artwork in the file.

Set exclusionArea/punchOut to true to cut the exclusion area out of an export instead. The page and everything on it get a hole where the exclusion area is, so a die cut window in the design becomes a window in the file. It is off by default, and the canvas keeps showing the content either way.

Title Template#

The page/titleTemplate property defines the display label shown for each page. It supports template variables like {{ubq.page_index}} for dynamic numbering.

// Set custom title templates for each page
try engine.block.setString(firstPage, property: "page/titleTemplate", value: "Cover")
try engine.block.setString(secondPage, property: "page/titleTemplate", value: "Content")

The default value is "Page {{ubq.page_index}}". Customize this to show labels like “Slide 1”, “Cover”, or any custom text.

Fill and Background#

Pages support fills for background colors or images using the standard fill system.

// Set a background fill on the second page
let colorFill = try engine.block.createFill(.color)
try engine.block.setColor(colorFill, property: "fill/color/value", color: .rgba(r: 0.95, g: 0.95, b: 1.0, a: 1.0))
try engine.block.setFill(secondPage, fill: colorFill)

Create a fill using engine.block.createFill(.color) or engine.block.createFill(.image), configure its properties, then apply it to the page with engine.block.setFill(_:fill:).

Page Layout Modes#

The scene’s layout mode controls how multiple pages are arranged. Set this when creating the scene with engine.scene.create(sceneLayout:) or update it with engine.scene.setLayout():

Layout Description
.verticalStack Pages stack vertically, one below the other (default for design)
.horizontalStack Pages arrange horizontally, side by side
.depthStack Pages overlay each other, typically used in video mode
.free Pages can be positioned freely without automatic arrangement

Next Steps#

  • Scenes — Learn about scene structure and management
  • Blocks — Understand the building blocks that live inside pages