Variable Settings

Variable Settings panel:

General Settings

The name of a variable is the underlying code, used for tagging purposes throughout the document. An alternative display name can be entered, which is the label shown to the end user in the variable Input Form. It is not recommend to use special characters (example single quote ') in variable names since it can cause error on some webservice functions.You can use special characters in display names instead.

Visibility of a variable inside the Input form can be influenced in a number of ways:

• The visible checkbox can be used (either manually or by using a display action). Variables which don't have this setting checked, won't be shown in any input form

• The display filter can be used in combination with a filter in the Input Form Panel's properties. In that case, only variables with a matching filter will be shown inside the relevant panel. Multiple Panels can be configured, to show different sets of variables

• Locked
  Locking the variable, will show a read-only version in the input panel, for end users of the Editor.
  The variable is still accessible / editable through the API or when using a DataSource.

For more information on display filters, see Conditional Interface Elements

When a Snippet is placed in a master document, it may also contain variables (which can be edited through a separate input form, based on the selected snippet). For some variables in the master document, you can check "Apply to snippets", which means that changes in the variable of the master document will also be pushed in any placed snippet. By default this is not enabled (as multiple snippets tend to be placed, with separate product or other information). Matching of the variables is done based on their name.

A variable's prefix and suffix will be added to the value entered by the user, before that value is inserted into a text frame. If no value is provided, the prefix and suffix also won't be included in the text frame.

User info for a variable is displayed either as a tooltip (default behavior), or as a label under the variable's input form item, if the matching checkbox has been checked by the administrator.

An individual variable can have any paragraph where it appears removed if it does not have a value (see ?Suppressing Lines for more options)

Data Types

• short text, long text and formatted text present the user with options for entering textual information

• A calculated field has no input option at all, but has an additional document action ("Value"), which can return its value. See lower

• an Image variable is presented to the user as a choice of images from a variety of repositories

• A number variable is presented in the Input Form as a numeric stepper

• A checkbox is visualized as a true/false checkbox

• A date variable allows the user to choose a date

• A list variable can be presented as a pulldown or as a list of checkboxes (with multiple items being selectable)

• a table variable is presented as an input grid, and will be placed in the text frames as tab delimited text

• color, paragraph style, character style and font variables allow for selection (and in some cases modification) of resource items. Note that these input types are mostly used by actions, and do not offer a lot of control over use throughout the document (see ?Common Document Actions for examples which might be more suited to your needs in those cases)

• coordinate variables are presented to the user as an input of a measurement unit, taking into account the current document's viewpreferences (mm, pt, in, ...), and also allowing the basic calculations. These again are most often used by document actions

• divider variables allow you to insert a divider into the Input Form

• button bar variables allow you to configure buttons (or icons) with attached document actions

• Structured Text (new in 6.3 & 2020.3) a variable that allows structured text in the content, mapped to styles

Depending on the type of the variable, more "Type Specific" settings might be possible.

Short and Long Text

Short and long text allow you to limit the amount of characters (0 being an unlimited amount), and optionally show the status of that count inside the Input Form.

In either case, you can also specify the text direction (left to right, right to left, or inherited from the "Default text dir." configured for all variables).

For long text, you can also configure the height of the input form.

Formatted Text

Next to the height of the input form and the text direction (similar to long text), you can also specify which formatting options are available in the input form.

Image

The basic selection option for an Image Variable is through a popup. These popups can be configured similarly to the normal CHILI Panels for the source, by clicking the "Popup Properties" button.

You can choose to show a preview of the selected image inside the Input Form, by checking the matching checkbox.

Additionally, you can allow the user to crop the image. For each reference of the image inside the document in an Image Frame where the positioning is set to "Manual", a "Crop" button will appear in the input form.

Images from the CHILI DAM can also be limited additionally to a specific directory, in which case the Popup Properties become unavailable (no popup will be shown), and are replaced with other options:

• Entry of the directory (or reference to a variable which will hold the directory path, and which can therefore also be manipulated easily through Document Actions)

• Possibility to allow the user to upload new images to the specified directory

• Possibility to have the user ONLY upload new images. No other selection method is available in that case

Number

When working with a numeric input, various options are available to limit entry and configure the display value of the number in the document.

Checkbox

The underlying value of a checkbox is "true" (for checked), or anything else (by default almost always "false", unless the data type was modified) for unchecked. But if the checkbox also is referenced inside a Text Frame (rather than using document actions), you can also configure its checked and unchecked display values.

Date

The date variable type can be configured with a display format (which is the way the date is inserted in a variable Text Frame), and allows you various ways to limit the selection:

• Based on a number of days before and/or after the current date

• Based on an absolute start and/or end date

• By selecting weekdays which can't be selected

Any date matching one of the limitation criteria will not be selectable in the Input Form.

Examples of display formatting for february 7, 2030

• M/D/YY will display the selected date as: 2/7/30

• MM.DD.YYYY will display the selected date as:  02.07.2030

Supported formats

These formats are tested to work. Other formats or combinations might work also, but we guarantee these to work.

• DD/MM/YYYY

• MM/DD/YYYY

• YYYY/MM/DD

• M/D/YY

• D/M/YY

• DD-MMM-YY

• D MMMM YYYY

• DD.MM.YYYY

• MM.DD.YYYY

• YYYY.MM.DD

• D.M.YY

• M.D.YY

• MMYY

• YYMM

• YYYYMMDD

• DDMMYYYY

List

A list variable can be configured to hold multiple list items, with the option to hide certain items based on values of other variables. The "value" of each list item is optional, and will be used (if present) when the selected item is inserted into a variable Text Frame.

You can choose to have an empty list item prepended to the items by checking the matching checkbox.

A list is presented to the user by default as a pulldown, but can also be visualized as a checkbox list with the "Allow multiple items to be selected" option. In that case, the display value will consist of the various selected items, concatenated using the Concat Prefix/Suffix settings.

Table

A table variable is presented to the user as a data grid, with the configured columns.

When used in a variable Text frame, the value of a Table variable is inserted as tab-delimited text, and the tab settings for the paragraph where the variable is placed are used to position the various columns. If the "Include header" option is checked in the variable's settings, the display text will include the names of the columns as the first line.

Color, Paragraph Style, Character Style, Font

The choice of selectable items can be limited based on a filter on name.

Coordinate

For input of a measurement unit, you can constrain the user to optional minimum and maximum values.

Button Bar

Button bars can be configured to contain a set of buttons, each with an associated Document Action to be executed

Structured Text

A structured text variable can hold long text (behaves the same way) but can also contain tagged (structured) text.

This variable can then be mapped to a pre-defined mapping in the BackOffice, where you map tags to styles.

Actions

See Getting Started with Document Actions for an overview of possibilities of Document Actions. From the context of Variable Data, the following actions are possible. Note that for complex actions, it might make more sense to use Document Event Actions, which allow you to group logic for the entire set of defined variables.

Value

This action is only available for variables of type "Calculated Field". The action is triggered by any change in value of any variable, and should use the "return" statement to return a new value for the variable (often by combining the values of other variables).

On Change

The most commonly used action. It is triggered by any change in the value of the current variable.

Validate

This action should return a string (eg: "return string NOT GOOD"), and it will display this string as a warning to the user (similar to the "required" checkbox, which shows a warning/error to the user if the variable's value is empty).

Visibility

This action should return "true" or "false", and provides a fast way to influence the current variable's visibility in the Input Form. For more complex forms, the logic of showing/hiding variables can usually better be influenced in a centralized action (eg using a Document Event Action)

Notes

Both on the full Variable List and for individual variables, the "Notes" option allows administrators to document the configuration for future reference