KILB Visual Layer Product Configurator

Getting Started

After installing the KILB Canvas Configurator, you will find a new menu entry "KILB Canvas Configurator" in the Content section of your Shopware Admin sidebar. Click it to open the configurator admin dashboard.

Step 1: Create a Configurator

Click "Create Configurator" and fill in the following fields:

• Name — An internal name for identification (e.g., "Shoe Configurator", "Phone Case Designer").
• Canvas Width / Height (px) — The base resolution of the canvas in pixels. This determines the aspect ratio and the quality of the generated images. Choose dimensions that match your product images (e.g., 800 x 800 for a square product).
• Preview Width / Height (px) — The display size of the live preview on the storefront (min 100, max 1024). The aspect ratio is locked to the canvas dimensions, so changing one value updates the other automatically.
• Background Image — Optionally select a background image from the Shopware media library. This image will be the base layer of the canvas, visible behind all other layers.
• Use canvas preview as line-item image — When enabled, the customer's designed canvas will be shown as the product image in the shopping cart and order confirmation instead of the default product image.

Click "Save" to create the configurator.

Step 2: Add Options

After saving the configurator, you will see the Options section. Click "Add Option" to create a new option.

• Label — The name displayed to the customer in the storefront (e.g., "Background", "Hair Color", "Your Name").
• Type — Choose Image for selectable image layers or Text for customer text input.
• Required — Enable this if the customer must make a selection or enter text before adding to cart.

Options are displayed in the order they appear in the list. Use the arrow buttons to reorder them.

Step 3: Add Option Values

Click "Edit" on an option to manage its values. Then click "Add Value".

For Image Options

Each value represents a selectable image layer:

• Label — The name shown on the selection button (e.g., "Blue", "Wood", "Marble").
• Image Mask — Select the image layer from the Shopware media library. This image will be overlaid on the canvas when the customer selects this value. Use transparent PNG files for best results.
• Selection Image — Optionally set a separate thumbnail image for the selection button. If not set, the image mask is used as fallback. This is useful when the image mask is a full-canvas layer but you want to show a small, cropped preview on the button.

For Text Options

Each value represents a text input field with its own configuration:

• Label — Descriptive name (e.g., "Front Text", "Back Engraving").
• Default Text — Pre-filled text the customer sees before typing. Can be translated per language.
• Max Characters — Limits the number of characters the customer can enter.

Position and Alignment (Both Types)

• Position X / Y — Coordinates in pixels on the canvas where the element is placed.
• Horizontal Alignment — Left, Center, or Right alignment relative to the position point.
• Vertical Alignment — Top, Center, or Bottom alignment relative to the position point.

Step 4: Configure Text Properties (Text Options Only)

For text option values, you can define the available colors, fonts, and sizes that customers can choose from. In the option value edit view, you will find the Properties section.

Adding Colors

