Editing variables

Variables are added and edited in the Dictionary Editor. The Dictionary Editor is opened by clicking the Dictionary Editor button on the Contract Express tab in Word. When the Dictionary Editor is opened click on All Variables to access the list of variables in the current document.
For a quick introduction to adding new variables see Creating a new variable and inserting it into a template. For an introduction to the features and functions of the Dictionary Editor see Using the Dictionary Editor.
This topic covers the editing of variables, specifically their attributes.
When a variable is selected in the Dictionary Editor the attributes of the variable are visible in the attributes panel. The attributes panel appears below the variable list when the Dictionary Editor is docked in the task pane, or to the right of the variable list when the Dictionary Editor is undocked.
The attributes are organised into the following tabs:
  • General
    : Most commonly used attributes such as Name, Question and Compulsory
  • Guidance
    : Contains both Guidance and Preamble
  • Constraints:
    Selections, default value, character lengths
  • Computation
    : Definition for computable variables
  • Document:
    Including the default format and case
  • Usage:
    relevancy and author notes
Each attribute is described below.

General Tab

Attribute: Name
Specifies the name of the variable.
Note that variable names are not case-sensitive, so
BuyerName
is the same as
buyername
and also the same as
BUYERNAME
. However, the name as it appears in the Dictionary Editor is the name that appears elsewhere in the
Contract Express Author
UI, such as
the
expression editor
.
If the name of your variable includes a space or any character outside of the letter characters from the Latin-1 Supplement or Latin Extended-A unicode character set, then the Dictionary Editor will automatically add single quotes around the variable when the variable is added into a field in the template.
Attribute: Question
Specifies the question text that is displayed on the questionnaire displayed to end users. This can have rich text formatting using the rich text controls above the text box.
Attribute: Type
The type of the variable primarily determines how its value is collected on the questionnaire, and secondly how that value appears in a generated document.
The type of a variable determines the kinds of values that can be entered into the field on the questionnaire and how that information can be used in your master document. For example, when
Contract Express
encounters a date type it will add a field and a calendar popup box on the questionnaire page. When displaying the answer to this date in the generated document you can choose whether to have it display in short form eg 01/01/2008, long form 1st January 2008 or a custom format.
The type of variable also determines how you can manipulate that variable in your master document. A variable whose type is set to a number can be used in numeric calculations. For example, it is possible to add two number variables together and put the resultant calculation into a field in the document.
Variables that ask the user to choose from a series of selections are well suited for controlling the inclusion of conditional text. This is because each item of conditional text is based on some pre-configured option, rather than a number or free text.
Type
Description
Text
Any single row of text
MultiLine Text
Any multi-line text
Text Selection
A list of
text
selections from which one or many can be chosen (see special note below)
File Upload
A path to a document to be uploaded and re-generated
Yes/No
Yes or No options
Whole Number
A whole number, including positive and negative numbers but no decimals
Decimal Number
Any number, including positive and negative whole numbers and decimal numbers
Date
Any date
Time
Any time
Entity
A collection of data values from multiple variable types
Computable
Derived from an expression. Could be a calculation containing number variables, a concatenation of text variables or a business rule based on multiple text selections with "AND" and "OR" operators
Attribute: Presentation
This attribute is only pertinent for
Yes / No, Date, Time, Whole Number
and
Text Selection
variables. The presentation determines how values are presented, and thus collected, on the questionnaire.
The options available in the presentation drop-down list vary according to the type of variable.
Presentation:
Yes/No Variables
The presentation options are:
Radio Buttons
the user is presented with a pair of radio buttons representing Yes and No
Radio buttons representing yes or no
Check Box
the user is presented with a single checkbox representing Yes (checked) and No (un-checked)
single checkbox with option yes/no
Presentation:
Date Variables
The presentation options are:
Calendar
the user is presented with an edit box and a button which invokes a popup calendar
calendar with edit box
By Format
the user is presented with a mixture of edit boxes and drop-down selections that are determined by the year/month/day ingredients in the variable's default format
Date by Format
Presentation:
Time Variables
The presentation options are:
Clock
the user is presented with an edit box and a button which invokes a popup clock
Time Clock
By Format
the user is presented with a mixture of edit boxes and drop-down selections that are determined by the hour/minute/second/ampm ingredients in the variable's default format
Time by format
Presentation:
Whole Number Variables
The presentation options are:
Edit Box
the user is presented with an edit box in which the whole number value can be entered
Edit Box where whole number value can be entered
Calculated From Repeat
the question does not actually appear on the questionnaire, but is calculated as the number of repetitions created for one or more repeated variables
N/A
Presentation:
Text Selection Variables
The presentation options are:
Single Select Dropdown
the user is presented with a drop-down list from which one and only one option can be chosen
single select dropdown
Single Select Radio Buttons
the user is presented with a group of radio buttons of which one and only one radio button can be pressed
single select buttons
Multi-Select List
the user is presented with a select box containing options from which none, one, many or all can be chosen
Multi select list
Multi-Select Ordered List
the user is presented with a select box containing options from which none, one, many or all can be chosen; selected options are moved to the right where up and down arrows can be used to change the order in which they should appear
Multi select order list
Multi-Select Checkboxes
t
he user is presented with a group of checkboxes of which none, one, many or all can be checked
multi select checkbox
Searchable List
the user is presented with an edit box - as they type characters a select box appears which contains options that match what they have typed - one and only one option can be chosen. Searchable lists must always be dynamically built.
manual multi searchable
Presentation:
Multiline text variables
Rich Edit
the user is presented with an edit box with various formatting options. This is for populating HTML fields.
Note that an "Include HTML" statement is required to display the formatted text correctly in the generated document.
Multiline rich text
Attribute: Compulsory
Specifies whether the question is compulsory (checked) or non-compulsory (un-checked). When compulsory is checked, the question must be answered by the user. A compulsory question is indicated on the questionnaire by the presence of a red asterisk, between the question and the value field. Contract Express will not allow any questionnaire page to be submitted if it contains a relevant compulsory question that has not been answered.
Attribute: Key Question
Specifies whether it is a key question (checked) or not (un-checked). The questionnaire can be configured so that it only contains key questions. This can be achieved by creating a new profile in
Contract Express
and changing the setting
Display a subset of questions on the questionnaire.
Attribute: Exclude from Questionnaire Completeness
When a question is optional and a value is not required to generate a complete document, it can be excluded from the questionnaire completeness calculation so that the questionnaire shows as complete even if they are not answered.
Answers to such questions will not be taken into account when the page completeness and the overall progress of the questionnaire is calculated. For example, imagine a questionnaire page that contains several address fields including Address Line 2. If this variable is marked as excluded from the questionnaire completeness, the questionnaire page will display the green checkbox of completion even if Address Line 2 field is left blank.
Attribute: Auto-trim
When the auto-trim attribute is enabled, any leading and trailing space characters will be automatically removed from the text that is entered into questionnaire. It is particularly useful when the corresponding field in the document has punctuation on either side.
This attribute is relevant to text variables and can be enabled (Yes), disabled (No), or controlled by a profile setting (Default).
  • For new variables, the auto-trim attribute will default to Yes.
  • All text variables created before this attribute was introduced in Contract Express 8.10 will have the value set to Default.
