Configuring the viewer

Last updated on August 8, 2025
•
4-5 minutes to read

The Viewer component visualizes and interacts with design elements created by Customer's Canvas, serving as an interface tool for integrating editing and viewing functionalities into web applications.

In the Working with the object model topic, you learned how to use the object model of a product. However, to be able to use it in a full force, you need to connect it to a backend.

Connecting the viewer

To integrate the Viewer, follow these steps:

Install the front-end library @aurigma/design-atoms via NPM:
```
npm install @aurigma/design-atoms --save
```

Create an instance of the Viewer class:

const backendUrl = "http://<yourInstanceUrl>";
const holderId = "#id-of-your-div";
const holder = document.querySelector(holderId);
const viewer = new Viewer({
    holderElement: holder,
    backendUrl: backendUrl,
    canvasBackground: { color: "white" }
});

Ensure that a back-end server is set up separately. You can connect to an existing Customer's Canvas Design Editor instance or create a custom backend using the Aurigma.DesignAtoms NuGet package.

Defining a print area

As an example, let's specify a print area and a bleed zone in the viewer:

// Import necessary classes from the Customer's Canvas SDK.
import { PrintArea, SafetyLine, PdfBox, RgbColor } from "@aurigma/design-atoms-model/Product";
import { RgbColor } from "@aurigma/design-atoms-model/Colors";
import { RectangleF } from "@aurigma/design-atoms-model/Math";

// Define safety lines.
const safetyLine = new SafetyLine();
safetyLine.margin = 10;
safetyLine.pdfBox = PdfBox.Bleed;
safetyLine.color = new RgbColor("lime");

// Add the safety line to a print area.
const printArea = new PrintArea(new RectangleF(0, 0, surface.Width, surface.Height));
printArea.safetyLines.add(safetyLine);

surface.printAreas.add(printArea);

// Enable safety lines in the viewer.
viewer.safetyLinesHandler.visible = true;

Changing zoom mode

To dynamically adjust the zoom level for a better user experience:

// Import the Viewer and ZoomMode classes from the Customer's Canvas SDK.
import { Viewer, ZoomMode } from "@aurigma/design-atoms/Viewer";

// Function to set the zoom mode for the given viewer instance.
const setZoomMode = (viewer: Viewer, mode: ZoomMode) => {
    // Set the specified zoom mode on the viewer.
    viewer.zoomMode = mode;
    // Hide any hover effects currently visible on the canvas.
    viewer.canvas.hideHover();
    // Redraw the canvas to apply changes immediately.
    viewer.canvas.redraw();
};

// Call the function to set the best-fit zoom mode on the viewer.
setZoomMode(viewer, ZoomMode.bestFit);

Subscribing to item events

To subscribe to events for items on the canvas (e.g., when a user moves an image):

viewer.eventManager.addItemChanged((item) => {
    // Handle item change event
});

Enabling Delete and Edit buttons

To enable the Floating Toolbar with Delete and Edit buttons:

viewer.configuration.floatingToolbar = {
    enabled: true,
    cssClass: "my-toolbar-css-class",
    editButtonClass: "edit-btn",
    selectButtonClass: "select-btn",
    deleteButtonClass: "delete-btn",
    handleButtonClass: "handle-btn",
    bigButtonCssClass: "big",
};
viewer.configuration = viewer.configuration;

Use CSS to customize the appearance of the toolbar:

.my-toolbar-css-class {
    background-color: white;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24);
    border-radius: 2px;
    padding: 4px;
    margin: 10px 1px;
}

.my-toolbar-css-class button {
    width: auto;
    height: 30px;
    padding: 9px;
    border: 0;
}

.my-toolbar-css-class button:hover {
    background-color: gray;
}

.my-toolbar-css-class .edit-btn::before {
    content: 'Edit';
}

.my-toolbar-css-class .select-btn::before {
    content: 'Select';
}

.my-toolbar-css-class .delete-btn::before {
    content: 'Delete';
}

To handle button clicks:

