Creating and Applying Conditional Instructions

As mentioned, Conditional Instructions are applied to form fields. Therefore, a suitable form template is required. You can find this sample document (travel-form.tx) in the following directories:

  • C:\Program Files\Text Control GmbH\TX Text Control 28.0.NET for Windows Forms\Samples\Demo
  • C:\Program Files\Text Control GmbH\TX Text Control 28.0.NET for WPF\Samples\Demo
  • C:\Program Files\Text Control GmbH\TX Text Control 28.0.NET Server for ASP.NET\Samples\Demo

Image

This sample form template contains four fields to fill in a booking request. The user can choose the date of arrival (represented by a DateFormField with the name Arrival), the number of nights to stay (TextFormField Number of Nights), the number of travelers (SelectionFormField Number of Travelers) and the desired accommodation (SelectionFormField Desired Accommodation). In this context, the corresponding form fields should behave as follows:

  • All fields are required. If no value is set, the form field is marked as invalid (which can be shown by toggling the RibbonFormFieldsTab's Highlight Invalid Values button, when the document is write-protected).
  • Only dates from July 15 to November 15, 2020 are accepted as valid booking dates.
  • Only integers from 2 to 14 can be filled in at the form field that represents the number of nights.
  • The maximum number of travelers is limited to 8 persons. That limitation is given by the drop down list that contains the selectable items 1 - 8. As long as no item is selected, the Desired Accommodation form field has to be disabled.
  • The user has to choose an accommodation. Which accommodation can be booked depends on the number of travelers. If 5 or more people are selected, only Appartment Belle View and Ocean View Suite are provided by the drop down list. A group of up to 4 people can choose additionally between the King's Life Suite and the Tree House Room. Furthermore, the form field is marked as invalid only if it is not disabled and no accommodation is chosen.

This requested behavior can be implemented by creating 7 Conditional Instructions. The following describes step by step how these Conditional Instructions are created by using the dialog. In this context, the basic concept and remarks of the behavior of Conditional Instructions are explained in detail.

To create a Conditional Instruction by dialog the TextControl Conditional Instruction dialog has to be opened. In TX Text Control Words, the dialog can be opened by clicking the New… button of the Conditional Instructions sidebar. To invoke the dialog programmatically, the TextControl.ConditionalInstructionDialog method is provided.

That dialog consists of three sections:

  • Name: A Conditional Instruction needs a name. It has to be unique and cannot be an empty string.
  • Condition(s): At least one condition has to be defined for a Conditional Instruction. Such a condition needs a reference to a FormField that provides the value that should be compared. The comparison operator determines the equality or difference between the FormField value and the comparison value. Such comparison operators and values are type specific, which implies, that all possible operators, values and states depend on the type of the associated FormField. For example, while a condition for a CheckFormField (representing a check box) only supports the operators Is and Is not in combination with values Checked and Unchecked, a condition of textual form fields, such as TextFormField, provides in addition to Is and Is not the operators Matches regular expression, Does not match regular expression, 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 and Is less than or equal. Supported comparison values and states of a TextFormField are custom and empty text, where empty text can only be compared by using the Is and Is not operators.
  • Perform these actions: Besides a unique name and a list of conditions, a Conditional Instruction needs at least one instruction that has to be executed, if the defined condition is fulfilled. Like conditions, an instruction also requires a FormField reference. For all form field types, five kind of instructions can be executed: Allow editing, Deny editing, Set new value, Set value as valid and Set value as invalid. While Allow editing and Deny editing sets the common FormField.Enabled property to true or false, the Set new value instruction sets form field type specific values: A CheckFormField (as check box) can be checked or unchecked, a DateFormField can get a new date or reset to an empty value and the text of a TextFormField and a SelectionFormField (as combo box or drop down list) can be cleared or replaced with a custom string. Form fields that are marked by an instruction as invalid are highlighted inside the TextControl when activating the TXITEM_HighlightInvalidValues toggle button of the RibbonFormFieldsTab tab. To identify invalid form fields programmatically, the ConditionalInstructionCollection.IsValueValid can be used. In addition, an instruction for objects of type SelectionFormField can set a new list of items to the SelectionFormField.Items property and/or one of its items as new displayed text.

1. Validate Arrival

When creating a Conditional Instruction, it is necessary to determine a unique name, that reflects the desired action. In this sample, to specify a Conditional Instruction, that checks whether the displayed value of DateFormField Arrival represents a valid date, we choose the name Validate Arrival.

Next, the condition has to be set by selecting the form field that triggers the instruction. The corresponding form field is represented by its name. If no name is set, a form field is referenced by an automatically created unique string. Using the sample form template, the Arrival date field is selected by choosing the corresponding item inside the Value of form field combo box. Since this is a date form field, the items Is/Is in, Is not/Is not in, After, Is on or after, Before and Is on or before are now available as comparison operators. In this sample two conditions have to be determined. The first one specifies the beginning of the range of valid dates by setting the Is on or after in combination with the date 7/15/2020. The second one, that can be added by clicking the button, determines the end of that range. Its operator is set to Is on or before and the comparison value to 11/15/2020. Both conditions are connected by the And logical connective. That means, that both conditions have to be fulfilled to perform instructions. Besides comparing the DateFormField value with a specific date, it is posible to create conditions where the value is tested for a specific Year, Month, Day of the month or Weekday (Weekday only supports Is/Is in, Is not/Is not in operators).

Finally, at least one instruction has to be defined. As before, when creating the condition, the referenced form field has to be selected. In this sample, by choosing the Arrival item, the instruction references to the same form field that triggers the related conditions. To mark that form field as valid when the conditions are fulfilled, the Set value as valid item of the instruction drop down list is selected. By default, when using the dialog to create conditional instructions, automatically an else instruction is created for the instructions Allow editing, Deny editing, Set new value and Set value as valid. The set instruction value of such a created else instruction is always the opposite of the determined instruction value. This means, that when the conditions to perform an instruction that marks a form field as valid are not fulfilled, the else instuction sets the form field to invalid automatically. Applied to this sample, as soon as the Arrival date value is before July 15, 2020, after November 15, 2020, or simply not set, the form field is marked as not valid. Generally, else instructions can be enabled, disabled and modified by the instruction Advanced Settings dialog, that is provided when clicking the corresponding button to the left of the instruction's Add button ().

Now, the first Conditional Instruction is defined and should be represented by the Conditional Instruction dialog as follows:

Image

After accepting the created Conditional Instruction by clicking Ok, it is listed by its name inside the Conditional Instructions' sidebar panel. Selecting the corresponding item displays the conditions and instructions as human-readable full sentences inside the Conditions(s) and Perform these actions overviews.

To create such a Conditional Instruction programmatically, TX Text Control provides four classes:

  • The Condition class, that stores a prerequisite that must be fulfilled to perform at least one action.
  • The Instruction class to determine such an action.
  • The ConditionalInstruction class, where all related Condition and Instruction elements are jointed under a unique name.
  • The ConditionalInstructionCollection class, that contains all Conditional Instructions in a Text Control document or part of the document.

Condition objects have to be initialized with a FormField that is located inside the document. That FormField provides the value to be tested.

In this context, a comparison value has to be defined by the constructor's comparisonValue parameter. That value is compared with the FormField's value by using a specified comparisonOperator parameter. In this sample, two conditions are created that compare the DateFormField's Date property value with a specific date. To implement this programmatically, two Condition objects must be initialized. One, by setting the Condition.ComparisonOperators.IsGreaterThanOrEqual enumeration value as comparisonOperator parameter and using a System.DateTime object, that represents the date 7/15/2020, as comparison value. And another Condition, that uses the Condition.ComparisonOperators.IsLessThanOrEqual in combination with a System.DateTime object representing the date 11/15/2020. It should be noted that the logical connective of a Condition object is set to Condition.LogicalConnectives.And by default. To change that value, the Condition.LogicalConnective property must be used.

When creating an Instruction object, also a reference to a form field that is located inside the document must be set. That FormField is the object for which the desired actions are executed. The type of action is specified by the constructor's instructionType parameter. The corresponding value is set by the instructionValue parameter. When creating the sample's Set value as valid instruction programmatically, the Instruction.InstructionTypes.IsValueValid enumeration value must be set to the instructionType parameter. The instructionValue parameter gets the value true. In contrast to the dialog, when specifying an instruction by the API, else instructions are not created automatically for the types Instruction.InstructionTypes.IsEnabled and Instruction.InstructionTypes.IsValueValid. To create such an else instruction programmatically, the else instruction value must be set by the elseInstructionValue parameter of the constructor's second overload. In this sample, such an else instruction is desired and for this reason, to mark the form field as invalid, if the conditions are not fulfilled, the elseInstructionValue parameter is set to false.

Both Condition and Instruction objects have to be committed to a ConditionalInstruction object by an array. This can be done via the conditions and instructions parameters when intializing the object or by setting the corresponding properties ConditionalInstruction.Conditions and ConditionalInstruction.Instructions. When creating the conditions array, it is to be noted, especially when applying the logical connective Condition.LogicalConnectives.Or to a condition, that the order of the elements represent the order how the conditions are tested. Furthermore, it must be ensured, that the name assigned for this Conditional Instruction is not used by another one.

Finally, the created ConditionalInstruction object must be added to the Text Control by using ConditionalInstructionCollection.Add the method. An instance of this class can be obtained with the FormFieldCollection.ConditionalInstructions property. In this context it should be mentioned, that an instance of the ConditionalInstructionCollection cannot be modified, when the document is write-protected. This means, that a ConditionalInstruction object can only be added to the collection, if the TextControl.EditMode is set to EditMode.ReadAndSelect and TextControl.DocumentPermissions.ReadOnly to true.

As follows a code snippet is provided that shows how to create the Conditional Instruction Validate Arrival programmatically. The related DateFormField Arrival is represented by the variable m_dffArrival.

// Create conditions
Condition cdArrivalBegin = new Condition(m_dffArrival, Condition.ComparisonOperators.IsGreaterThanOrEqual, new DateTime(2020, 7, 15));
Condition cdArrivalEnd = new Condition(m_dffArrival, Condition.ComparisonOperators.IsLessThanOrEqual, new DateTime(2020, 11, 15));
Condition[] rcdConditions = new Condition[] { cdArrivalBegin, cdArrivalEnd };

// Create instruction
Instruction isSetAsValid = new Instruction(m_dffArrival, Instruction.InstructionTypes.IsValueValid, true, false);
Instruction[] risInstructions = new Instruction[] { isSetAsValid };

// Create conditional instruction
ConditionalInstruction ciValidateArrival = new ConditionalInstruction("Validate Arrival", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateArrival);
' Create conditions
Dim cdArrivalBegin As Condition = New Condition(m_dffArrival, Condition.ComparisonOperators.IsGreaterThanOrEqual, New DateTime(2020, 7, 15))
Dim cdArrivalEnd As Condition = New Condition(m_dffArrival, Condition.ComparisonOperators.IsLessThanOrEqual, New DateTime(2020, 11, 15))
Dim rcdConditions As Condition() = New Condition() { cdArrivalBegin, cdArrivalEnd }

' Create instructions
Dim isSetAsValid As Instruction = New Instruction(m_dffArrival, Instruction.InstructionTypes.IsValueValid, True, False)
Dim risInstructions As Instruction() = New Instruction() { isSetAsValid }

' Create conditional instruction
Dim ciValidateArrival As ConditionalInstruction = New ConditionalInstruction("Validate Arrival", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateArrival)

2. Validate Number of Nights

The next Conditional Instruction shows another approach to validate the value of a form field by creating conditions that tests for invalid values. If at least one of these conditions are fulfilled, the form field should be marked as invalid. Otherwise as valid. To validate the TextFormField Number of Nights text, three conditions that check for invalid values have to be created: The first one uses the Is less than operator to examine whether the set form field's text represents a number that less than the integer 2. The second condition applies the Is greater than operator to test for numbers that are greater than 14. The last condition uses the regular expression ^\d+$ to determine that only integers are allowed. By using the Does not match regular expression operator the condition is fulfilled, if the form field's text is empty or represents a string that is not an integer. To ensure that the instruction is executed, even if only one of the conditions is met, all conditions have to be connected by the Or logical connective.

The instruction references to the same form field, that is used to specify the conditions. The Set value as invalid drop down item is selected to mark the form field as invalid as soon as one of the related conditions are fulfilled. As mentioned earlier, the dialog creates for validating and enabling instruction automatically an else instruction. In this case the else instruction marks the form field as valid, if none of the conditions are met.

Image

When creating this Conditional Instruction programmatically, that Condition constructor overload must be used, which handles objects of type TextFormField. The first two conditions in this sample use the Condition.ComparisonOperators.IsLessThan and Condition.ComparisonOperators.IsGreaterThan operators to compare the TextFormField's Text property value. The third one uses the second TextFormField type specific overload. By using the Condition.TextComparisonFlags.Regex enumeration as textComparisonFlag parameter, the Condition is required to handle the specified comparison string as regular expression.

Furthermore, the logical connective value of the second and third Condition is changed to Condition.LogicalConnectives.Or. It is not necessary to change the corresponding value of the first Condition because the logical connective value only relates to the previous condition inside the corresponding ConditionalInstruction.Conditions array (which does not exists for the first Condition).

By setting the Instruction.InstructionTypes.IsValueValid enumeration value as instructionType parameter, the Instruction object uses the same instruction type as for the Conditional Instruction Validate Arrival mentioned before. The only difference is, that now the instructionValue is set to false and the elseInstructionValue to true. Accordingly, the form field is marked as invalid when the condition is fulfilled. Otherwise as valid.

As follows a code snippet is provided that shows how to create the Conditional Instruction Validate Number of Nights programmatically. The related TextFormField Number of Nights is represented by the variable m_tffNumberOfNights.

// Create conditions
Condition cdLessThan2Nights = new Condition(m_tffNumberOfNights, Condition.ComparisonOperators.IsLessThan, "2");
Condition cdMoreThan2Nights = new Condition(m_tffNumberOfNights, Condition.ComparisonOperators.IsGreaterThan, "14") { LogicalConnective = Condition.LogicalConnectives.Or };
Condition cdIsNotInteger = new Condition(m_tffNumberOfNights, Condition.ComparisonOperators.IsNot, "^\d+$", Condition.TextComparisonFlags.Regex) { LogicalConnective = Condition.LogicalConnectives.Or };
Condition[] rcdConditions = new Condition[] { cdLessThan2Nights, cdMoreThan2Nights, cdIsNotInteger };

// Create instructions
Instruction isSetAsInvalid = new Instruction(m_tffNumberOfNights, Instruction.InstructionTypes.IsValueValid, false, true);
Instruction[] risInstructions = new Instruction[] { isSetAsInvalid };

// Create conditional instruction
ConditionalInstruction ciValidateNumberOfNights = new ConditionalInstruction("Validate Number of Nights", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateNumberOfNights);
' Create conditions
Dim cdLessThan2Nights As Condition = New Condition(m_tffNumberOfNights, Condition.ComparisonOperators.IsLessThan, "2")
Dim cdMoreThan2Nights As Condition = New Condition(m_tffNumberOfNights, Condition.ComparisonOperators.IsGreaterThan, "14") With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim cdIsNotInteger As Condition = New Condition(m_tffNumberOfNights, Condition.ComparisonOperators.[IsNot], "^\d+$", Condition.TextComparisonFlags.Regex) With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim rcdConditions As Condition() = New Condition() { cdLessThan2Nights, cdMoreThan2Nights, cdIsNotInteger }

' Create instructions
Dim isSetAsInvalid As Instruction = New Instruction(m_tffNumberOfNights, Instruction.InstructionTypes.IsValueValid, False, True)
Dim risInstructions As Instruction() = New Instruction() { isSetAsInvalid }

' Create conditional instruction
Dim ciValidateNumberOfNights As ConditionalInstruction = New ConditionalInstruction("Validate Number of Nights", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateNumberOfNights)

3. Validate Number of Travelers

Beside testing a form field value for a specific value, other (form field type specific) comparison options are provided to determine a condition. One of these options, that is supported by all form field types except CheckFormField, is checking whether or not the corresponding form field displays a value. Such a condition can be created by selecting the dialog's Comparison value drop down item Empty (no value set) in combination with the Is and Is not Comparison operator. In this sample applying the Is operator and the Empty (no value set) comparison value to the SelectionFormField Number of Travelers creates a condition that marks the form field as invalid when no text is set. Due to the fact that a SelectionFormField is considered as a drop down field when its Editable property is set to false, no other value except one of its items can be set by the user as the text to display. From this it follows, that as soon as one of these items is selected, the displayed text is no longer empty and the form field is marked as valid by the else instruction.

Image

To create a Condition programmatically, that checks whether or not a FormField value is set, for each FormField type (except type of CheckFormField) an overload is provided, that accepts the comparison value null to test such a state. Using this parameter is only supported by the Condition.ComparisonOperators.Is and Condition.ComparisonOperators.IsNot operators.

As follows a code snippet is provided that shows how to create the Conditional Instruction Validate Number of Travelers programmatically by using the first SelectionFormField related constructor's overload with null as comparisonValue parameter value. The related SelectionFormField Number of Travelers is represented by the variable m_sffNumberOfTravelers.

// Create conditions
Condition cdIsEmpty = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.Is, null);
Condition[] rcdConditions = new Condition[] { cdIsEmpty };

