Custom Page Templates

Starting with PSPDFKit 7.6 for iOS, you can customize the set of templates that PDFNewPageViewController offers on the picker via the new PageTemplate API.

The page templates can be updated via the pageTemplates property on PDFDocumentEditor.Configuration. Then you can instantiate a PDFNewPageViewController with that configuration. If you wish to make your custom set of templates available globally, you can update the page templates list on a PDFDocumentEditor.Configuration and then assign that configuration to PDFConfiguration.documentEditorConfiguration.

Remove PSPDFKit-Provided Templates

PSPDFKit ships with a predefined list of page templates, which are ready to use:

Template PageTemplate.Identifier
Blank .blank
Dot 5mm .dot5mm
Grid 5mm .grid5mm
Line 5mm .lines5mm
Line 7mm .lines7mm
Image .image

When you don’t want some of these default templates to be available as options for creating or editing PDF documents, you can use PDFDocumentEditor.Configuration.pageTemplates:

Copy
1
2
3
4
5
6
7
let documentEditorConfiguration = PDFDocumentEditor.Configuration { builder in
    builder.pageTemplates = []
}
let configuration = PDFConfiguration { builder in
    builder.documentEditorConfiguration = documentEditorConfiguration
}
let controller = PDFViewController(document: document, configuration: configuration)
Copy
1
2
3
4
5
6
7
PSPDFDocumentEditorConfiguration *documentEditorConfiguration = [PSPDFDocumentEditorConfiguration configurationWithBuilder:^(PSPDFDocumentEditorConfigurationBuilder *builder) {
    builder.pageTemplates = @[]
}];
PSPDFConfiguration *configuration = [PSPDFConfiguration configurationWithBuilder:^(PSPDFConfigurationBuilder *builder) {
    builder.documentEditorConfiguration = documentEditorConfiguration
}];
PSPDFViewController *controller = [[PSPDFViewController alloc] initWithDocument:document configuration:configuration];

The PageTemplate Class

You can use the PageTemplate class to build page templates from your own PDF documents.

PageTemplate has three initializers you can use depending on what you’re trying to achieve:

ℹ️ Note: Creating a tiled pattern page template requires the source document to be exported correctly. This means that the source PDF needs to contain a pattern itself. If a PageTemplate is instantiated using the tiled pattern initializer and the source document does not contain a pattern, the rendering will fail silently.

Check out DocumentEditorCustomTemplates.swift in the Catalog to see PageTemplate in action.

Custom Tiled Templates

Many uses for page templates require the background being tiled (or patterned).

A page is considered tiled if there are one or more images repeated on the page.

For a PDF to be able to work as a source for a tiled page template using the new PageTemplate(tiledPatternFrom:sourcePageIndex:) API, it has to have actual pattern path information embedded.

To accomplish this, you can use Adobe Illustrator or any other vector editing tool.

When creating your own patterns, please take the following points into consideration:

  1. What’s rendered on the page is the path information embedded in the PDF and not the actual PDF.
  2. If your custom pattern needs certain spacing between tiles, that information needs to be included within the pattern information as well. Currently, there’s no way to specify spacing between tiles from the PSPDFKit API.

Click here to download a custom sample template.

After you’ve created the PDF document that will serve as a pattern source, you can use it with PSPDFKit as follows:

Copy
1
2
3
4
5
6
7
8
9
10
let document = Document(url: url)
let customTemplate = PageTemplate(tiledPatternFrom: document, sourcePageIndex: 0)

let editorConfiguration = PDFDocumentEditor.Configuration { (builder) in
  builder.pageTemplates.append(contentsOf: [customTemplate])
}

let newPageViewController = PDFNewPageViewController(documentEditorConfiguration: editorConfiguration)

present(newPageViewController, options: options, animated: true, sender: sender)
Copy
1
2
3
4
5
6
7
8
9
10
PSPDFDocument *document = [[PSPDFDocument alloc] initWithURL:url];
PSPDFPageTemplate *customTemplate = [[PSPDFPageTemplate alloc] initWithTiledPatternFromDocument:document sourcePageIndex:0];

PSPDFDocumentEditorConfiguration *editorConfiguration = [PSPDFDocumentEditorConfiguration configurationWithBuilder:^(PSPDFDocumentEditorConfigurationBuilder *builder) {
    NSMutableArray<PSPDFPageTemplate *> *pageTemplates = builder.pageTemplates.mutableCopy;
    [pageTemplates addObject:customTemplate];
    builder.pageTemplates = pageTemplates;
}];

[controller presentViewController:newPageViewController options:options animated:YES sender:sender completion:nil];