Form Fields

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

We recommend to also read the general chapter about Styles and their best friends, Form Fields, before going into too deep.

Pro Tip: Form Fileds can be copied over from Template to Document or vice versa by selecting them and then either use the context menu to copy and paste or by 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 in the current document. This is mandatory for Snippets or 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, it can be changed 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 (s.b.).

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 where a text can get entered by using ${form.name} where ‘name’ is the name of the form field.

Form fields might also be used in Styles and therefore also as conditions for styles. One can find a good example for conditional Styles in conjunction with form fields in the Styles Wizard ‘Frame Position - Controlled by a form field’

Form Field Properties

Form fields also 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 beside the mover to open the Context menu and select Properties.

The Properties dialogue opens:

Pin to Frame

Document form fields can also get pinned to a frame. That way they only appear on buyer side once the frame is selected.
Note: one must first select a frame and then open the Properties menu of a Document Form Filed to see this option.

Please see Pin To Frame Example in the Form Field & Styles Chapter here

Form Field Name

Sets the name for 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 is the name used later on when addressing the form field in Expressions.

Label

This is the display name for the form field which will get 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 (neccessary if the form field value should get used in Script calculations)

Number Type

If Number was selected as Data Type the Number Type defines the type of Number stored.

• integer a positive or negative number without fractions like -1 or 2
• float a number with fractions like 1.41
• month kind of a special number but really useful when dealing with calendar calculations this Value can only be between 1 and 12 and automatically overflows. so if you write 13 into this number type it will overflow to 1.

Visibility

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

Impact Price

Impact Price 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.

Long Running

This option indicates a long running script or big visual changes which should be indicated to the Buyers - this is recommended whenever changing 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: __). Otherwise, the complete line should be omitted.

Note that 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. Note that 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:> Note that a Paragraph Style will also create a new paragraph at the end of the paragraph (<p:>) and that 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 case of text flow 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 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 inside the drop-down.
A Select List is useful for letting a user choose from different options. Besides the value, there are three different elements that can be displayed for selection.

• A label - displayed in bold if info text is present
• A info text
• An image (upload 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 property defines the box (in pixels) that the image will be proportionally scaled into.

Note: Beside using ${form.name} one can also use ${label.name}, ${info.name} and with the help of a Style also ${image.name} you 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 fields 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 as well as add or delete rows.

To create a Data Table choose Table as Data Type and then define the columns and their edit options in the Form Fields properties.

For each column one can define:

• The name: must be a unique name without spaces
• The data (type): can be string, number or boolean (will show a check box)
• Optionally a list of possible values to present 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 checkbox).

Once the columns of the table are defined one can add default values by closing the properties dialogue and adding rows by pressing the + on the top-left of the table and 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. For the above table this 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 this can be edited and by using Paste JSON copied back from the clipboard 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 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.

Auto-Generated & Special Form Fields

Auto-generated form fields are a handy way to expose content when subdocuments are used in Buyer Side. Sub Documents may be placed several times in one document and every occurrence therefore needs to have its own form field for configuration.

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 form fields. Please also see the layer resources chapter.

Sub Document The selected spread (the Page) of a Sub Document can be controlled by 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 to control color scheme selection automatically.

Note: Change visibility of the form field to Designer in case the 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 one would like to present multiple configuration options for a product which have side effects like 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 like with all other form fields but it clearly must stay 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 an additional row by pressing the + button and entering a selection value or use the trashcan icon to delete a row.

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

If one likes to add a Layer of a Document to get 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. There one can select the layer and a new Column will be added to the Matrix Product.

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

The example template ‘Sign’ contains a good example of what is possible with a Matrix Product. Click here to explore the Sign Example Template!

It contains Multiple product options which are controlled by enabling or disabling Layers. Not all options are available for different sign materials - with the Matrix Product this is easy to implement.

The product options are visualized via Sub Documents having 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 this layer gets switched by the Matrix Product table also the corresponding drop-down will appear and 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, go to the settings menu on the top right bar and check Show Document Size Form Field.

This Creates a Template form field with DOCUMENT_SIZE as the name and creates a select-list or image-list with the document sizes to select from. By default, the size of the actual document is added as the first list entry. In the values, one must enter simple value combinations of width x height (e.g. 22x29.7). When this form field is changed, the document size will adjust accordingly.
The values in the list are always interpreted with the setup document unit. One can learn more about document settings here.

There can only be one template wide Document Size form field - it will always change the size of the currently shown document.

Please see also our chapter about the superpowers of Flex-Designs.

Single Line and Path Text
For Single Line text and Text on Path auto-generated form fields are possible as well (Switch 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 still 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 and in the case of Layout Snippets you may add Groups to group Frames and their configuration.

Another possible concept is to have the form field in the document where the snippets are inserted and all the snippets will ‘listen’ to a form field e.g. called ‘name’. This way one can create prefilled Snippets.