// Create instructions
Instruction isSetAsInvalid = new Instruction(m_sffNumberOfTravelers, Instruction.InstructionTypes.IsValueValid, false, true);
Instruction[] risInstructions = new Instruction[] { isSetAsInvalid };

// Create conditional instruction
ConditionalInstruction ciValidateNumberOfTravelers = new ConditionalInstruction("Validate Number of Travelers", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateNumberOfTravelers);
' Create conditions
Dim cdIsEmpty As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.[Is], Nothing)
Dim rcdConditions As Condition() = New Condition() { cdIsEmpty }

' Create instructions
Dim isSetAsInvalid As Instruction = New Instruction(m_sffNumberOfTravelers, Instruction.InstructionTypes.IsValueValid, False, True)
Dim risInstructions As Instruction() = New Instruction() { isSetAsInvalid }

' Create conditional instruction
Dim ciValidateNumberOfTravelers As ConditionalInstruction = New ConditionalInstruction("Validate Number of Travelers", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateNumberOfTravelers)

For form fields of type SelectionFormField two more comparison options can be used to specify a condition. Both compare the displayed value with the SelectionFormField's drop down items. The first one applies the comparison operator (all operators are accepted, except the Matches regular expression and Does not match regular expression) to the string conversion of a specific item. When using the dialog such an item can be selected by the Comparison value drop down list. The other option is to check whether or not any of the items represent the current SelectionFormField's text. That kind of condition can be determined by the Is or Is not operator in combination with the Comparison value A list item. When creating a condition to validate the displayed Number of Travelers drop down list value, using A list item can be an alternative to the previous approach, where a condition handles the Empty (no value set) comparison value. Selecting this Comparison value item in combination with the Is operator always handles the condition as fulfilled, when a list item is selected and marks the form field as valid if the corresponding instruction is defined. For all other cases (including no displayed text) the form field is marked as invalid.

