Conditional Instructions
A booking request should accept only dates of the season, a number of nights between 2 and 14 and an accommodation that suits the size of the group. Conditional instructions are the rules that do this in a TX Text Control form: each one tests the values of form fields and, depending on the result, enables or disables fields, sets values, replaces the items of a drop-down list or marks a value as invalid. The rules are stored in the document and run while users fill out the form in the Document Editor or the Document Viewer.
What follows explains the parts of a rule, the comparisons each form field type supports, how conditions combine and when instructions run, and then builds the rules of a complete booking form. Form fields themselves are described in Form Fields.
How Conditional Instructions Work
A conditional instruction has three parts:
- A name. It can't be empty and must be unique in the document.
- One or more conditions. Each condition compares the value of one form field with a comparison value, for example "the date of Arrival is on or after July 15".
- One or more instructions. Each instruction names a form field and what happens to it, for example "mark Arrival as valid". The field can be the one the conditions test or any other form field of the document.
When the conditions are fulfilled, every instruction is carried out. An instruction can also have an else value, which is applied when the conditions are not fulfilled. A rule is evaluated at two moments:
- When the document becomes a form. A form is a document in the
ReadAndSelectedit mode with read-only document permissions, as Let Users Fill Out the Form in the Document Editor describes. At that moment, all rules of the document are applied once. These are the initial instructions. - When the value of a form field changes that one of its conditions refers to. A check box changes when it is clicked. A date or selection form field changes when the user picks a date or an item, and a text, date or combo box field changes when the user has typed a new value and leaves the field. Typing alone, key by key, doesn't evaluate the rules.
In the class library, the four classes Condition, Instruction, ConditionalInstruction and ConditionalInstructionCollection describe these parts. The sections below give the name of each setting in the dialog box and in the class library, so that the rules in the Document Editor and the reference can be read side by side.
Where Conditional Instructions Run
| Component | What it does with conditional instructions |
|---|---|
| Document Editor | Users create, edit and remove them in the Form Validation group of the Form Fields tab. They are applied while form field validation is enabled and the document is a form. |
| Document Viewer | Applies the rules of a loaded form while users fill it out, as Form Fields in the Document Viewer describes. |
ServerTextControl | Loads and saves a document with its rules in the TX Text Control format, but can't read, add or apply them. |
In the Document Editor, your code turns form field validation on with setIsFormFieldValidationEnabled and reads the setting with getIsFormFieldValidationEnabled. Add the following script below the editor in Views/Home/Index.cshtml of the ASP.NET Core tutorial:
TXTextControl.addEventListener("documentLoaded", function () {
// Apply the conditional instructions of every loaded form
TXTextControl.setIsFormFieldValidationEnabled(true, function () {
TXTextControl.getIsFormFieldValidationEnabled(function (enabled) {
console.log("Form field validation: " + enabled);
});
});
});
On the Server
The class library documents FormFieldCollection.ConditionalInstructions, and with it Add, Remove, Clear, GetItem, GetItems, ConditionalInstructionNames and Count. All of them work only while form field validation is enabled, a property of the TextControl of the Windows Forms and WPF products. When validation is off, Count returns -1, ConditionalInstructionNames, GetItem and GetItems return null, and Add, Remove and Clear return false.
ServerTextControl has no property that enables validation, so its collection stays locked, also for a loaded document that contains rules: with version 34.0 of the Core engine, Count returns -1 and Add returns false. The code samples of the desktop products, which add rules with textControl1.FormFields.ConditionalInstructions.Add, don't apply to ServerTextControl. The class ServerVisualization.TextViewGenerator, which is derived from ServerTextControl, has an IsFormFieldValidationEnabled property, false by default, which the reference describes as deciding whether conditional instructions are applied when its EditMode is ReadAndSelect and its DocumentPermissions are read-only.
What the server does with forms that contain rules:
- Keep them. A form loaded and saved in the TX Text Control format (.tx) keeps its rules, so the server can merge data into a form template and pass it on to the Document Editor or the Document Viewer. Saved as DOCX, the form loses them.
- Check the values itself. Values that come back from the browser are checked by your server code, as Read and Check the Values of a Filled Form shows.
Create Rules in the Document Editor
The Form Validation group of the Form Fields tab has five buttons: Enable Form Validation, Highlight Invalid Values, Previous Invalid Value, Next Invalid Value and Manage Conditional Instructions.... The other buttons stay disabled until Enable Form Validation is on. The picture in Form Field Types of the Document Editor shows the group.
Open the form and click Enable Form Validation.
Click Manage Conditional Instructions.... The dialog box lists the rules of the document. Create a rule, or select one and click Edit... to change it.
The Conditional Instruction dialog box has three sections:
- Name: the unique name of the rule.
- Condition(s): in each row, the form field whose value is tested (a field without a name is listed under a generated unique name), the comparison operator and the comparison value. The ➕ button adds a row, and each row after the first is joined to the one before it with And or Or.
- Perform these actions: in each row, the form field to change, the instruction and its value. The ➕ button adds a row. The button to the left of it opens the Advanced Settings dialog box of the instruction.

