User Manual Quickstart General Concepts Buyer Side Snippets Engraving Styles and Form Fields Flex Designs Sub Documents Scripting Workflows Editing Workflow Production Workflow Tutorial Videos Frame Features Resources Pages Layers Snippets Images Fonts Colors Styles Form Fields Template & Document Form Fields Create a Form Field Using Form Fields Pin to Frame or Document Form Field Properties Visibility Max Characters Is Mandatory Clear On Focus No Offensive Language Price Relevant Long Running / Update Thumbnails Control Group Digit Grouping User Interface Textbox Text Area Select List Image List List Filtering Data Table Color-List Image-ID Auto-Generated & Special Form Fields Form Fields and Snippets Account Portal Style Reference Change Log Known Bugs & Limitations Glossary Acknowledgements Api Reference Authorization Tokens Embedding The Editor Custom Integration Backend Api Price Display

Form Fields

Form Fields Overview

Form fields are used wherever one needs to use user inputs or choices across several frames or documents. Form fields can also be used to create nice looking user interfaces on the Buyer Side.

Before going in too deep, we recommend reading the general chapter about Styles and their best friends, form fields.

Pro Tip: Form fields can be copied over from a Template to a document (or vice versa) by selecting them and using either the context menu to copy and paste or simply pressing CTRL+C, CTRL+V.

Template & Document Form Fields

There are two different kinds of form fields:

Template form fields are globally usable across all documents.

Document form fields are local and only usable within the current document. This is mandatory for Snippets or any documents which will be used as Sub Documents in Snippets.

Use the tab on the top to switch between Template and Document form fields. Document form fields will have the name of the current document in square brackets [DocumentName].

Create a Form Field

To create a new form field use the Add Form Field button. Enter a name for your Form Field but don’t worry, it can be changed at any point later on.

By default, the created form field will be a standard text input that will simply ask for a text on the Buyer Side. This can be changed in the form fields properties.

Form fields can be sorted by clicking on the mover bar to the left and then dragged and dropped into place.

Form fields can also be grouped, which will create a grouped configuration for the Buyer Side. New Form Field groups can be inserted by the Add Form Field Group Add Form Field Group button.

Note: Global form fields will always be shown before local form fields within the same group.

Using Form Fields

Form fields can be used anywhere a text can be entered by using ${form.name} where ‘name’ is the name of the form field.

Form fields may also be used in Styles and therefore can be used as conditions for Styles. You can find a good example of conditional Styles used in conjunction with form fields in the Styles Wizard ‘Frame Position - Controlled by a Form Field’.

Pin to Frame or Document

Form fields can be pinned to a selected frame. That way they will only appear on the Buyer Side once the frame is selected. If the frame is a buyer step then it will also be zoomed to while editing. Clicking on the Pin icon shows the pinned frame/the first pinned document.

Form fields may also be pinned to a document. This way they only appear when a specific document is edited by the buyer. Form fields can be pinned to multiple documents.

See also: Steps Workflow in the Buyer Side chapter.

Form Field Properties

Especially for step interface Template purposes, it can be very useful to pin a form field to a document(s). So when the pinned document is shown, the form field is shown like always, but for all other documents the form field is not shown anymore. This allows for form fields which can be used in every document but will only be shown in a specific document/configuration step.

Click here to see Pin To Frame example in the Form Field & Styles Chapter.

Form Field Properties

Form fields create a user interface for entering data with just the right UI elements.

Form Field Context Menu

To open the Form Field properties, right-click anywhere on the form field or click to the left of a form field (besides the mover) to open the Context menu and select Properties.

The properties dialogue opens:

Form Field Properties

Form Field Name

Sets the name of the form field (except for auto-generated form fields where the name is fixed). The name has to be unique in its scope and can only contain characters and numbers without spaces. This name is used later on when addressing the form field in expressions.

Label

This is the display name for the form field which is used in the Buyer Side interface.

Data Type

Data Type
The data type defines what type of data will be stored in the form field:

Label

Number Type

If Number was selected as the data type, the number type defines the type of number stored:

Visibility

Defines if the form field should be visible on Buyer Side (default) or only in Designer Side.

Form Field Visibility

Form fields can be shown conditionally (conditional disclosure). This is useful in all situations where a specific option should only be shown to the buyer if another form field has a certain value.

For example, you allow adding an envelope and the buyer to select the envelope color. Then the form field for the envelope color will be conditionally shown based on whether the envelope option was chosen.

Form Field Conditional Disclosure