Image

To determine programmatically, that a Condition tests whether or not a SelectionFormField's list item is selected, the third SelectionFormField related constructor's overload must be used by setting the itemComparisonFlag to ComparisonValueTypes.AnyItem. Using this parameter is only supported by the Condition.ComparisonOperators.Is and Condition.ComparisonOperators.IsNot operators. The value of the comparisonValue parameter is ignored.

As follows a code snippet is provided that shows how to create the Conditional Instruction Validate Number of Travelers programmatically by using the third SelectionFormField related constructor's overload. The related SelectionFormField Number of Travelers is represented by the variable m_sffNumberOfTravelers.

// Create conditions
Condition cdIsAListItem = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.Is, null, Condition.ItemComparisonFlags.AnyItem);
Condition[] rcdConditions = new Condition[] { cdIsAListItem };

// Create instructions
Instruction isSetAsInvalid = new Instruction(m_sffNumberOfTravelers, Instruction.InstructionTypes.IsValueValid, true, false);
Instruction[] risInstructions = new Instruction[] { isSetAsInvalid };

// Create conditional instruction
ConditionalInstruction ciValidateNumberOfTravelers = new ConditionalInstruction("Validate Number of Travelers", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateNumberOfTravelers);
' Create conditions
Dim cdIsAListItem As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.[Is], Nothing, Condition.ItemComparisonFlags.AnyItem)
Dim rcdConditions As Condition() = New Condition() { cdIsAListItem }

