The Preflight Check

To verify that user designs are valid for printing, you can enable the preflight check. Customer's Canvas verifies that the following conditions are met:

  • Design elements are within the print zone.
  • Images and image placeholders have a good DPI resolution.
  • Bounded text fits the bounding rectangles.
  • Violations of the regions do not occur.

Customer's Canvas performs the preflight check at runtime, while your users are editing their designs. If one of these problems occurs, then the corresponding warning appears right on the canvas and in the Object Inspector. When you rendering a user design, you can also retrieve details about design elements that failed this validation.

Violation Warnings

You can enable the preflight check and violation warnings in the ~\Configuration\clientConfig.json file globally or through the IConfiguration interface for a single product. The following example shows how you can enable the preflight check.

clientConfig.json
{
    "violationWarningsSettings": {
        "regionViolationWarningEnabled": true,
        "safetyLineViolationWarningEnabled": true,
        "textCropViolationWarningEnabled": true,
        "qualityMeter": {
            "enabled": true
        }
    }
}

Here, the regionViolationWarningEnabled property enables the region validation, safetyLineViolationWarningEnabled enables the bleed zone validation, textCropViolationWarningEnabled validates that bounded text is not cropped, and the qualityMeter object configures the image resolution check.

Now that you have enabled the preflight, define whether these warnings appear in the Object Inspector and on the canvas. Note, you can enable the validation and simultaneously disable warnings in the user interface. In this case, Customer's Canvas performs the validation, and you can handle the OnImageDpiChanged event by analyzing the preflight problems while rendering the designs.

Warnings in the Object Inspector

To display violation warnings in the Object Inspector, set the violationWarningsEnabled property to true.

clientConfig.json
{
    "widgets": {
        "ObjectInspector": {
            "violationWarningsEnabled": true
        }
    }
}

These violation warnings appear on the right side of the Object Inspector as red and yellow icons.

Warnings in the Object Inspector.

When you click the icons or tap them on your mobile device, Customer's Canvas displays corresponding messages and the actual DPI of the image for the quality warnings.

Warnings in the Object Inspector.

Warnings on the Canvas

To display violation warnings on the canvas, set the violationWarningButtonsEnabled property to true.

clientConfig.json
{
    "canvas": {
        "violationWarningButtonsEnabled": true,
        "qualityChangeContainersEnabled": true
    }
}

On the canvas, warning icons appear near design elements that have preflight problems. For example, when a design element goes out of the safety zone, the following warning appears.

The bleed zone violation warning on the canvas.

Now, if you move this element back to the safety zone, the warning icon briefly changes to a green check and disappears.

The green check mark of successful preflighting.

Validating the Image Resolution

To verify that user images have a good resolution for printing, Customer's Canvas uses a so-called quality meter. When the user resizes an image or adds a new image to the design, the quality meter evaluates the image resolution based on the hiResOutputDpi property and the DPI tolerance set up in qualityLevels.

clientConfig.json
{
    "rendering": {
        "hiResOutputDpi": 250
    },

    "violationWarningsSettings": {
        "qualityMeter": {
            "enabled": true,
            "qualityLevels": {
                "warning": "100",
                "bad": "80"
            }
        }
    },

    "canvas": {
        "violationWarningButtonsEnabled": true,
        "qualityChangeContainersEnabled": true
    }
}

The warning and bad properties define the image quality levels as a percentage of the hi-res output DPI. The warning value should be greater than or equal to the bad value. You can enable a bar displaying the DPI change when the user resizes images. To display this bar, set qualityChangeContainersEnabled to true.

The image DPI bar.

Also, Customer's Canvas sends the OnImageDpiChanged event when the user resizes images. The following example subscribes to this event and outputs the event arguments - the DPI values and design element names - to the console.

JavaScript
var editor = null;

CustomersCanvas.IframeApi.loadEditor(iframe, productDefinition)
    .then(function(e) {
        editor = e;
        editor.subscribe("OnImageDpiChanged", function (oldDpi, newDpi, elementName) {
            console.log("oldDpi: " + oldDpi + " newDpi: " + newDpi + " element: " + elementName);
        });
    });

Validation Results

When you use the finishProductDesign method, you can retrive details about preflight problems through violationWarningData. This array contains as many elements as there are design elements that have preflight problems.

JavaScript
editor.finishProductDesign()
    .then(function (result) {

        console.log("Saved state: " + result.stateId);

        // If there are preflight problems, output the details to the console.
        if (result.violationWarningData.length > 0)
            preflightProblems.forEach(function (anItem) {
                console.log("Warning: " + anItem.name + " failed the preflight check.");
            });
    });

See Also

IFrame API Reference