Frequently Asked Questions

The Aurigma Preflight Tool is implemented in the UI Framework and represents the preflight widget. This framework allows you to operate with the Preflight Tool API through the configuration in the JSON format. To manage a widget, you need to configure its params object.

This topic describes the most frequent use-cases and how you can configure this tool to:

For more details about manipulating the Preflight Tool, you can refer to the UI Framework Tutorials

How to Configure Products

You can configure product properties in the config.product object.

How to Define the Product Size

The Preflight Tool uses points as measurement units (1 point = 1/72 inch). 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.

{
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "config": {
                "product": {
                    "dpi": 300,
                    "size": {
                        "width": 720,
                        "height": 576
                    }
                }
            }
        }
    }]
}

How to Set Product Pages

By default, the Preflight Tool opens a one-page product in the editor. For multipage products, you can specify the number of pages 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": 1,
                    "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
                }
            }
        }
    }]
}

In this example, we open two pages in the editor and allow users to reduce the number of pages to one and increase their number to four. For multipage products, this configuration allows users to open only the first four pages in the editor.

You can also specify page titles when setting up product pages. For two-page products, you can specify the titles in an array as follows:

{
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "config": {
                "product": {
                    "pages": [{ "title": "Front" }, { "title": "Back" }],
                    "allowAddPages": false,
                    "allowDeletePages": false
                }
            }
        }
    }]
}

How to Configure the Bleed Zone

The Preflight Tool allows you to enable 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 them as follows:

{
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "config": {
                "product": {
                    "bleed": 8,
                    "safetyLines": [{
                        "color": "#00ff00",
                        "margin": 20
                    }]
                }
            }
        }
    }]
}

How to Configure Preflight Rules

To enable a preflight check, you need to define the config.rules array. This array contains as many elements as the rules need to be checked.

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 can remain in the print file or if it must 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 Specify Spot Colors

You can define a set of allowed spot colors in a rule of the spotcolors type. In the allowed object, you can list spot color names and use regular expressions. Other spot colors will be considered invalid, and the Preflight Tool will suggest to replace them.

{
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "config": {
                "rules": [{
                    "type": "spotcolors",
                    "severity": "error",
                    "params": {
                        "allowed": {
                            "names": [ "PANTONE 653 C", "PANTONE 649 C", "PANTONE 7677 C" ]
                        }
                    }
                }]
            }
        }
    }]
}

How to Configure Image Formats

You can specify which file formats are allowed to be uploaded to the Preflight Tool in the uploader.fileTypes array. This tool supports both single file upload and the upload of multiple files at once. To enable multiple selections and uploading, set the multiple property to true.

{
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "config": {
                "startFromUploader": true,
                "uploader": {
                    "fileTypes": [".pdf", ".jpg", ".psd", ".eps"],
                    "multiple": true
                }
            }
        }
    }]
}

In this example, we allowed EPS files to be uploaded. This format does not have built-in support in the Preflight Tool, but you can convert such images to PDF by using external converters. On the back end, you can configure the converters in the Converters.config file. For example, to work with EPS files, you can convert them to PDF by using the Ghostscript. You can set up this utility as follows:

Converters.config
<Aurigma.DesignAtoms.Converters>
  <Converters>
    <Converter name="epsgs"
            format="eps"
            executable="D:\ghostscript\gs9.27\bin\gswin64c.exe"
            args="-dPSFitPage -dSAFER -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -dFitPage -r300 -sOutputFile=%OUTPUT% %INPUT%"
            timeout="30" />
  </Converters>
</Aurigma.DesignAtoms.Converters>

For more details about converters, you can refer to the corresponding topic.

When the user finishes validation of their files, they click the Finish button in the navigation area, and the Preflight Tool renders these files to the high-resolution PDF file.

To get links to the resulting files, you must create and initialize an e-commerce driver and subscribe to the onSubmitted event. This event is triggered when the user finishes editing. On the front end, you can log these links as follows:

JavaScript
// Initialize the e-commerce driver and display the editor in the container.
const ecommerce = await driver.init(product, editor, config, settings, null, quantity, user);
ecommerce.products.current.renderEditor(document.getElementById("editor-parent"));

// Subscribe to the onSubmitted event.
ecommerce.cart.onSubmitted.subscribe(data => {
    data.lineItems.forEach(function(order) {
        console.log("Print files: ", order.downloadUrls);
        console.log("Previews: ", order.images);
    });
});

If you refer to the sample page, you can see that the ecommerce object is initialized before loading the editor. We can also use this object to connect to the event of clicking the Finish button.

How to Upload Files through the Web API

The Preflight Tool already includes the upload interface. However, if you still need uploading files externally, you can do it as described here.

First, configure the preflight widget. You need to disable starting from the uploader.

{
    "vars": {
        "fileList": [],
        "backendUrl": "<URL to your preflight backend>"
    },
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "files": "{{ vars.fileList }}",
            "config": {
                "backendUrl": "{{vars.backendUrl}}",
                "startFromUploader": false,
                ... // Other settings.
    },
    "steps": [
        ...
    ]
}