' Create instructions
Dim isSetAsInvalid As Instruction = New Instruction(m_sffNumberOfTravelers, Instruction.InstructionTypes.IsValueValid, True, False)
Dim risInstructions As Instruction() = New Instruction() { isSetAsInvalid }

' Create conditional instruction
Dim ciValidateNumberOfTravelers As ConditionalInstruction = New ConditionalInstruction("Validate Number of Travelers", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateNumberOfTravelers)

4. Validate Desired Accommodation

In some cases, more than one form field has to be involved to fulfill the requirements for performing instructions. This means, that the Conditional Instruction is always handled, as soon as the value of any related conditions' form field is changed. In relation to this sample, it means that the conditions are tested if the value of the form fields Number of Travelers or Desired Accommodation changed. In these cases the Desired Accommodation form field is marked invalid if the number of travelers is set, but no accommodation selected. The corresponding conditions have to be created as follows:

Image

As follows a code snippet is provided that shows how to create the Conditional Instruction Validate Desired Accommodation programmatically. The related SelectionFormFields Number of Travelers and Desired Accommodation are represented by the variables m_sffNumberOfTravelers and m_sffDesiredAccommodation.

// Create conditions
Condition cdIsAListItem = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.Is, null, Condition.ItemComparisonFlags.AnyItem);
Condition cdIsEmpty = new Condition(m_sffDesiredAccommodation, Condition.ComparisonOperators.Is, null);
Condition[] rcdConditions = new Condition[] { cdIsAListItem, cdIsEmpty };