Click OK. The rule is listed by its name.
Protect the document as a form, as Let Users Fill Out the Form describes, and save it in the TX Text Control format.
Before you protect the form, turn on Highlight Invalid Values, so that fields marked as invalid are highlighted. Previous Invalid Value and Next Invalid Value step through the invalid values of the form.
Conditions for Each Form Field Type
The operators and values a condition offers depend on the type of the form field it tests. In the class library, a Condition constructor exists for each type, and the operator is a value of Condition.ComparisonOperators.
| Form field | Tests | Operators in the dialog box | Comparison values |
|---|---|---|---|
Check box (CheckFormField) | Checked | Is, Is not | Checked, Unchecked |
Text box (TextFormField) | Text | Is, Is not, Contains, Starts with, Ends with, Does not contain, Does not start with, Does not end with, Is greater than, Is greater than or equal, Is less than, Is less than or equal, Matches regular expression, Does not match regular expression | A text, or Empty (no value set) |
Drop-down list or combo box (SelectionFormField) | Text | As for text boxes | A text, Empty (no value set), one of the items, or A list item |
Date (DateFormField) | Date | Is/Is in, Is not/Is not in, After, Is on or after, Before, Is on or before | A date, a year, a month, a day of the month, a weekday, or Empty (no value set) |
Empty (no value set) tests whether the field has no value: a text box or selection form field without text, or a date field without a date. It works with Is and Is not only, and not for check boxes. In code, the comparison value is null (or an empty string for text).
Check Boxes
A check box condition tests one of two states. In the class library, the constructor takes the check box and a bool: true stands for Is Checked, false for Is not Checked.

Text Boxes and Selection Form Fields
Text and selection form fields are compared by their text in three ways:
- Text comparison. Is and Is not compare the whole text, Contains and Does not contain look for a part of it, and the Starts with and Ends with operators test the beginning and the end.
- Greater and less. Is greater than, Is greater than or equal, Is less than and Is less than or equal compare numbers when both the text and the comparison value are numbers, decimal numbers included. Otherwise, they compare the strings in alphabetical order, case-sensitively. Numbers are read with the culture of the current thread (
Thread.CurrentThread.CurrentCulture): with English settings, "1.0" is the number 1, but with German settings, where the comma separates decimals, the period is ignored and "1.0" is 10. - Regular expressions. Matches regular expression and Does not match regular expression test the text against a pattern of the .NET regular expression engine. In the class library, this is the operator
IsorIsNotwith the flagRegexof Condition.TextComparisonFlags; the default flagCustomTextcompares plain text.