viewer.eventManager.addDeleteToolbarButtonClick((item) => { console.log('delete') });
viewer.eventManager.addEditToolbarButtonClick((item) => { console.log('edit') });
viewer.eventManager.addSelectToolbarButtonClick((item) => { console.log('select') });
viewer.eventManager.addHandleToolbarButtonClick((item) => { console.log('handle') });

To disable the Floating Toolbar:

viewer.canvas.floatingToolbarManager.enabled = false;

Managing Layers

To move layers up and down, for example, text above an image, use the bringItems command:

const selectedItems = viewer.selectedItems;
const position = "bottom"; // Possible values: "front", "levelUp", "levelDown", "bottom"
viewer.commandManager.execute(ItemsCommand.bringItems, { items: selectedItems, position: position });

Note

Ensure that the item has defined itemPermisssions.allowZOrderChange=true.

Snap lines

To enable snap lines for guiding users when moving items:

const itemConfig = { enabled: true, includeLocked: false, color: "magenta", priority: 1, tolerance: 5 };
const otherElementsConfig = { enabled: true, color: "magenta", priority: 1, tolerance: 5 };

viewer.configuration.snapLines = {
    snapElements: {
        items: itemConfig,
        printArea: otherElementsConfig,
        grid: otherElementsConfig,
        region: otherElementsConfig,
        safetyLines: otherElementsConfig
    }
};
viewer.configuration = viewer.configuration;

Restricting item movements

To restrict users from moving images beyond the safety line, you can use the region property of SurfaceContainer:

mainContainer.region = new RectangleF(300, 350, 400, 400);

Displaying violation warnings

To display warnings when items are outside the print area or safety lines:

Set the main surface container name to "Main":

const mainContainer = new SurfaceContainer([imageItem], "Main");

Configure the violation service:

viewer.configuration.violationService = {
    bleedViolationWarningEnabled: false,
    inPlaceNotSupportedWarningEnabled: false,
    qualityChangeContainersEnabled: true,
    qualityMeter: { enabled: false, qualityLevels: { bad: 30, warning: 70 }, renderingDpi: 300 },
    regionViolationWarningEnabled: false,
    safetyLines: { enabled: true, mode: SafetyLineViolationMode.PartiallyInsideAny },
    textCropViolationWarningEnabled: false,
    enabled: true,
    violationWarningButtonsEnabled: true,
};
viewer.configuration = viewer.configuration;

Subscribe to violation events and display custom messages:

viewer.violationService.addItemViolationStateChanged((args) => {
    const msg = `Violation state changed for item [${args.new.item.name}] => ${ViolationState[args.new.state]}`;
    if (args.new.state == ViolationState.Bad || args.new.state == ViolationState.Warning) {
        console.warn(msg, args.new.messages);
    }
});

Visual Enhancements

Displaying guiding lines during item movement

To show guiding lines (e.g., for centering objects relative to printArea), configure snapLines: in the Editor.ts at the very end of the initViewer method after the Editor.configureCanvas add:

const viewerConfig = this._viewer.configuration;
const defaultElementConf = {
    tolerance: 5,
    color: "rgb(255,0,255)",
    enabled: false,
    priority: 0
};
viewerConfig.snapLines = {
    snapElements: {
        items: { ...defaultElementConf, includeLocked: false },
        printArea: { ...defaultElementConf },
        safetyLines: { ...defaultElementConf },
        region: { ...defaultElementConf },
        grid: { ...defaultElementConf }
    }
};
viewerConfig.snapLines.snapElements.printArea.enabled = true;
this._viewer.configuration = viewerConfig;

Customizing the selection border

To customize the border of the selected items (e.g., change color and padding):

viewer.canvas.style.selection.color = "#FFA500";

Customizing the rotation button icon

To replace the rotation button icon with a custom image:

let image = document.createElement("img");
image.onload = () => {
    viewer.canvas._canvasRenderer._rotationIconImage = image;
};
image.src = "https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/atom.svg";