// Create instructions
Instruction isSetAsInvalid = new Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.IsValueValid, false, true);
Instruction[] risInstructions = new Instruction[] { isSetAsInvalid };

// Create conditional instruction
ConditionalInstruction ciValidateDesiredAccommodation = new ConditionalInstruction("Validate Desired Accommodation", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateDesiredAccommodation);
' Create conditions
Dim cdIsAListItem As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.[Is], Nothing, Condition.ItemComparisonFlags.AnyItem)
Dim cdIsEmpty As Condition = New Condition(m_sffDesiredAccommodation, Condition.ComparisonOperators.[Is], Nothing)
Dim rcdConditions As Condition() = New Condition() { cdIsAListItem, cdIsEmpty }

' Create instructions
Dim isSetAsInvalid As Instruction = New Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.IsValueValid, False, True)
Dim risInstructions As Instruction() = New Instruction() { isSetAsInvalid }

' Create conditional instruction
Dim ciValidateDesiredAccommodation As ConditionalInstruction = New ConditionalInstruction("Validate Desired Accommodation", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciValidateDesiredAccommodation)

5. Enable/Disable Desired Accommodation

As mentioned, up to 6 types of instructions can be executed. All previously described Conditional Instructions validated form fields by applying the Set value as invalid or Set value as valid instruction in combination with the corresponding else instruction. The other two instruction types, where the dialog creates an else instruction automatically, are represented by the Instruction drop-down items Allow editing and Deny editing. Instructions that use these types enable or disable the related form field by setting its Enabled property to true or false. In this sample a Conditional Instruction created where editing the Desired Accommodation form field is denied, if the number of travelers is not specified. Otherwise it is allowed.