Items of Selection Form Fields
A selection form field can also be compared with its items, set with the flags of Condition.ItemComparisonFlags:
- One of the items (
SpecificItem) compares the text with the text of that item, with any operator except the two regular expression operators. Unlike a plain text comparison, the condition is fulfilled only while the field still has an item with this text, and in code, the constructor throws anArgumentExceptionwhen the value isn't one of the items. - A list item (
AnyItem) tests whether the text equals any of the items. It works with Is and Is not only, and the comparison value is ignored. With Is, the condition is fulfilled as soon as the user selects an item, and not fulfilled while the field is empty or shows typed text that isn't an item.


Date Form Fields
A date condition compares the date of the field with one of five kinds of values, which the constructor takes as different types:
| Value | Type in the class library | Operators |
|---|---|---|
| A date | DateTime | All six |
| A year from 1601 to 9999 | int | All six |
| A month | Condition.Month, such as Condition.Month.December | All six |
| A day of the month from 1 to 31 | int | All six |
| A weekday | System.DayOfWeek | Is, Is not |
In the class library, After and Is on or after are IsGreaterThan and IsGreaterThanOrEqual, and Before and Is on or before are IsLessThan and IsLessThanOrEqual. Condition.ComparisonValueType returns how a condition interprets its value, as a value of Condition.ComparisonValueTypes.

Combine Conditions With And and Or
Each condition after the first is joined to the one before it by a logical connective, set with Condition.LogicalConnective and the values And and Or of Condition.LogicalConnectives. The default is And, and the connective of the first condition is ignored. The conditions are tested in the order in which they appear in the rule.
And binds more strongly than Or. Conditions joined by And form a group that is fulfilled when all of its conditions are, and Or joins such groups:
C1 And C2 Or C3 means (C1 And C2) Or C3
C1 Or C2 And C3 means C1 Or (C2 And C3)

There are no parentheses. To test C1 And (C2 Or C3), repeat the shared condition in each group:
C1 And C2 Or C1 And C3 means (C1 And C2) Or (C1 And C3)
In the class library, the same Condition object may appear several times in the Conditions array of a rule. Give it the connective Or and put it first: the first occurrence ignores its connective, and every later one starts a new group.
Instruction Types
An instruction changes one form field. In the class library, its type is a value of Instruction.InstructionTypes, and the Instruction constructor takes the field, the type, the value and, optionally, the else value:
| In the dialog box | InstructionTypes | Value | Form fields |
|---|---|---|---|
| Allow editing, Deny editing | IsEnabled | bool, the new value of FormField.Enabled | All |
| Set value as valid, Set value as invalid | IsValueValid | bool, true for valid | All |
| Set new value | SetValue | bool for a check box (Checked or Unchecked), a string or an item for text and selection form fields, a DateTime for a date field; null or Empty (no value set) removes the value of all but check boxes | All |
| Set new items | SetItems | string[] that replaces the Items of the field; null or an empty array removes all items | Selection form fields |

In the dialog box, Specify items to set... next to Set new items opens the Edit Items dialog box, in which you enter the new items. An item can't be an empty string, and removing all items from the list creates an instruction that empties the drop-down list.

A rule can change several fields, and one field several times, but not twice with the same instruction type: the constructor of ConditionalInstruction and its Instructions property throw an ArgumentException for two instructions of the same type for the same form field.
Else Instructions
An else instruction sets a value when the conditions of the rule are not fulfilled. The dialog box and the class library differ here:
- The dialog box adds an else instruction with the opposite value to Allow editing, Deny editing, Set value as valid and Set value as invalid. A rule that marks a field as valid therefore marks it as invalid when its conditions are not met. Set new value and Set new items get no else instruction by themselves.
- The class library never adds one. The constructor with four parameters sets the else value and turns IsElseInstructionEnabled on; with three parameters, it's off.
In the Advanced Settings dialog box of an instruction, the check box In case the condition is not fulfilled, set the value to turns the else instruction on or off, and the value next to it sets it. ElseInstructionValue returns the else value. When none was set, it returns a default: the negation of the value for IsEnabled, IsValueValid and check boxes, an empty string for text and selection form fields, null for date fields and an empty array for SetItems.