The condition must be a valid JavaScript instruction returning a boolean value. One can use form, info, label, and data fields here. Result will give you an indication of the outcome where true means the form field will be shown and false means the form field will be hidden.

Edit Condition will open the condition editor which allows for easy creation and editing of the visibility rule.

Condition Editor

Please read about the condition editor in the Styles chapter here.

Max Characters

Form Field Visibility
Define the maximum characters a buyer can input. A warning message is shown once the buyer enters more than the predefined number of characters.

Is Mandatory

Form Field Visibility
Defines if changing this form field is mandatory. A warning message is shown if the buyer does not change the form field. This lets you avoid example values getting into the ordered product.

Clear On Focus

The default content of this form field will be cleard when the buyer starts editing.

No Offensive Language

Enables the check against a predefined offensive word list (either supplied in the account preferences or supplied via API).

Price Relevant

Price Relevant is an indicator to a connected e-commerce system that this form field represents a potential price change or option. This will not have any effects within the Editor, but it will trigger a callback in the frontend API to allow for price changes in the shop page when this form field is changed (e.g., for a product option).

Long Running / Update Thumbnails

This option force update of all editable doc thumbnails (only in conjunctions with live-update icon-mode) it will also indicates a long-running script or big visual change e.g. complete resize of a multipage document.

Control Group

Control Groups allow to group form fields into one line. eg. to have a area code selection and a phone number in one line but still separated. Simply select one Control Group for several form fields. The form fileds will then be shown in their order from left to right. You have up to 5 Control Groups available.

Control Group

Pro Tip You can make a grouped Form Field inside a group smaller by setting max characters. See this example where we set max characters of the area code to 5: Control Group

When using control groups in single or multiline text - you can use ${group._(x)} syntax to address a form-field control-group instead of concatenate all members. This additionally has the advantage that only the first control group members text-before and last control group members text-after will be used and only if the entire group has a value.

Digit Grouping

Printess allows for easy digit grouping for phone numbers. Number Type

Digit grouping works best if you split up a phone number into its components like in the above Control Group example. So you should not try to format a complete number.

Digit grouping works with groups of characters and also define where characters which do not match the pattern are added (the *).

Try selecting some formats from the list and observe the outcome both for you current form field value and an example value.

Imagine you’d like to format a cell phone number in the pattern ‘111 22 333’ then the pattern of choice would be ‘### * ###’ which will first fill one pattern of three letters and then tries to create as many 3 letter pattern from the right as possible and put the remaining letters (up to 2) after the first three letter pattern which will give the desired output when ‘11122333’ is entered.

In our Business Card Example we use this feature in conjunction with Control Group to achieve a good user experience for entering a phone number.

BC Example

User Interface

This defines how the form field should be presented:
Number Type

Textbox

A simple text field to enter text:

Add Form Field

Additionally, one can set Text-Before or Text-After in the form field properties, which will add additional text before or after the entered text (but only if the entered text is not empty).
This can be very useful if e.g., one creates a business card where a fax nr. can be entered, and when entered it should be prefixed with (Fax: __). If a number is not entered here, then the complete line will be omitted.

Note: Within these fields one can also use special formatting options:

A paragraph Style will create a new paragraph at the end of the paragraph <p:> and nothing can be added after it.

Additionally, one can insert special characters:

\t to insert a tab
\n to insert a newline
\f to create a formfeed which in the event of text overflow between frames means, “please continue in the next frame.”

A nice example of using Text-Before and Text-After is shown in our Business Card example. Please have a look at the “phone” form field in the linked Template.

Text Area

The text area is meant for text input spanning several lines of text. It does not support Text-Before or Text-After.

Text Area

Select List

The values will be presented as a drop-down list for the buyer to choose from. Besides being able to define displayed values that are independent of the value returned, one can also define the images that will be displayed within the drop-down.
A select list is useful for letting a buyer choose from different options. Besides the value, there are three different elements that can be displayed for selection:

All elements can be used together or alone. This is an example where all three elements are used:

Select List Example

And these are the corresponding settings in the form field properties:

Select List Settings

Image List

The values are represented by images. Image appearance, selection, and hoover state are configurable via standard CSS properties. The image must have been previously uploaded in the Images tab.

Image List Example

The image-list type is made for all options where every value is represented by an image. All options are shown together and it features a CSS controllable appearance and hover effect.

Image List Settings

The label text will be used as a tool-tip when hovering over an image, the info text content will not be used.

The List Image Width and Height properties define the box (in pixels) that the image will be proportionally scaled into.

Form Field Table