Use a FORM element to select files and send a multipart/form-data POST request.

HTML
<form action="/server/api/files/upload" method="post" enctype="multipart/form-data">
    Select PDF to upload:
    <input type="file" name="file" id="file" accept="application/pdf">
    <input type="submit" value="Upload Image" name="submit">
</form>
<div class="editor-parent" id="editor-parent"></div>

The api/files/upload request returns a list of files, which you need to pass to the Preflight Tool as follows:

  1. Get a reference to the editor instance which is returned from the renderEditor method.
  2. This instance has the scopeInternal method which returns the same object as you can use inside dynamic config expressions. For example, if you give your preflight widget name My-Preflight-Tool, you need to access it as $["My-Preflight-Tool"]. In this example, the widget name is preflight, and you can access it using both dot and square bracket syntax.
  3. The preflight widget supports the setFiles method which accepts an array of file names from the Preflight backend.
JavaScript
<script type="module">

    // Initialize the Preflight Tool.
    var editorInstance = null;

    document.addEventListener('DOMContentLoaded', async () => {

        // Define init parameters.
        // ...
        config.vars.backendUrl = "/server";

        // Instantiate an editor.
        const ecommerce = await driver.init(product, editor, config, settings, null, quantity, user);
        editorInstance = await ecommerce.products.current.renderEditor(document.getElementById("editor-parent"));

    });

    // Here goes the upload handling code.
    document.addEventListener("DOMContentLoaded", () => {

        // Send a POST request containing files to https://<preflight backend>/api/files/upload
        document.querySelector("form").addEventListener("submit", async e => {
            e.preventDefault();
            let response = await fetch("/server/api/files/upload", {
                body: new FormData(e.currentTarget),
                method: "post",
            });

            // The response contains an array of internal file identifiers on the back end.
            // For example, ['35e8d7f6-c075-4540-8f89-aa7255ab8ed5.pdf'].
            let result = await response.json();
            console.log(result);

            // Pass these names to the UI Framework. To do it, you need to get an access to the
            // preflight widget and call the setFiles method as follows: 
            editorInstance.scopeInternal.$.preflight.setFiles(result);

        });
    });
</script>

For more details, refer to the Web API Reference.

How to Change Default Colors of the User Interface

The Preflight Tool uses the following CSS variables for colors applied in the user interface.

html {
    --theme-primary-color: #30c2ff;
    --theme-border-color: #e0e0e0;
    --theme-dark-border-color: #cccccc;

    --theme-white-color: #ffffff;
    --theme-grey-color: #505253;
    --theme-light-grey-color: #909293;
    --theme-dark-grey-color: #666666;

    --theme-green-color: #00b628;
    --theme-red-color: #ff0000;
    --theme-orange-color: #f4a100;
    --theme-blue-color: #0000ff;

    --theme-viewer-background-color: #f8f9fa;
    --theme-scrollbar-color: #dadce0;
    --theme-report-title-color: #212121;

    --theme-uploader-progressbar-color: #e5e5e5;
    --theme-uploader-hinttext-color: #6f747d;
    --theme-uploader-hover-color: rgba(48, 194, 255, .1);

    --theme-popup-box-shadow: 0 2px 16px rgba(33, 43, 54, .08), 0 31px 41px rgba(33, 43, 54, .2);

    --theme-overlay-color: rgba(0, 0, 0, .3);
    --theme-light-overlay-color: rgba(255, 255, 255, 0.9)
}

To specify a custom color, change the variable values in the style section of params, for example:

{
    "widgets": [{
        "name": "preflight",
        "type": "preflight",
        "params": {
            "config": {
                ...
            },
            "style": {
                "--theme-primary-color": "#ff0000",
                "--theme-viewer-background-color": "#ffffff"
            }
        }
    }]
}

How to Localize Text Resources

In the \ui-framework\<version>\static\preflight\locales.json file, you can find text resources for supported languages. You can change these locales or add new ones.

Note that text in rightToolbar.info.rules can include HTML tags, for example:

{
    "en": {
        ...
        "rightToolbar": {
            "info": {
                "rules": {
                    "important": "Important:",
                    "text": "Your artwork must be in <b>{{COLORSPACE}}</b> color space and its resolution should be at least <b>{{DPI}}</b> dpi."
                }
            },
            ...
}

How to Configure Custom Buttons

You may want to configure a single button to fix several or even all preflight problems at a click. The Preflight Tool allows you both to list the required rules and to change the button style. Let's look at how you can configure the Fix All button to resolve errors and warnings of the rules with the enableFix property set to true.

{
    ...
    "interface": {
        "customButtons": [
            {
                "title": "Fix All",
                "filter": {
                    "severity": ["error", "warning"]
                },
                "style": {
                    "color": "white",
                    "background-color": "var(--theme-primary-color)"
                }
            }
        ]
    }
}

Here, we only specified the severity of the rules. Instead, you can list the required rules in the types array.

To change the appearance of the button, we defined a new color and background-color. In the first case, we used the constant "white". To specify the latter property, we referred to the CSS variable --theme-primary-color.

See Also

Manual