Initial and Change Instructions
By default, an instruction runs at both moments: when the document becomes a form, and when a tested field changes. Two properties, both true by default, switch one of the moments off for a single instruction:
| Property | Check box in Advanced Settings | Set to false when |
|---|---|---|
| IsInitialInstruction | Is initial instruction | The instruction must not run when the form opens, for example because its conditions are fulfilled by the empty form. |
| IsFormFieldChangeInstruction | Perform instruction on form field value changes | The instruction must run only when the form opens and ignore what users enter. |
Invalid Values
An instruction of the type IsValueValid marks a form field value as valid or invalid; the value itself doesn't change. In the Document Editor, Highlight Invalid Values highlights the invalid values of a form, and Previous Invalid Value and Next Invalid Value step through them. The Document Viewer highlights required fields that aren't valid, and its forms.validate method returns false while required fields are missing, as Validate and Submit the Values shows.
Example: A Booking Request Form
The sample form travel-form.tx is installed with TX Text Control .NET Server in C:\Program Files\Text Control GmbH\TX Text Control 34.0.NET Server for ASP.NET\Samples\Demo. It has four form fields:
| Name | Type | Content |
|---|---|---|
| Arrival | Date form field | The date of arrival |
| Number of Nights | Text form field | The length of the stay |
| Number of Travelers | Selection form field, drop-down list | The items 1 to 8 |
| Desired Accommodation | Selection form field, drop-down list | The accommodation |

The form must behave as follows:
- Every field is required. A field without a value is invalid.
- Arrival is valid from July 15 to November 15, 2020.
- Number of Nights accepts whole numbers from 2 to 14.
- Desired Accommodation is disabled until a number of travelers is selected. It is invalid only while it is enabled and empty.
- Groups of 5 or more can choose Apartment Belle View and Ocean View Suite. Groups of up to 4 can also choose King's Life Suite and Tree House Room. If the group grows to 5 or more after one of these two was chosen, the choice is removed.
Seven rules implement this. Create each in the Conditional Instruction dialog box of the Document Editor; the lists give the settings of the dialog box, and the class library values in parentheses.
1. Validate Arrival
- Conditions: Arrival Is on or after 7/15/2020 (
IsGreaterThanOrEqual,new DateTime(2020, 7, 15)), And Arrival Is on or before 11/15/2020 (IsLessThanOrEqual). - Instruction: Arrival, Set value as valid (
IsValueValid,true), with the else instruction Set value as invalid (false) that the dialog box adds.
A missing date doesn't fulfill the conditions, so the else instruction marks it as invalid too.
2. Validate Number of Nights
This rule tests for invalid values instead of valid ones:
- Conditions: Number of Nights Is less than 2 (
IsLessThan,"2"), Or Is greater than 14 (IsGreaterThan,"14"), Or Does not match regular expression^\d+$(IsNotwithTextComparisonFlags.Regex). - Instruction: Number of Nights, Set value as invalid (
IsValueValid,false), with the else instruction Set value as valid (true).
The regular expression accepts only digits, so an empty field, a decimal number or text is invalid. All three conditions are joined by Or, so one of them is enough.

3. Validate Number of Travelers
- Condition: Number of Travelers Is Empty (no value set) (
Is,null). - Instruction: Number of Travelers, Set value as invalid (
false), with the else instruction Set value as valid (true).
A drop-down list shows only its items, so the field is valid as soon as the user selects one. The condition Number of Travelers Is A list item (Is, ItemComparisonFlags.AnyItem) with Set value as valid does the same from the other side.

4. Validate Desired Accommodation
Two fields take part, so the rule is evaluated when either of them changes:
- Conditions: Number of Travelers Is A list item (
Is,AnyItem), And Desired Accommodation Is Empty (no value set) (Is,null). - Instruction: Desired Accommodation, Set value as invalid (
false), with the else instruction Set value as valid (true).