Note: Besides using ${form.name}, one can also use ${label.name} and ${info.name}. With the help of a Style ${image.name} can directly assign an image used in a form field to a frame by assigning it to the image property in the Style. A good example of this is the demo document T-Shirt Configurator where the T-Shirt image is directly taken from the form field’s image value.

List Filtering

List filtering comes super handy when you’d like to filter a select-list, image-list or color-list by a category. The values used to filter down the list must be entered into the info column of the to be filtered list. To enable filtering select a second form field containing the categories (in the value field). As a helper the form fields selected by the current value of the category drop down are highlighted in green and the current value is also shown when selecting the form field. Note that the filtering will only be in effect on buyer side.

Filtered Example

Once a new category is selected in the Category form field Printess will also make sure that the filtered form field will show a valid value.

Write content to other form fields

Additionally one can use Write to Second Form Field to write the content of either the value, label, info, or tag field of your list to another form form field (into the value). In the above example we fill the text type form field ‘Titel’ with the value of the product list e.g. Cheese Burger. Write to Second Form Field can also be used without filtering.

Filtered Example

Please have look into our Menu Card example and try it yourself.

Data Table

If the data type of a form field is set to Table, the Buyer Side will show a table editor where the buyer can enter data and add or delete rows.

Data Table

To create a data table choose Table as the data type and then define the number of columns and their edit options in the form field’s properties.

Data Table settings

For each column one can define:

Once the columns of the table are defined one can add default values by closing the properties dialogue and pressing the + on the top-left of the table then entering values into the newly created row(s). Once finished entering the default values, press the Apply button below the table.

Internally the values of a table are represented as an array of row objects and their named properties. One can also export and import the values in a table as a JSON string via the context menu of the form field.

Data Table settings

Select Copy JSON and the content of the table will be copied to the clipboard in JSON format. The above table will look like this:

[{"event":"Holiday","text":"New Year's Day","day":3,"month":1},{"event":"Holiday","text":"Good Friday","day":15,"month":3},{"event":"Holiday","text":"Easter Monday","day":18,"month":4},{"event":"Holiday","text":"Early May Bank Holiday","day":2,"month":5},{"event":"Holiday","text":"Spring Bank Holiday","day":2,"month":6},{"event":"Holiday","text":"Boxing Day","day":26,"month":12},{"event":"Holiday","text":"Christmas Day","day":27,"month":12},{"event":"Birthday","text":"Peter Müller Birthday","day":26,"month":12},{"event":"Birthday","text":"Gabi's Birthday","day":1,"month":1},{"event":"Birthday","text":"Hans' Birthday","day":4,"month":1}]

Now the table contents can be edited and (by selecting Paste JSON) copied back into the table. Note that if one adds a property in the table which currently has no column, the table control will not display it until you add the respective column.

Pro Tip: One can use the Table form field to store structured data for use in the document without showing it to the buyer by switching the visibility to Designer Side.

Please read more about tables and the use of scripting in the scripting section.

Color-List

The color-list user interface allows for a simple color selection on the Buyer Side.

Color List Settings

By entering a Hex RGB color value in the value column, the color-list displays a color patch with this color to the buyer.

If you want to set colors with a form field you can either use the value directly in a Style’s color property or if you need to address named Spot or CMYK colors use the label or info column to do so.

On the Buyer Side a color selection with color patches is shown below. The size of the color patch can be controlled with the List Image Width and Height properties.

Data Table settings

Image-ID

The Image-ID form field can be used in all situations where you would like to let the buyer choose one image and distribute it across multiple image frames in one or many documents. That’s why you need to also define the default image size and aspect ratio in pixels.

Image-ID Form Field

With this information, Printess will automatically show a matching crop option whenever the buyer uploads an image.

Note: To get a working example one can also use the Style Wizard. Press Open Style Wizard on top of the Styles tab and choose Image Frame Linked to ‘image-id’ Form-Field. This will create a frame with the connected Style and Image-ID form field.
Read More about the Style Wizard here.

Image-ID Form Field

To use the Image-ID form field one needs to define a Style that is assigned to the image. Then this style can be assigned to all frames which should show the uploaded image.

.ffImage {
 image:${form.Image};
}

Auto-Generated & Special Form Fields

Auto-generated form fields are a handy way to expose content when Sub Documents are used on the Buyer Side. Sub Documents may be placed several times in one document and every occurrence needs to be configured with its own form field.

Single Line Text & Multi Line Text

Single Line text frames as well as Multi Line text frames can expose auto-generated form fields by enabling Show as Form Field. They will be generated on the document level.