Image

To create an Instruction object that sets the related FormField's Enabled property to true or false by code, the instructionType parameter must be set to Instruction.InstructionTypes.IsEnabled. The corresponding instructionValue parameter needs a value of type boolean. If it is set to true, the Instruction enables the form field. The value false disables the field.

As follows a code snippet is provided that shows how to create the Conditional Instruction Enable/Disable Desired Accommodation programmatically. The related SelectionFormFields Number of Travelers and Desired Accommodation are represented by the variables m_sffNumberOfTravelers and m_sffDesiredAccommodation.

// Create conditions
Condition cdIsEmpty = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.Is, null);
Condition[] rcdConditions = new Condition[] { cdIsEmpty };

// Create instructions
Instruction isDisableFormField = new Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.IsEnabled, false, true);
Instruction[] risInstructions = new Instruction[] { isDisableFormField };

// Create conditional instruction
ConditionalInstruction ciEnableDesiredAccommodation = new ConditionalInstruction("Enable/Disable Desired Accommodation", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciEnableDesiredAccommodation);
' Create conditions
Dim cdIsEmpty As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.[Is], Nothing)
Dim rcdConditions As Condition() = New Condition() {cdIsEmpty}

' Create instructions
Dim isDisableFormField As Instruction = New Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.IsEnabled, False, True)
Dim risInstructions As Instruction() = New Instruction() {isDisableFormField}

' Create conditional instruction
Dim ciEnableDesiredAccommodation As ConditionalInstruction = New ConditionalInstruction("Enable/Disable Desired Accommodation", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciEnableDesiredAccommodation)

6. Update Desired Accommodation Items

The dialog's Instruction drop down provides with the Set new items item a specific instruction type that can only be applied to form fields of type SelectionFormField. By using this instruction a specified list of items replaces the drop down items of the related SelectionFormField. When using the conditional instruction dialog, these items can be set by the Edit Items dialog, that appears on clicking the Specify items to set... button to the right of the selected Set new items item. Each of the specified items has to be a non empty string. To create an instruction, that clears the drop down menu, all listed items inside the Edit Items dialog have to be removed. To specify items for an else instruction, the Advanced Settings dialog must be opened, the corresponding check box checked and the Specify items to set... button clicked. Applied to this sample, a Conditional Instruction is created, where items of the SelectionFormField Desired Accommodation are replaced by a list of two accommodations, if the number of travelers is set to a value that is greater than 4. If this number is 4 or less, the list is expanded by two additional accommodations.

Image

Conditions that compare the set value with the string conversion of one of its items can be programmatically created by using the third SelectionFormField related constructor's overload. Setting the itemComparisonFlag to ComparisonValueTypes.SpecificItem informs the Condition to perform both the comparison itself and whether an item with the specified comparison value still exists.

An Instruction that updates the Items property of a SelectionFormField can be created by setting the Instruction.InstructionTypes.SetItems enumeration value as instructionType parameter. The corresponding instructionValue and elseInstructionValue parameters require a string array that represent the new items to set or null to remove all items.

As follows a code snippet is provided that shows how to create the Conditional Instruction Update Desired Accommodation Items programmatically. The related SelectionFormFields Number of Travelers and Desired Accommodation are represented by the variables m_sffNumberOfTravelers and m_sffDesiredAccommodation.

// Create conditions
Condition cdGreaterThan4 = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.IsGreaterThanOrEqual, "5", Condition.ItemComparisonFlags.SpecificItem);
Condition[] rcdConditions = new Condition[] { cdGreaterThan4 };

