SVG Templates for the Product Designer

With an SVG template the product image follows the configuration: a tag is drawn as wide and high as your customer orders it, gets rounded corners or a hole, and the design zone for custom text or a custom image grows with it. You don't need a separate picture for every size and every variant.

Requirements

• Frontend engine V3. Legacy does not show the template. See Frontend engine: Legacy or V3.
• Combined product image. The template is the picture of a value in the combined product image, e.g. for the characteristic Paper. configento.app reads the design zone from the bottom picture, i.e. the base product. See Image Visualisation & Uploading Images.
• Characteristics with an internal name. The template reads values via a characteristic's Internal name (ID), e.g. $length for the length in mm.

How a template is built

An SVG template is an ordinary SVG file whose attributes contain placeholders in double curly braces. The configurator fills them again with every selection and draws the result into the product image.

<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="-2 -2 {{$length + 4}} {{$height + 4}}"
     width="{{($length + 4) * 4}}" height="{{($height + 4) * 4}}">
  <rect x="0" y="0" width="{{$length}}" height="{{$height}}"
        rx="{{$corners == 'round' ? 3 : 0}}" fill="#f4efe4" stroke="#cfc6b4" stroke-width="0.4"/>
  <circle cx="{{$length / 2}}" cy="8" r="{{$hole == 'none' ? 0 : 2.5}}"
          fill="#ffffff" stroke="#cfc6b4" stroke-width="0.4"/>
  <rect data-configento-zone="brandname" x="5" y="15"
        width="{{$length - 10}}" height="{{$height - 20}}" fill="none"/>
</svg>

• viewBox in millimetres. One unit in the template is one millimetre on the product. Here the tag is $length × $height mm, with 2 mm of space around it.
• width and height set how large the picture is drawn. The root needs width and height or a viewBox, otherwise the file is refused on upload.
• Rounded corners and the hole depend on select characteristics: $corners == 'round' ? 3 : 0 sets the corner radius to 3 mm when the value round is selected.
• The design zone is the rect with data-configento-zone (see below).

You can download this template as a starting point: hangtag.svg. Replace the names after $ with the internal names of your characteristics.

Placeholders

Inside {{ … }} goes an expression written the same way as in a formula characteristic:

• For select characteristics, compare with the entry's Value, not with its label.
• Numbers are rounded to three decimal places. If a characteristic is empty, the configurator uses 0.
• Placeholders work in attributes, e.g. in width, rx, fill or viewBox.
• Write < and > as < and > in the SVG file, e.g. {{$length > 80 ? 4 : 2}}. The configurator converts them back before calculating.

Defining the design zone

A rect with data-configento-zone="…" defines where a custom text or custom image sits. Enter the Internal name (ID) of the characteristic of type Custom text on the product or Custom image on the product there.

• x, y, width and height of the rect are the position and real size of the zone in mm. configento.app uses them to calculate font sizes and a picture's resolution.
• The zone from the template takes precedence over the zone drawn in the editor, and over Width from and Height from.
• With fill="none" the rect stays invisible.
• The template needs a viewBox for this.

Several characteristics each get their own rect. The price check at the cart reads the template as well, so size and resolution in the order match the browser.

Background for the contrast check

If a custom text checks the contrast, the template can supply the background. Give the design zone's rect data-configento-bg:

<rect data-configento-zone="brandname" x="5" y="15"
      width="{{$length - 10}}" height="{{$height - 20}}" fill="none"
      data-configento-bg="{{$card == 'black' ? '#1a1a1a' : '#f4efe4'}}"/>

The value must be a six-digit hex colour such as #1a1a1a; empty means no check. If a Background is entered on the custom text under Contrast check, that one applies.

Safe margin and hole

Cutting or punching can take something off at the edge. Two attributes keep text and pictures away from it:

• data-configento-safe-mm="3" on the design zone's rect: the distance in mm that text and pictures should keep from the edge of the zone.
• data-configento-keepout on a rect, circle or ellipse: an area that has to stay clear, e.g. the hole of a tag. Write the attribute as data-configento-keepout="", since SVG requires a value. Keep-out areas apply to every design zone, also from a layer above, for example for the characteristic Hole, if its template has the same viewBox.

<circle cx="{{$length / 2}}" cy="8" r="{{$hole == 'none' ? 0 : 2.5}}"
        fill="#ffffff" data-configento-keepout=""/>
<rect data-configento-zone="brandname" data-configento-safe-mm="3"
      x="5" y="15" width="{{$length - 10}}" height="{{$height - 20}}" fill="none"/>

If a text or picture comes closer to the edge than the margin or touches the hole, the field shows “Too close to the edge or the hole: this part may be cut off or punched out.” Whether the configurator only warns or also blocks the cart is set on the characteristic. More: Custom Text on the Product and Custom Image on the Product.

Uploading

Upload the template like any other picture on the value (SVG up to 5 MB). On upload, configento.app cleans the file:

• Scripts are removed.
• References to files on other servers are removed, e.g. linked pictures. Embed pictures directly or add them as a separate layer.
• Placeholders and data- attributes are kept.

360° pictures cannot be SVG files.

Troubleshooting

1. The file is refused on upload: The root <svg> has neither width and height nor a viewBox.
2. A shape has size 0 or disappears: The placeholder results in 0. Check the Internal name (ID) including upper and lower case, and whether the characteristic has a value.
3. A comparison never matches: Compare with the entry's Value, e.g. round, not with the label Round.
4. The text stays in the old place: data-configento-zone must carry exactly the internal name of the text or image characteristic, and the template needs a viewBox.
5. The contrast is not checked: data-configento-bg does not result in a six-digit hex colour, or the text has no Min. contrast.
6. The hole is ignored: The shape with data-configento-keepout is not a rect, circle or ellipse, or its layer has a different viewBox from the template.

Next steps

• Custom Text on the Product
• Custom Image on the Product
• Formulas & Calculations
• Image Visualisation & Uploading Images