Preflight
- 7-8 minutes to read
This widget integrates the Preflight Tool into your personalization workflow. For validation, you can load a state file from Asset Storage, or define the product properties and allow your users to upload their files.
{
"name": "preflight",
"type": "preflight",
"params": {
"config": {...}
}
}
Referencing the backend
This widget requires a running instance of the Preflight Tool. In workflow files, you can refer to the instance deployed in your tenant through the settings.preflightToolUrl
property. Define this URL in the config.backendUrl
property of the preflight
widget. The best practice in workflows would be to create a variable and then use it in the widget definition.
{
"vars": {
"backendUrl": "{{ settings.preflightToolUrl }}"
},
...
"widgets": [
{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"backendUrl": "{{vars.backendUrl}}",
...
To be short, we will omit this property in the following examples.
Setting up product properties
Now let's define the properties of the product for which we will check the designs. The product
object allows you to define the size and DPI, manage product pages, and configure the bleed zone.
Product size
Let's define a product of 10 x 8 inches.
The preflight
widget uses points as measurement units (1 point = 1/72 inch). For example, to define a product of 10 x 8 inches, you need to set the width
to 720 and height
to 576. To define the resolution of the resulting print files, you can use the dpi
property.
If you need to open the editor page first, set the startFromUploader
property to false
.
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"product": {
"dpi": 300,
"size": {
"width": 720,
"height": 576
}
},
"startFromUploader": false
}
}
}]
}
Product pages
By default, this widget opens a one-page product in the editor. For multipage products, you can specify the number of available product pages, for example, two.
Set up the page number in the pages
property. You can also allow your users to add and delete pages by using the allowAddPages
and allowDeletePages
properties, correspondingly.
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"product": {
"pages": 2,
"allowAddPages": true,
"allowDeletePages": true
}
}
}
}]
}
To limit the number of pages that can appear in the editor, you can define the initial, min, and max values as follows:
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"product": {
"pages": {
"init": 2,
"min": 1,
"max": 4
},
"allowAddPages": true,
"allowDeletePages": true
}
}
}
}]
}
Bleed zone
In the preflight
widget, you can display both safety lines and bleed margins. The safety lines only appear in the editor and do not affect print files, whereas the bleed margin is added into print files, thereby enlarging the product size.
You can configure this bleed zone as follows:
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"product": {
"bleed": 8,
"bleedLineWidth": 1,
"bleedLineColor": "#880000",
"safetyLines": [{
"stepPx": 5,
"widthPx": 1,
"color": "#22b980",
"altColor": "#00ff00",
"margin": 20
}]
}
}
}
}]
}
Uploading files
You can define the file uploader properties in the uploader
object. For example, you can enable the upload of multiple files at once and define how images should be resized and inserted after their upload. By default, the preflight
widget supports files of the following types: PDF, JPEG, PNG, BMP, GIF, PSD, TIFF, AI, and EPS. If you want to allow users to upload files of only specific types, you can list their extensions.
When this widget opens, it displays the upload page.
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"uploader": {
"fileTypes": [".pdf", ".jpg", ".jpeg"],
"multiple": true
}
}
}
}]
}
Loading state files
Instead of configuring products in the JSON format, you can prepare a product design, save it as a state file in your tenant, and then load it into a preflight
widget as a product definition.
To load a state file, pass its ID in the config.state.stateId
property.
{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"state": {
"stateId": "64f6d1be4737b3417c7a546a"
},
"product": {
"dpi": 300
}
}
}
}
Since all the product properties will be read from the state file, you can pass only the following settings within the product
object:
allowAddPages
allowDeletePages
dpi
Defining validation rules
Now, let's define the conditions that user designs must meet. To enable a preflight check, you need to define the config.rules array. This array contains as many elements as the rules that must be checked.
As a result of checking this file, a color space error and a low image resolution were found. The corresponding messages appear on the right panel. The error icon is displayed on the page thumbnail.
How to set up preflight rules
For example, you may want to adjust the color space and resolution of products. In this case, you must define two elements in the rules
array.
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
...
"rules": [
{
"type": "colorspace",
"severity": "error",
"enableFix": true,
"params": {
"allowedColorSpaces": ["CMYK"]
}
},
{
"type": "resolution",
"severity": "warning",
"params": {
"target": 300
}
}
]
}
}
}]
}
Here, severity
specifies whether a preflight problem should should be reported as a warning
and can remain in the print file, or if it's an error
that needs to be fixed.
As a result, if user files contain graphics in color spaces other from CMYK
, then the Preflight Tool considers them invalid and enables the Fix button to resolve this issue automatically. If these files have a resolution of less than 300 DPI, then a warning only appears in the editor.
How to configure the Fix All button
You may want to configure a single button to fix several or even all preflight problems in one click. Let's see how you can configure the Fix All button to resolve errors and warnings from the rules with the enableFix
property set to true
.
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
...
"interface": {
"customButtons": [
{
"title": "Fix All",
"filter": {
"severity": ["error", "warning"]
}
}
]
}
}
}
}]
}
Here, we only specified the severity of the rules. Instead, you can list the required rules in the types array.
Defining the rendering properties
The rendering
object allows you to set up the preview images, specify color profiles for print files, and add metadata fields to PDF files.
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
"rendering": {
"hiResOutputToSeparateFiles": false,
"trimPreviewOnBleed": true,
"previewSize": {
"width": 400,
"height": 400
},
"hiResOutputPdfMetadata": {
"author": "CA Printing",
"title": "Invitation"
}
},
...
}
}
}]
}
Changing the interface
In the interface
section of the config, you can configure a toolbar from any combination of standard buttons.
To do so, add the topToolbar
array as follows:
{
"widgets": [{
"name": "preflight",
"type": "preflight",
"params": {
"config": {
...
"interface": {
"topToolbar": [
{
"name": "upload"
},
{
"name": "fitToBleed"
},
{
"name": "fitToTrim"
},
{
"name": "reset"
}
]
}
}
}
}]
}
If you skip defining the topToolbar
, the default toolbar will appear. However, if you add at least one button, it will be created based on your list.
The following actions are supported:
"upload"
- uploads a new file or files."rotateCanvas"
- rotates the canvas 90 degrees."fillToBleed"
- fills the bleed zone with the image."fillToTrim"
- fills the trim zone with the image."fitToBleed"
- fits the image to the bleed zone."fitToTrim"
- fits the image to the trim zone."center"
- centers the image."reset"
- resets the image to the initial position."keepAspectRatio"
- allows for changing the aspect ratio of the image."rotateImage"
- rotates the image 90 degrees."applyToAll"
- applies the image position on the current page to the images on other pages.
Setting up the output
Once the Preflight Tool has rendered previews and print files, you can pass them to a Customer's Canvas project in the props
object of the order
widget. These custom properties don't appear in the order, but are available in the project.
{
"name": "order",
"type": "order",
"params": {
"props": {
"images": "{{ $['preflight'].preview }}",
"downloadUrls": "{{ $['preflight'].hires }}",
"_userId": "{{ user.id }}",
"resources": "{{ $['preflight'].origins.map(o => { return { type: 0, url: o.url, name: o.fileName}; }).concat($['preflight'].hires.map((o, index) => { return { type: 2, url: o, name: 'hires_' + index}; })) }}"
}
}
}
In the resources
, we create an array of links to origin images and print files. Each element in this array is an object that includes a type
, a name
, and url
. The type
represents one of three values:
0
- general binary file1
- preview image2
- hires file
To get a resource in a processing pipeline, you can find it by name or by type. For more details, refer to the pipeline examples.
In the Developer's Center, you can find the guide on the config and the complete list of available rules.