// Create instructions
Instruction isSetNewItems = new Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.SetItems,
    new string[] { "Appartment Belle View", "Ocean View Suite" },
    new string[] { "King's Life Suite", "Tree House Room", "Appartment Belle View", "Ocean View Suite" });
Instruction[] risInstructions = new Instruction[] { isSetNewItems };

// Create conditional instruction
ConditionalInstruction ciUpdateDesiredAccommodationItems = new ConditionalInstruction("Update Desired Accommodation Items", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciUpdateDesiredAccommodationItems);
' Create conditions
Dim cdGreaterThan4 As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.IsGreaterThanOrEqual, "5", Condition.ItemComparisonFlags.SpecificItem)
Dim rcdConditions As Condition() = New Condition() { cdGreaterThan4 }

' Create instructions
Dim isSetNewItems As Instruction = New Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.SetItems,
    New String() { "Appartment Belle View", "Ocean View Suite" },
    New String() { "King's Life Suite", "Tree House Room", "Appartment Belle View", "Ocean View Suite" })
Dim risInstructions As Instruction() = New Instruction() { isSetNewItems }

' Create conditional instruction
Dim ciUpdateDesiredAccommodationItems As ConditionalInstruction = New ConditionalInstruction("Update Desired Accommodation Items", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciUpdateDesiredAccommodationItems)

7. Reset Desired Accommodation

By default, groups of conditions that are connected with And logical connective are handled prioritized. This means, that a combination such as

Condition1 And Condition2 Or Condition3

follows the logical sequence

(Condition1 And Condition2) Or Condition3.

To determine a group of conditions that follows

Condition1 And (Condition2 Or Condition3)

the group must be specified as

(Condition1 And Condition2) Or (Condition1 And Condition3).

In this sample, such grouped conditions are determined to remove the displayed text from the SelectionFormField Desired Accommodation, if the number of travelers changed to a value that does not allow choosing the currently selected accommodation. Or described in more detail: As soon as the value of form field Number of Travelers is greater than or equals 5 And the current selected item of form field Desired Accommodation is (King's Life Suite Or Tree House Room), the text of form field Desired Accommodation is set to an emtpy string. The corresponding conditions and instructions are implemented inside the dialog as follows:

Image

Besides applying grouped conditions, this sample includes an instruction type that has not been mentioned in detail so far: Set new value. That instruction can be used, if it is necessary to change the displayed value of a form field. The kind of value to set depends on the type of the form field. A CheckFormField can be set to Checked or Unchecked. Objects of type TextFormField and SelectionFormField need a custom string or can be set to Empty (no value set), which clears the displayed text. A DateFormField supports a specific date or can also be reset by using the Empty (no value set) drop down item. In contrast to the types Allow editing, Deny editing, Set value as valid and Set value as invalid the dialog does not create automatically an else instruction. To do so, the Advanced Settings dialog must be opend, the corresponding check box be checked and a value be set.

When creating Condition or Instruction objects programmatically, they can be used more than once. This means that such an object can be referenced several times to or inside an array that is committed to a Conditional Instruction. In this sample the Condition that tests whether the SelectionFormField's value is greather than or equals to "5" (cdGreaterThan4) is created once, but used twice inside the array to commit.

Furthermore, the following code snippet shows how to to create an Instruction that sets a new value to display when the corresponding conditions are fulfilled. To do this, the constructor's instructionType parameter must be set to Instruction.InstructionTypes.SetValue and the instructionValue parameter to a value that has to be displayed. That instructionValue parameter can be set to null (except CheckFormField) to remove the content of the related form field or to an object of that type, that is required by the related form field. As for all instruction types, by using the second overload of the Instruction constructor, an else instruction value can also be defined for the instruction type Instruction.InstructionTypes.SetValue.

As follows a code snippet is provided that shows how to create the Conditional Instruction Reset Desired Accommodation programmatically. The related SelectionFormFields Number of Travelers and Desired Accommodation are represented by the variables m_sffNumberOfTravelers and m_sffDesiredAccommodation.

// Create conditions
Condition cdGreaterThan4 = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.IsGreaterThanOrEqual, "5", Condition.ItemComparisonFlags.SpecificItem) { LogicalConnective = Condition.LogicalConnectives.Or };
Condition cdKingsLifeSuite = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.Is, "King's Life Suite");
Condition cdTreeHouseRoom = new Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.Is, "Tree House Room");
Condition[] rcdConditions = new Condition[] { cdGreaterThan4, cdKingsLifeSuite, cdGreaterThan4, cdTreeHouseRoom };

// Create instructions
Instruction isClearValue = new Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.SetValue, null);
Instruction[] risInstructions = new Instruction[] { isClearValue };