5. Enable/Disable Desired Accommodation
- Condition: Number of Travelers Is Empty (no value set).
- Instruction: Desired Accommodation, Deny editing (
IsEnabled,false), with the else instruction Allow editing (true).

6. Update Desired Accommodation Items
- Condition: Number of Travelers Is greater than or equal the item 5 (
IsGreaterThanOrEqual,"5",ItemComparisonFlags.SpecificItem). The items are numbers, so they are compared as numbers. - Instruction: Desired Accommodation, Set new items (
SetItems) with Apartment Belle View and Ocean View Suite. In Advanced Settings, turn on the else instruction and set all four accommodations with Specify items to set....

In the class library, the instruction is:
Instruction setItems = new Instruction(desiredAccommodation, Instruction.InstructionTypes.SetItems,
new string[] { "Apartment Belle View", "Ocean View Suite" },
new string[] { "King's Life Suite", "Tree House Room", "Apartment Belle View", "Ocean View Suite" });
7. Reset Desired Accommodation
The choice is removed when the group has 5 or more travelers and the accommodation is King's Life Suite or Tree House Room. Because And binds more strongly than Or, the travelers condition is repeated in both groups:
- Conditions: Number of Travelers Is greater than or equal the item 5, And Desired Accommodation Is King's Life Suite, Or Number of Travelers Is greater than or equal the item 5, And Desired Accommodation Is Tree House Room.
- Instruction: Desired Accommodation, Set new value Empty (no value set) (
SetValue,null), without an else instruction.

Both accommodation conditions compare plain text, not an item: once rule 6 has replaced the items, King's Life Suite is no longer one of them, and a condition on that item would never be fulfilled. In the class library, the conditions are:
Condition fiveOrMore = new Condition(numberOfTravelers, Condition.ComparisonOperators.IsGreaterThanOrEqual,
"5", Condition.ItemComparisonFlags.SpecificItem)
{
LogicalConnective = Condition.LogicalConnectives.Or
};
Condition kingsLifeSuite = new Condition(desiredAccommodation, Condition.ComparisonOperators.Is, "King's Life Suite");
Condition treeHouseRoom = new Condition(desiredAccommodation, Condition.ComparisonOperators.Is, "Tree House Room");
Condition[] conditions = { fiveOrMore, kingsLifeSuite, fiveOrMore, treeHouseRoom };
fiveOrMore appears twice with the connective Or: at the first position, the connective is ignored, and at the third position, it starts the second group.
The Form in Use
When the form is protected, the initial instructions run. Arrival, Number of Nights and Number of Travelers are marked as invalid because they are empty. Desired Accommodation is disabled by rule 5, but not marked as invalid, because rule 4 requires a selected number of travelers.
As the user fills out the form, the rules follow each change. A date before July 15 keeps Arrival invalid, and "2.5" nights stays invalid because of the regular expression. Selecting 3 travelers enables Desired Accommodation and marks it as invalid until an accommodation is chosen. If the user then changes the number of travelers from 3 to 6 after choosing King's Life Suite, rule 7 empties Desired Accommodation, rule 4 marks it as invalid and rule 6 leaves only the two accommodations for larger groups.



