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.
note
Escape character \
If you include a single quote as part of the variable Name, the Variable Editor will automatically add a backslash character to escape the quote: \'
Similarly, if the name includes a backslash, the variable editor will prefix this with a further backslash character \\
If you add fields into the template as you type, you must remember to escape quotes and backslashes where necessary.
note
Reserved words
There are a number of reserved words which variable names cannot contain such as AND and NOT.
Below is the full list for reference:
alt, and, answered, as, attach, attribute, authornote, by, capitals, cell, cloaked, collect, collectvalues, committed, datatype, deferred, definite, doctitle, document, else, every, exists, export, expressiontext, false, foreach, format, from, hyperlink, if, ifknownelse, include, is, isatleast, isatmost, islessthan, ismorethan, isnot, known, knowntrue, label, list, lower, mark, nonmutualand, nonmutualor, nonrepeated, not, note, now, occurrence, onlyoninput, onlyonoutput, onlyother, or, other, otherselections, picture, prefix, prescribedselections, proper, punctuation, ref, reference, relevance, repeat, repeatcontext, repeatcounter, select, selectionoptions, sensitive, simplify, spanrelevance, style, sure, template, templaterelevantce, textfile, then, to, today, true, unrepeated, upper, using, value, where, with, xor
Additionally, you cannot use the following symbols as the variable name (but they can be included as part of the variable name if quoted):
+ - * / // , ( ) # ? .
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 |
note
Even if your text selection contains a list of numbers,
Contract Express Author
will treat these as text options - you must refer to them with quotes in Business Rules. If you want to perform numeric calculations on text selection options then you will need to convert them to a number using the ToNumber function. 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:
Input Type | Description | Options Presented |
|---|---|---|
Radio Buttons | the user is presented with a pair of radio buttons representing Yes and No |  |
Check Box | the user is presented with a single checkbox representing Yes (checked) and No (un-checked) |  |
Presentation:
Date Variables
The presentation options are:
Input Type | Description | Options Presented |
|---|---|---|
Calendar | the user is presented with an edit box and a button which invokes a popup calendar |  |
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 |  |
Presentation:
Time Variables
The presentation options are:
Input Type | Description | Options Presented |
|---|---|---|
Clock | the user is presented with an edit box and a button which invokes a popup 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 components in the variable's default format |  |
Presentation:
Whole Number Variables
The presentation options are:
Input Type | Description | Options Presented |
|---|---|---|
Edit Box | the user is presented with an edit box in which the 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:
Input Type | Description | Options Presented |
|---|---|---|
Single Select Dropdown | the user is presented with a drop-down list from which one and only one option can be chosen |  |
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 |  |
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 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 Checkboxes | t he user is presented with a group of checkboxes of which none, one, many or all can be checked |  |
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. |  |
Presentation:
Multiline text variables
Input Type | Description | Options Presented |
|---|---|---|
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. |  |
note
By changing the Height attribute of a single dropdown variable you can create a scrollable single-choice list box, where the user can see more than one option at a time but only choose one. See Attribute:Height below
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.
note
In addition, the questionnaire can be configured so that it displays only those questions marked as compulsory. This can be achieved by creating a new profile and changing the setting
Display a subset of questions on the questionnaire.
Further, when testing questionnaires it is often desirable to turn off all compulsory questions, especially if it is a large questionnaire that contains many pages. This is accomplished by creating a new profile in Contract Express
and setting the Enforce compulsory questions
setting to No.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.
note
This is useful for offering a "quick draft" facility for a document with a very long questionnaire. Only those questions that have large structural influence on the document would be marked as key questions therefore getting the biggest impact with the least amount of questions.
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.
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:
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">).
then enter the URL for the image using a HTML image tag (e.g. <img src="URL">).note
Formatting and hyperlinks are added to the guidance text as HTML. For more on this see Advanced guidance
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.note
Contract Express
will not allow any questionnaire page to be submitted if it contains a (relevant) question whose value is less than the minimum value for that question: 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.note
Contract Express
will not allow any questionnaire page to be submitted if it contains a (relevant) question whose value is more than the maximum value for that question: 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 note
For
Text
and Multiline Text
, if the default value is a text literal then the text must be enclosed between double-quote characters. 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:note
For a date variable, you can use the Today function to default it to today's date. To do this just type Today in the default box. Alternatively, use an If-Then-Else statement to define the default value.
Note that you can use a question mark in this expression to leave the default value blank, if the condition does not evaluate to true. For example:
If
SameDateYN Then
Date1 Else
?note
If the variable is un-answered, either because the user removed the default value or because the user did not visit the questionnaire page that contained the question, then the default value is definitely
NOT
used when generating the document. This ensures that only values that have been submitted (and thus confirmed) by the user can appear in generated documents. 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.
note
Contract Express
will not allow any questionnaire page to be submitted if it contains a (relevant) question whose text box contains fewer than its required minimum number of characters. 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:
Pre-defined masks | Description |
|---|---|
telephone | the user must enter a valid telephone number
|
emailaddress | the user must enter a valid email address
|
webaddress | the user must enter a valid web address
|
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:
 |
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:
 |
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:
Characters | Description |
|---|---|
# | 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
note
Contract Express
will not allow any questionnaire page to be submitted if it contains a (relevant) question whose text box contents do not fully match the specified mask. 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.
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.
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.
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.
See Formatting for more information on how to format variables according to their types.
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.
note
You can override the default alternative text of a variable by including an ALT phrase in an expression field.
For example:
{NameBuyer ALT "the buyer"}
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:
note
Click the
Edit...
button to Use the expression editor to build your expression.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
.