// Create conditional instruction
ConditionalInstruction ciResetDesiredAccommodation = new ConditionalInstruction("Reset Desired Accommodation", rcdConditions, risInstructions);

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciResetDesiredAccommodation);
' Create conditions
Dim cdGreaterThan4 As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.IsGreaterThanOrEqual, "5", Condition.ItemComparisonFlags.SpecificItem) With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim cdKingsLifeSuite As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.[Is], "King's Life Suite")
Dim cdTreeHouseRoom As Condition = New Condition(m_sffNumberOfTravelers, Condition.ComparisonOperators.[Is], "Tree House Room")
Dim rcdConditions As Condition() = New Condition() {cdGreaterThan4, cdKingsLifeSuite, cdGreaterThan4, cdTreeHouseRoom}

' Create instructions
Dim isClearValue As Instruction = New Instruction(m_sffDesiredAccommodation, Instruction.InstructionTypes.SetValue, Nothing)
Dim risInstructions As Instruction() = New Instruction() {isClearValue}

' Create conditional instruction
Dim ciResetDesiredAccommodation As ConditionalInstruction = New ConditionalInstruction("Reset Desired Accommodation", rcdConditions, risInstructions)

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciResetDesiredAccommodation)

Applying Conditional Instructions

Now all required Conditional Instructions that are necessary to perform the desired behavior are defined. Before setting the form to write-protected, it is recommended, due to the fact that the document contains value validating Conditional Instructions, to enable highlighting those fields, that are marked as invalid. When using TX Text Control Words, toggling the Highlight Invalid Values button inside the RibbonFormFieldsTab highlights such invalid fields in yellow. On setting a form to write-protected, by default, all specified Conditional Instructions inside the document are automatically applied and executed, in case the corresponding conditions are fulfilled. Thus, the sample form template would look as follows:

Image

All form fields, except the SelectionFormField Desired Accommodation, are marked as invalid. The Arrival form field, because no date is set, that fulfills the Conditional Instructions Validate Arrival. Number of Nights because of Conditional Instructions Validate Number of Nights and Validate Number of Travelers marks form field Number of Travelers as invalid. Desired Accommodation is disabled, because the conditions of Conditional Instructions Enable/Disable Desired Accommodation are fulfilled. But it is not marked as invalid, because to fulfill the corresponding conditions of Enable/Disable Desired Accommodation, an item of the Number of Travelers SelectionFormField should be selected.

After the form is initialized, the user can complete the booking request. The following image shows some entries that were validated by the corresponding Conditional Instructions:

Image

The form fields Number of Travelers and Desired Accommodation are marked as valid, because all related Conditional Instructions are fulfilled. Arrival is marked as invalid, because the set date is before July 15, 2020. The value of the Number of Nights form field is accepted by all conditions except the regular expression that matches only strings that represent integers. Form field Desired Accommodation is changed to enabled because an item of SelectionFormField Number of Travelers is selected.

The next image shows what happend if the number of travelers changed from 3 to a number that is greater than 4:

Image

Since an accommodation (King's Life Suite) was selected that is not available for groups of 5 or more people, the Conditional Instruction Reset Desired Accommodation clears the Desired Accommodation SelectionFormField. The Conditional Instruction Validate Desired Accommodation marks it as invalid.

How the form looks like if it was completed with correct data, can be seen below:

Image

Advanced Instruction Settings

As mentioned before, by default, all specified Conditional Instructions inside the document are automatically applied when changing the document to write-protected. But in some cases it is required to command specific instructions not to be executed in this context. To do this, the Instruction.IsInitialInstruction property must be set to false. Furthermore, for some forms it could be necessary to create a Conditional Instruction that is handled during initializing, but ignores form field value changes due to user interaction. The corresponding property to determine that behavior is the Instruction.IsFormFieldChangeInstruction property. It has to be set to false as well.

The last option to manipulate the specific behavior of an instruction is to enable, disable and set a specific else instruction. When using the Conditional Instruction dialog automatically an else instruction is created for the instrutions Allow editing, Deny editing, Set new value and Set value as valid. These else instructions can be disabled by unchecking the corresponding check box inside the Advanced Settings dialog or setting the Instruction.IsElseInstructionEnabled property to false. The corresponding value can be changed by setting a new value inside the corresponding dialog's input mask. Furthermore, else instructions can also be specified for those instructions that are not created automatically. To do this, the corresponding else instuction check box must be checked and an instruction type specific value be set.

Image

When creating instruction programmatically, no else instruction is created automatically. To specify such an else instruction instruction, the second overload of the Instruction constructor must be used by setting the desired value to the elseInstructionValue parameter. When using this overload, the Instruction.IsElseInstructionEnabled property is automatically set to true.