The default behavior is controlled by a profile setting, with the built-in profile value set to No. Auto-trim can be enabled for all text variables by changing the profile value to Yes.
Option to select Auto trim

Guidance Tab

Attribute: Guidance
Specifies the guidance text that appears on the questionnaire. This is edited in the same way as the question attribute except that it will appear below, rather than above, the variable's answer box, and in smaller text. As with the question, rich text formatting can be applied to guidance.
For example:
Guidance Editor
is displayed on the questionnaire as:
Images can be placed within the guidance by switching the editor to source mode. Click on the icon then enter the URL for the image using a HTML image tag (e.g. <img src="URL">).
Attribute: Preamble
Specifies the preamble text that appears on the questionnaire.
This is very similar to the guidance attribute except that it appears above the question on the questionnaire. As with the question and guidance boxes, rich text formatting can be applied to preamble text.

Constraints Tab

Attribute: Selection List Items
This attribute contains sub-attributes that determine whether the user can pick only a single choice or multi-values and also how they are presented on screen. See the Text selection variable options for more information specific to Text Selections.
Attribute: Template
This attribute is only pertinent for Entity variables.
The template selected will define the structure of the entity.
Attribute: Allow New
This attribute is only pertinent for Entity variables.
Controls whether new entities can be used when completing the questionnaire. If checked, Business Users will be able to add new entities. If un-checked, Business Users will only be able to add existing entities when completing this question.
Attribute: Filter
This attribute is only pertinent for Entity variables.
Attribute: Label
This attribute is only pertinent for Entity variables.
The text entered in the Label field will be displayed as a suffix for the Set/Change/Remove entity buttons in the questionnaire e.g. the Label field has the text “
Address
”. In the questionnaire this will be displayed as:
Set
Address
Change
Address
Remove
Address
Attribute: Width
This attribute is now deprecated.
Attribute: Height
This attribute is only pertinent for
Multiline Text
and
Text Selection
variables. The height determines how many rows of text the user will see on the questionnaire. An address variable may only need 4 or 5 lines but a description or comment field may require the user to see more text - say 10 or 15 lines.
Attribute: Minimum Value
This attribute is only pertinent for
Whole Number
,
Decimal Number
,
Date
and
Time
variables.
Minimum values are used to ensure the user enters a value that is at least the specified minimum, and are expressions which can be either:
(a) entered manually in the edit box, or
(b) clicking the corresponding
Edit...
button to the right of the edit box to invoke the
Expression Editor
.
The type of the minimum value expression must correspond to the type of the variable. So, for example,
Whole Number
variables must have a minimum value expression which evaluates to a whole number.
Attribute: Maximum Value
This attribute is only pertinent for
Whole Number
,
Decimal Number, Date
and
Time variables
.
Maximum values are used to ensure the user enters a value that is at most the specified maximum, and are expressions which can be either:
(a) entered manually in the edit box, or
(b) clicking the corresponding
Edit...
button to the right of the edit box to invoke the
Expression Editor
.
The type of the maximum value expression must correspond to the type of the variable. So, for example,
Whole Number
variables must have a maximum value expression which evaluates to a whole number.
Attribute: Default
Default values are values used to pre-fill the questionnaire on first use.
Default values are expressions which can be either:
(a) entered manually in the edit box, or
(b) clicking the corresponding
Edit...
button to the right of the edit box to invoke the
The type of the default value expression must correspond to the type of the variable. So, for example,
Date variables
must have a default value expression which evaluates to a date:
Attribute: Minimum Character Length
This attribute is only pertinent for
Text
and
Multiline Text
variables.
When specified it must be a positive whole number which represents the minimum number of characters that can be entered on the questionnaire.
Attribute: Maximum Character Length
This attribute is only pertinent for
Text
and
Multiline Text
variables.
When specified it must be a positive whole number which represents the maximum number of characters that must be entered on the questionnaire.
The text box on the questionnaire will stop the user entering more characters than the value specified for this attribute.
Attribute: Mask
This attribute is only pertinent for
Text
and
Multiline Text
variables.
There are two kinds of mask that can be specified:
(a) a pre-defined mask
(b) a regular expression that restricts characters in certain positions to be of a certain form
The pre-defined masks are:
telephone
the user must enter a valid telephone number
  1. Any sequence of
    digit
    (0-9) characters,
    minus
    (-) characters and
    space
    characters
  2. Optional leading
    plus
    (+) character
  3. Optional matching pair of
    open
    /
    close
    round
    brackets
