Form Fields
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 
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 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’.
Form Field Properties
Form fields create a user interface for entering data with just the right UI elements.
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:
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.
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 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
The data type defines what type of data will be stored in the form field:
- String - basically any text.
- Table - a table with rows and columns.
- Number - a number (necessary if the form field value will be used in script calculations).
Number Type
If Number was selected as the data type, the number type defines the type of number stored:
- Integer - a positive or negative number without fractions (e.g., -1 or 2).
- Float - a number with fractions (e.g., 1.41).
- Month - kind of a special number but really useful when dealing with calendar calculations. This value may only be between 1 and 12 and automatically overflows. So if you write 13 as a month number type it will overflow to 1.
Visibility
Defines if the form field should be visible on Buyer Side (default) or only in Designer Side.
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.
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.
Please read about the condition editor in the Styles chapter here.
Max Characters
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
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
This option indicates a long-running script or big visual change which should be indicated to the buyer. This is recommended whenever a change in the form field may take longer than one or two seconds to show up in the Editor.
User Interface
This defines how the form field should be presented:
Textbox
A simple text field to enter text:
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:
-
<w:styleName>Text with Style<w:> adds a character style before the text and reverts it after the text. You can also let the style span the complete text by starting in the text before and putting the <w:> in the text after.
-
For Multi Line text, it is sometimes useful to use a paragraph Style.
<p:styleName>Text With Paragraph Style<p:>
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.
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:
- A label - displayed in bold if an info text is present.
- An info text.
- An image (uploaded in the image tab).
All elements can be used together or alone. This is an example where all three elements are used:
And these are the corresponding settings in the form field properties:
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.
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.
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.
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.
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.
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.
For each column one can define:
- The name - must be a unique name without spaces.
- The data type - can be a string, number or boolean (will show a check box).
- Optionally, a list of possible values to present in a drop-down to the buyer (except for boolean which will always show a check box).
- A width for the column in pixels (this will be ignored for boolean columns as they only span the width of the check box).
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.
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.
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.
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.
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
Read More about the Style Wizard here.
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.
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.
This will show the matrix table at the bottom of the window:
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.
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:
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:
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.
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.
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.