1. Click "Add Color".
2. Enter a hex color code (e.g., #FF0000 for red).
3. Optionally set the opacity (1 = fully opaque, 0 = fully transparent).
4. Click "Add".
5. Repeat for all colors you want to offer. You can mark one color as the default.

Adding Fonts

Fonts must be uploaded to your Shopware media library before they can be used:

1. Open the Shopware Admin and navigate to Content > Media.
2. Create a folder named exactly KilbCanvasConfiguratorFonts (case-sensitive, no spaces).
3. Download the one or multiple available fonts from here: https://canvas-configurator.kilb.tech/fonts  -> the number of available fonts will continuously increased
4. Upload the available font PDF files in your media library's folder.
5. Return to the configurator admin dashboard and edit your text option value.
6. In the Font Properties section, click "Add Font".
7. Select a font from the dropdown — it lists all TTF files found in the KilbCanvasConfiguratorFonts folder.
8. Click "Add". Repeat for all fonts you want to offer.
9. Mark one font as the default that will be pre-selected for the customer.

Adding Sizes

1. Click "Add Size".
2. Enter the font size in pixels (e.g., 24).
3. Click "Add".
4. Repeat for all sizes you want to offer. Mark one as the default.

Important: For text to render correctly on the canvas, each text option value should have at least one color, one font, and one size configured.

Step 5: Assign Products

Navigate to the Products tab of your configurator. Here you can link the configurator to one or more Shopware products:

1. Click "Assign Product".
2. Use the search field to find products by name.
3. Click a product to assign it. The configurator will now appear on that product's detail page in the storefront.
4. Product variants are supported — you can assign the configurator to individual variants.

A single configurator can be assigned to multiple products. To remove an assignment, click "Remove" next to the product.

Step 6: Translations

If your shop supports multiple languages, you can translate all texts (configurator name, option labels, option value labels, default texts) per language. Edit any entity and switch to the desired language to add translations manually.

Alternatively, use the "Translate Missing" button on the configurator edit page. This AI-powered feature automatically translates all missing texts across all your configured shop languages in one click.

Managing Orders

Navigate to the Orders section in the configurator admin dashboard. Here you see all orders that contain configured products.

• Use the search field to filter by order number or configurator name.
• Click "Preview" to open a canvas preview of the customer's design.
• In the preview modal, you can see all customer selections (chosen options, entered text, font, color, size).
• Use the export options to download the design:
  • PNG — Standard image format, ideal for print production.
  • WebP — Compressed image format for digital use.
  • PDF — Vector-quality export with embedded fonts, ideal for professional printing.
  • JSON — Full FabricJS canvas state for archival or re-rendering.
• Adjust the resolution scale factor to control export quality.
• Toggle "Include Background Image" to include or exclude the background layer.
• Mark orders as "Done" to track your fulfillment progress.

Duplicating a Configurator

To create a similar configurator without starting from scratch, click the "Copy" button on any existing configurator. This duplicates the configurator including all its options, option values, and property configurations. The copy will appear with the same name — rename it to distinguish it from the original.

Step 7: Show Configuration Options in the Order Confirmation Email

The order confirmation email is a Shopware mail template. Because mail templates belong to the shop and can be edited by the merchant, the configuration output has to be added to the template once. This has to be done per shop and per language.

1. Open the template

Go to Settings → Email templates and open the template of type Order confirmation.

2. Select the right language first

A mail template is translated per language, and only the translation of the language the order was placed in is sent. Switch the Administration to the language you want to configure (language switcher in the top bar) before editing — the editor always shows the translation of the currently selected Administration language. Repeat this step for every language your shop sells in.

3. Add the column header (HTML)

In the Mail text → HTML editor, find the products table header and insert one cell directly after the Product image column:

To locate the position, search for Product image — the new cell goes immediately after that . Some shops have the column labelled in German (Produktbild); use whichever label the table actually shows.

4. Add the product cell (HTML)

Still in the HTML editor, scroll to the product row ({% for lineItem in order.lineItems %}) and insert one cell directly after the cell that contains the product image (the one with

5. Add the line to the plain-text mail

Switch to the Mail text → Plain text editor and insert this directly after the product description line:

{% if lineItem.payload.kilbCanvasSelectionDetails is defined and lineItem.payload.kilbCanvasSelectionDetails|length > 0 and lineItem.payload.kilbCanvasSelectionIncludeDetails|default(false) %}{{ 'kilb-canvas-configurator.selectedOptions'|trans }}: {% for kilbDetail in lineItem.payload.kilbCanvasSelectionDetails %}{{ kilbDetail.option }}: {{ kilbDetail.value }}{% if kilbDetail.text %} ({{ kilbDetail.text }}){% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
{% endif %}

6. Save and test with a real order

Click Save, then place a test order in the language you edited. The options appear as a Selected options column next to the product image, and each configured product prints its option/value pairs (including entered text) in that column.

Notes

• The admin's own Preview in the email template view cannot show the column: a preview has no order, so there is no product row to fill. Only a real order proves it.
• The column shows values only for products that were configured and whose configurator has Include configuration options in order confirmation email enabled. Products without a configuration simply leave the cell empty.
• The label uses the app's translation, so German shops show Gewählte Optionen and English shops Selected options. Both languages are shipped with the app.
• The header cell is unconditional and therefore always visible. If you do not see the header in a test mail at all, the snippets were added to a different language translation than the one the order was placed in.
• Saving the template in the Administration marks it as merchant-edited, so later Shopware updates will no longer overwrite your order confirmation template.