Understanding the Position Parameter

Several engraver methods use a position parameter to select one of the options configured for a personalization element, such as a font, color, preset image, or vector. This article explains how the position parameter works and how to determine which value to use.

What is the position?

The position is a 1-based index that corresponds to the order in which options were added to a personalization element in the Design Studio. The first option added is position 1, the second is position 2, and so on.

The position parameter always refers to the options configured on the template in the Design Studio—not the options displayed in your option set. If an option isn't configured on the template, it can't be selected using the position parameter, even if it exists in your option set.

Options can be configured directly on a personalization element in the Design Studio or provided through a library. If the order of the options changes—either by reordering them on the personalization element or within the library—the position values are updated to reflect the new order.

Where do options come from?

Options can come from two sources:

Element options

These are fonts, colors, or images added directly to the element in the Design Studio. For example, a text element might have three font options configured on it:

engraver.setFont(1, 2); // Sets Roboto on text element 1

Libraries

Libraries are collections of fonts, colors, or images that can be linked to one or more personalization elements. When an element is linked to a library instead of having its own options, the position indexes into the library's options.

For example, a color library shared across multiple elements:

engraver.setFontColor(1, 3);   // Sets Green on text element 1
engraver.setImageColor(5, 3);  // Sets Green on image element 5 (same library)

The position parameter works the same way regardless of whether the options are stored on the element or in a library.

Methods that use the position parameter

The following engraver methods use a position value to select one of the available options configured for a personalization element.

Examples

The examples below show how the position parameter is used with different engraver methods.

Selecting a font

// Text element 1 has fonts: [Lato, Roboto, Montserrat]
engraver.setFont(1, 1); // Lato
engraver.setFont(1, 2); // Roboto
engraver.setFont(1, 3); // Montserrat

Selecting a font color

// Text element 1 has colors: [Black, White, Red]
engraver.setFontColor(1, 1); // Black
engraver.setFontColor(1, 3); // Red

Selecting a preset image

// Image element 3 has preset images: [Cat, Dog, Bird]
engraver.setPresetImage(3, 1); // Cat
engraver.setPresetImage(3, 2); // Dog

Selecting an image color

// Image element 5 has colors: [Gold, Silver, Bronze]
engraver.setImageColor(5, 1); // Gold

Selecting a vector color

// Vector element 2 has colors: [Red, Blue]
engraver.setPresetVectorColor(2, 2); // Blue