Settings

  • Last updated on June 10, 2025
  • •
  • 6 minutes to read

Settings are a set of feature flags and configurations that change the Handy Editor behavior.

The settings are organized in sections. Each section configures one group of related features, such as an image gallery or the editor's workspace.

The supported sections are listed below.

{
    "settings": {
        "assetLibrary": {},
        "designViewer": {},
        "imageUploader": {},
        "itemValidation": {},
        "leaveConfirmation": {}
   }
}

Let's learn parameters of each section.

assetLibrary

The assetLibrary object manages the buttons for creating new elements. You can toggle the following elements:

  • text - a tool that adds new text items
  • shape - a tool that creates new rectangles, ellipses and potentially other shapes
  • images - an image manager that allows inserting image items from a library
  • cliparts - another image library that is more oriented for clipart - vector elements used as decorations, icons, etc.
  • imageUploader - a tool for uploading and inserting new images from the user's device
  • templates - a design selection tool that is available if multiple design templates are connected to the product variant
  • productOptions - an option selection tool

Buttons for new elements

If you omit the assetLibrary object, the following default values will be applied:

{
    "assetLibrary": {
        "text": {
            "enabled": true
        },
        "shapes": {
            "enabled": true
        },
        "images": {
            "enabled": true
        },
        "cliparts": {
            "enabled": true
        },
        "imageUploader": {
            "enabled": true
        },
        "templates": {
            "enabled": true
        },
        "productOptions": {
            "enabled": true
        }
    }
}

designViewer

The designViewer object is responsible for the user experience with the work area (design viewer) where the user manipulates the design elements.

{
    "designViewer": {
        "grid": { }
    }
}

The grid object configures the grid that makes it easier for the user to position and align the elements on the design.

Grid in the viewer

The grid parameters:

  • step defines the grid step, in points (1/72 inch).
  • gridEnabled defines whether the grid is enabled when the editor is opened. The user can toggle it later through the user interface or a hotkey Ctrl+'.

If you omit the grid object, the following default values will be applied:

{
    "grid": {
        "step": 10,
        "gridEnabled": false
    }
}

imageUploader

The imageUploader object defines the format in which the uploaded images will be added to the design. You can set a single option for all supported image types in the insertByDefaultAs property, which will be applied by default. At the same time, you can specify how different types of uploaded images will be added to the design in the insertFileAs object. This setting may look as follows:

{
    "imageUploader": {
        "insertByDefaultAs": "Auto",
        "maxFileSizeMb": 50,
        "multipleUploadEnabled": false,
        "insertByDefaultAs": "Auto",
        "allowedFileFormats": [".jpg", ".jpeg", ".png"],
        "allowedFileFormatsVectorOnly": [".svg", ".psd", ".eps"],
        "insertFileAs": {
            "svg": "Shape",
            "pdf": "Clipart",
            "png": "Image",
            "jpeg": "Image"
        }
    }
}

Let's examine the parameters:

  • maxFileSizeMb: The maximum file size in megabytes.

  • multipleUploadEnabled: Enables the ability to upload multiple files simultaneously.

  • allowedFileFormats: A list of allowed file formats.

  • allowedFileFormatsVectorOnly: Allowed file formats when the Constraints > Raster objects" container setting is disabled.

  • insertByDefaultAs: The preferred type for file extensions that are not defined in the configuration.

  • insertFileAs: Determines the internal element type of the editor that will correspond to the images of the uploaded file format. The keys in this object are the file formats (e.g., svg, pdf, png, jpeg, etc.), and the values may be "Clipart", "Image", "Shape", "Group", or "Auto", where:

    • "Clipart" creates a clipart item if possible.
    • "Image" creates an image item if possible.
    • "Shape" creates a shape item if possible.
    • "Group" creates a group item if possible.
    • "Auto" automatically determines the type of uploaded graphics on the server.

itemValidation

The itemValidation object configures the validation rules for items in the design. You can enable an image quality meter with low DPI warnings, check for minimum font sizes for text elements, and verify vector graphics compliance for images. The following example demonstrates properties of these checks and their default values.

{
    "itemValidation": {
        "allowRasterElements": {
            "enabled": true,
            "severity": "Error"
        },
        "targetResolution": {
            "errorLevel": 50,
            "warningLevel": 100
        },
        "qualityMeter": {
            "enabled": true,
            "targetResolution": 300,
            "warning": 80,
            "bad": 50,
            "qualityChangeContainersEnabled": true
        },
        "minFontSize": {
            "enabled": true,
            "severity": "Warning"
        }
    }
}

The severity of allowRasterElements and minFontSize determines the level of validation issues:

  • Warning: Indicates that there are validation issues but does not prevent the user from proceeding to the next step.
  • Error: Stops the user from proceeding to the next step until the validation issues are resolved.

allowRasterElements

The allowRasterElements setting restricts the type of images being added to the design to either vector-only or both vector and raster elements.

By default, the enabled property is true, which enables this validation. To prevent the client from proceeding to the approval page, set severity to "Error".

{
    "itemValidation": {
        "allowRasterElements": {
            "enabled": false,
            "severity": "Error"
        }
    }
}

targetResolution

The targetResolution validates the resolution for raster objects that will be used for rendering print files.

This setting determines the image resolution levels at which validation violations will be reported. It has a higher priority compared to the warning and bad settings of qualityMeter. However, the target DPI value is taken from the container's printing restrictions, not from the configuration.

The warningLevel is the percentage of the target DPI (default is 100%) below which a warning will be displayed for the image. It shows a yellow icon on the canvas and a warning message at the approval page, but still allows the user to click the Approval checkbox and the Continue button on the approval page. To disable this setting, change its value to null.

The errorLevel is the percentage of the target DPI (default is 50%) below which an error will be displayed for the image. It shows a red icon on the canvas and a warning message at the approval page. If this validation fails, the Approval checkbox and the Continue button will be disabled on the approval page, preventing the user product personalization from being completed. To disable this setting, change its value to null.

{
    "itemValidation": {
        "targetResolution": {
            "errorLevel": 50,
            "warningLevel": 100
        }
    }
}

qualityMeter

Note

This object remains for compatibility purposes. It's recommended to use the targetResolution object for DPI validation. Otherwise, the warning and bad properties will be applied only when errorLevel and warningLevel are set to null.

The warning and bad properties define the raster image quality levels as a percentage of the targetResolution property that will be used for rendering print files. 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.

In the following example, a DPI lower than 150 (50% of 300) will be considered bad, a DPI in the range from 150 to 240 will display a warning, and a DPI higher than 240 will be considered acceptable. For DPI values corresponding to the bad and warning levels, an icon appears near the image.

{
    "itemValidation": {
        "qualityMeter": {
            "enabled": true,
            "targetResolution": 300,
            "warning": 80,
            "bad": 50,
            "qualityChangeContainersEnabled": true
        }
    }
}

minFontSize

The minFontSize setting imposes a limit on the minimum font size to prevent using extremely small text that cannot be printed. This setting affects the font size in the font size selector and is also checked when resizing text. This check is enabled by default.

{
    "settings": {
        "itemValidation": {
            "minFontSize": {
                "severity": "error" | "warning"
            }
        }
    }
}

leaveConfirmation

The leaveConfirmation object contains an enabled property that allows you to disable confirmation dialog when leaving the page with the editor. By default, this dialog will appear in a browser, and the property value is true.

{
   "leaveConfirmation": {
        "enabled": false
    }
}
Was this page helpful?
Back to top Copyright © 2001–2025 Aurigma, Inc. All rights reserved.