Some functionality is available only with auto-generated form fields:

Layer Visibility

Layer Visibility can be controlled by an auto-generated form field. For this one needs to enable Show as Form Field in the Layers Context menu. A new form field will appear in the document’s form fields. Please also see the layer resources chapter.

Sub Document

The selected spread (the page) of a Sub Document can be controlled with a form field. Enable Show as Form Field in the Sub Document feature tab. The Sub Document must have named spreads. Please read the chapter on Sub Document frame features.

Color Scheme

If a color scheme is available (at least one color exists two times with the same name in different color groups), it will create a Template-wide form field used to automatically control color scheme selection.
Learn more on Color Schemes here

Note: Change visibility of the form field to Designer when a color scheme is controlled via user interface buttons.

Click here to learn more about Buyer Side user interface elements.

Matrix Products

The Matrix Product feature is ideal if you would like to present multiple configuration options for a product with side effects e.g., a different artwork area or a different product image.

Whenever a Matrix Product is configured, a form field with the product choice is created. The properties of the form field can be edited as with all other form fields (but it must remain a list type).

Matrix Products can be configured via enabling Show Layer Matrix in the Settings menu on the top-right bar.

Matrix Product Visible

This will show the matrix table at the bottom of the window:

Matrix Product Table

Within this table one can add additional rows by pressing the + button and entering a selection value. The trashcan icon can be used to delete a row.

The Matrix Product is a powerful way to control visible layers by product selection. The controlled layers can be from any document within the Template. This also makes it possible to control layers of contained Sub Documents.

If you’d like to add a layer of a document to be switched by the Matrix Product, switch to the document and then select the layer to be controlled by clicking on the triangle beside the Visible Layers headline. Here you can select the layer and a new column will be added to the Matrix Product.

Now one can switch all layers within a row to either visible or invisible with the eye icon in each column.

The example Sign Template contains a great example of what is possible with a Matrix Product.

Sign Example

This example contains multiple product options which are controlled by enabling or disabling layers. Not all options are available for different sign materials - but with the Matrix Product this is easy to implement!

The product options are visualized via Sub Documents that have multiple spreads and a form field to select them. In the below example, it is the Sub Document containing the drill holes for the sign which is placed on a layer called HOLES. When HOLES layer visibility is changed in the Matrix Product table, the corresponding drop-down will appear or disappear:

Matrix Product Sign Example

Document Size

A special form field type is the DOCUMENT_SIZE form field, which controls the size of the actual document. To enable it, right-click on the document for which you’d like to enable size control and select Get Size from Form Field:

Document Size enabled

If it does not already exist, this creates a Template form field named DOCUMENT_SIZE and a select-list or image-list with all available document sizes to choose from. By default, the size of the actual document is added as the first list entry. In the values column, one must enter simple value combinations of width x height (e.g., 22x29.7). Now whenever this form field is changed, the document size will adjust accordingly.

Note: The values in the list are always interpreted with the setup document unit.

Learn more about document settings here.

Form Field Properties

If several identically sized entries are necessary for a configuration, one must add letters at the end. For example “10x21a” and “10x21b” will result in the two documents of the same size, but each retains a unique key which is necessary for a select list.

There can only be one Template-wide document size form field which will change the size of all documents when Get Size from Form Field is enabled.

Sometimes you will need a diffrently sized print document. e.g. see our canvas example where additional print area is needed to cover the frame. As there can be only one Document Size Form Field Printess allows to add fixed offsets for Production documents. If a document is a Production document and has Get Size From Form Field switched on, you can add these offsets at the bottom of the document settings.

Form Field Properties

The above setting will always add 4cm to the width and height selected in the Document Size Form Field.

Please also read our chapter on the superpowers of Flex-Designs here.

Single Line and Path Text
For Single Line texts and Text on Path, auto-generated form fields are possible as well by simply switching on Show as Form Field in the Text/Text On Path tab.

All auto-generated form fields cannot be deleted - instead they must be switched off or the condition they appear on must be removed/changed.

One can change all properties of an auto-generated form field like with every other form field.

Form Fields and Snippets

When working with Snippets be aware that all form fields and Styles will not be imported into the document where they are inserted. So instead of using form fields, one should use the Buyer Side configuration options for frames. In the case of Layout Snippets, you may want to add groups to group frames and their configurations.

Another possible concept is to have the form field in the document where the Snippets are inserted and all the other Snippets will ‘listen’ to this form field (e.g., called ‘name’). This method lets one quickly and easily create prefilled Snippets.