More Condition Examples
| Goal | Conditions |
|---|---|
| Check box 1 is checked | cb1 Is Checked (new Condition(cb1, true)) |
| Both check boxes are unchecked | cb1 Is not Checked And cb2 Is not Checked |
| At least one check box is checked | cb1 Is Checked Or cb2 Is Checked |
| Check box 1, or both 2 and 3, are checked | cb1 Is Checked Or cb2 Is Checked And cb3 Is Checked |
| A text box isn't empty | Is not Empty (no value set) |
| The state Colorado | Is "Colorado" Or Is "CO" |
| A simple .com e-mail address | Contains "@" And Does not start with "@" And Ends with ".com" And Does not end with "@.com" |
| A positive number | Is greater than "0" |
| A number from 0 to 18 | Is greater than or equal "0" And Is less than or equal "18" |
| Text starting with a, b or c in either case | Is greater than or equal "a" And Is less than "d" Or Is greater than or equal "A" And Is less than "D" |
| 5 to 8 characters | Matches regular expression ^.{5,8}$ |
| No digits and no white space | Does not match regular expression [\s\d]+ |
| The item "Economy class basic" is selected | Is the item "Economy class basic" |
| A subcategory of the item "Economy class" | Is not the item "Economy class" And Contains the item "Economy class" |
| A clothing size from XL to XXXL | Is not the item "XS" And Is greater than or equal the item "XL" |
| The text of a combo box is one of its items | Is A list item |
| No date | Is Empty (no value set) |
| Any date but March 11, 2027 | Is not 3/11/2027 |
| Before March 11, 2027 | Before 3/11/2027 |
| From December 24, 2027 to January 1, 2028 | Is on or after 12/24/2027 And Is on or before 1/1/2028 |
| December 25 of any year | Is December And Is day 25 |
| The fourth Thursday of November | Is November And Is Thursday And Is on or after day 22 And Is on or before day 28 |
| The last Monday of May | Is Monday And Is May And Is on or after day 25 |
| A weekend | Is Saturday Or Is Sunday |
| A working day | Is not Saturday And Is not Sunday |
| Every Monday of 2027 | Is year 2027 And Is Monday |
| Every weekend of 2027 | Is year 2027 And Is Saturday Or Is year 2027 And Is Sunday |
The last week of a month starts on the 25th in months with 31 days, on the 24th in months with 30 days and on the 22nd in February, or the 23rd in a leap year. Comparisons of text are case-sensitive, which is why the a-to-c example needs a group for each case.
Regular expressions for common values, for Matches regular expression:
Credit card number ^((4\d{3})|(5[1-5]\d{2})|(6011))-?\d{4}-?\d{4}-?\d{4}|3[4,7]\d{13}$
E-mail address ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
US social security number ^\d{3}-\d{2}-\d{4}$
US telephone number ^[2-9]\d{2}-\d{3}-\d{4}$
US ZIP code ^(?!0{5})(\d{5})(?!-?0{4})(|-\d{4})?$
More Instruction Examples
- Reset a field. To disable a field, remove its value and clear an invalid mark when a condition is met, use three instructions for the field: Deny editing with its else instruction Allow editing; Set new value Empty (no value set); and Set value as valid with its else instruction turned off in Advanced Settings, because another rule decides when the field is invalid. Clear Is initial instruction for all three, as the reset isn't needed when the form opens. A check box can't be empty, so its reset value is Checked or Unchecked.
- Mark an empty combo box as invalid when the form opens. Choose a condition that the new form fulfills, such as the combo box Is Empty (no value set), and the instruction Set value as invalid with the else instruction turned off. Clear Perform instruction on form field value changes, so that another rule, which validates what the user enters, isn't overridden (
IsFormFieldChangeInstructionfalse). - Set a value from an item. Set new value can set a selection form field to one of its items, or to any text in a combo box.


Radio Button Groups
A radio button group, in which users select exactly one option, is built from check boxes that show radio button characters and start unchecked, as Conditional Instructions and Radio Button Groups shows. For each button, two rules create the group behavior:
| Rule | Condition | Instruction |
|---|---|---|
| Button 1 Checked | button 1 Is Checked | button 2 (and every other button), Set new value Unchecked |
| Button 1 Unchecked | button 1 Is not Checked | button 1, Set new value Checked, with Is initial instruction cleared |
The second rule keeps a selected option from being cleared. It must not be an initial instruction: when the form opens, all buttons are unchecked, and each of these rules would check its button, so the button handled last would appear selected.


Next Steps
- Form Fields: create forms, read their values and flatten them on the server.
- Form Fields in the Document Editor: design and protect forms in the browser.
- Form Fields in the Document Viewer: let users fill out and submit forms with their rules.
- Events of the Document Editor: the form field change events.