emailaddress
the user must enter a valid email address
  1. Any sequence of characters that contains at least one
    at
    (@) character and at least one
    dot
    (.) character
webaddress
the user must enter a valid web address
  1. Any sequence of characters that contains at least one
    dot
    (.) character
searchaddress
Enables the UK postcode search feature within the questionnaire. A Postcode Search button will be displayed next to the text field in the questionnaire
.
Note this feature will only work when using either of the following options:
  1. en-GB is the base locale applied to the template
  2. If the locale code is manually added to the mask field as /en-GB in cases where the template uses a different base locale
searchcompany
Enables the companies house search feature. A button “Search Companies House” will be displayed next to the text field in the questionnaire.
Note this feature will only work when using one of the following options:
  1. en-GB as the base locale: this will only allow searching for companies registered in the UK
  2. nl-NL as the base locale: this will only allow searching for companies registered in the Netherlands
  3. If the locale code is manually added to the mask field as /en-GB or /nl-NL in cases where the template uses a different base locale
password
the edit box contains bullet characters for every character typed by the user.
Note the password is only masked in the questionnaire; in the Document History it is recorded in plain text.
Use the dropdown list to apply a pre-defined Mask. Otherwise type into the Mask edit box to customize the Mask using a regular expression.
The characters in a regular expression have the following meaning:
# a digit character in the range 0-9
a a lowercase letter character in the range a-z
A an uppercase letter character in the range A-Z
^ a letter character in the range a-z or A-Z
_ an optional space character
? any character
* any sequence of zero or more characters
Any other character in the mask must be matched verbatim. For example, to ensure the user enters a valid UK National Insurance number (of the form AB 12 34 56 Z), with or without space characters to separate the digits, the mask is:
^^_##_##_##_^
which represents:
letter, letter, optional space, digit, digit, optional space, digit, digit, optional space, digit, digit, optional space, letter
Attribute: Custom Repeat Labels
This attribute is only pertinent for Whole Number variables using a presentation style of Calculated from Repeat. It allows customisation of the text on the 3 repeat buttons, the defaults being 'Insert After', 'Insert Before' and 'Delete'.
Attribute: Tag for Yes
This attribute is only pertinent for Yes / No variables. It allows the user to specify a text label for the ‘true’ option, the default value being 'Yes'.
Attribute: Tag for No
This attribute is only pertinent for Yes / No variables. It allows the user to specify a text label for the ‘false’ option, the default value being 'No'.
Attribute: Distinct Repetitions
This attribute is only pertinent for selection list variables within repeat groups. It allows the user to ensure that each value from the selection list is used only once. If the same value is selected on another repeat, a compulsory warning will be raised. The display text of the warning can be customised using the text box below the Distinct Repetitions checkbox.
Distinct Repetitions
If no text is entered, the default warning text will be used.
In the questionnaire, the user will also see the links to the questionnaire answers that have been evaluated to trigger this warning.
Distinct Repetitions Warning

Document Tab

Attribute: Default Format
The default format attribute determines how, in the absence of any local formatting, variable values appear in a generated document. The default format is interpreted according to the type of the variable. Use the dropdown to choose from popular formats or type your own formatting. Clicking on the on the Preview Button next to the Default Format box will take you to the Format dialog.
Use the Format dialog to test how your formatting will look in the generated document. Use the dropdown at the top to choose formats or customize by typing in your own. The values on the left represent test values and the box on the right will show how those values will look if the formatting is applied. Use the Locale to see how this will affect the output.
See for more information on how to format variables according to their types.
Format Editor
Attribute: Default Case
The default case attribute determines, in the absence of any local case, the casing of variable values as they appear in a generated document. The options are:
  • Capitals:
    The first letter of the word will appear capitalized in the generated document.
  • Uppercase:
    All letters will appear in uppercase in the generated document.
  • Lowercase:
    All letters will appear in lowercase in the generated document.
  • Case-sensitive:
    All letters will appear as they are entered on the questionnaire in the generated document.
Attribute: Default Alternative Text
The default alternative text appears in a generated document if the variable's value is unknown.
It will also appear in active text when the variable's value is unknown.

Usage Tab

Attribute: Variable Usage
This is a read-only field which displays the relevancy of the variable in the current document. See Variable relevance for more details on this field.
Attribute: Author Note
The Author Note is for information purposes only. This attribute can be used to describe the role of the variable, or what it means in relation to other variables, or even how it maps onto some external data source. It can also be used to store a temporary note about a variable to remind you of tasks on that variable yet to be completed.
The description does not appear either on the questionnaire or in a generated document.

Computation Tab

Attribute: Computation
This attribute is used to define a Computable variable in terms of other variables. For example, to create a new variable which represents 3 months after the execution date:
Computables
Attribute: Save in Session
If you tick this check box then the value of the computed variable will be recorded in the answer set. It is only applicable to unrepeated variables. This is useful for exposing data to other systems, such as
HighQ iSheets
.