Creating Conditional Instructions for Form Fields

Based on observing whether a form field value is changed, TX Text Control provides the concept of Conditional Instructions as an option to modify properties of specific form fields as soon as one or more conditions are fulfilled.

More precisely, a Conditional Instruction determines a list of states that associated form fields should have in order to fulfill a condition. If this condition was fulfilled by changing one of the related form field values, a defined list of instructions is executed. In this context, each of these instructions references a form field and a state that this form field should take. To enable Condition Instructions in a document, the TextControl.IsFormFieldValidationEnabled property must be set to true. When using the RibbonFormFieldsTab, the Enable Form Validation button (TXITEM_EnableFormValidation item) must be toggled to activate this feature.

The first chapter describes how to create such Conditional Instructions both programmatically and by using the built-in user interfaces. This is followed by samples and detailed explanations how to create form field type specific conditions and instructions.

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 31.0.NET for Windows Forms\Samples\Demo
  • C:\Program Files\Text Control GmbH\TX Text Control 31.0.NET for WPF\Samples\Demo
  • C:\Program Files\Text Control GmbH\TX Text Control 31.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.

How-to: Creating Conditions for Check Form Fields

A check form field can have two states: Checked and unchecked. Accordingly, the number of conditions that can be created for this form field type is limited to two. The first condition tests whether the check form field is checked. The other one whether it is not checked.

Some examples for applying check form field conditions are listed as follows:

Check form field is checked

To test whether or not a check form field is checked, a condition has to be created where the Isor Is not operator represents the desired checked state. On using the Is operator, the condition is fulfilled, if the CheckFormField.Checked property is set to true. CheckFormField conditions using the Is not operator require the value false.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdIsChecked = new Condition(m_cffCheckFormField1, true);
Condition[] rciConditions = new Condition[] { cdIsChecked };
' Create conditions
Dim cdIsChecked As Condition = New Condition(m_cffCheckFormField1, True)
Dim rciConditions As Condition() = New Condition() { cdIsChecked }

Both check form fields are unchecked

Sometimes it is necessary that more than one condition has to be fulfilled to perform an instruction. For these cases the conditions can be combined by the And logical connective. The following examples show that both checkFormField1 and checkFormField2 have to be unchecked to enforce an instruction.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsNotChecked1 = new Condition(m_cffCheckFormField1, false);
Condition cdIsNotChecked2 = new Condition(m_cffCheckFormField2, false);
Condition[] rcdConditions = new Condition[] { cdIsNotChecked1, cdIsNotChecked2 };
' Create conditions
Dim cdIsNotChecked1 As Condition = New Condition(m_cffCheckFormField1, False)
Dim cdIsNotChecked2 As Condition = New Condition(m_cffCheckFormField2, False)
Dim rcdConditions As Condition() = New Condition() { cdIsNotChecked1, cdIsNotChecked2 }

At least one check form field is checked

Combined conditions where at least one condition has to be fulfilled can be created by using the Or logical connective. The example below describes how to create a condition where either checkFormField1 or checkFormField2 has to be checked to perform an instruction.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsChecked1 = new Condition(m_cffCheckFormField1, true);
Condition cdIsChecked2 = new Condition(m_cffCheckFormField2, true) { LogicalConnective = Condition.LogicalConnectives.Or };
Condition[] rcdConditions = new Condition[] { cdIsChecked1, cdIsChecked2 };
' Create conditions
Dim cdIsChecked1 As Condition = New Condition(m_cffCheckFormField1, True)
Dim cdIsChecked2 As Condition = New Condition(m_cffCheckFormField2, True) With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim rcdConditions As Condition() = New Condition() { cdIsChecked1, cdIsChecked2 }

Check form field 1 is checked or both check form field 2 and 3 are checked

Another option to create combined conditions is using both the And and Or logical connective. As previously described, all conditions that are connected by the And logical connective are considered as one comprehensive condition. It is fulfilled if all its linked conditions are fulfilled. The Or logical connective handles such a condition as one condition. That means that either the group of And-linked conditions fulfill the condition or the condition that is Or-connected to that group.

The following example applies the And logical connective to test whether both checkFormField2 and checkFormField3 are checked. They are combined by an Or logical connective with checkFormField1. The condition is fulfilled if either checkFormField1 is checked, or both checkFormField2 and checkFormField3 are checked. If both checkFormField1 and one of the other two check form fields are not checked, the condition is unfulfilled.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsChecked1 = new Condition(m_cffCheckFormField1, true);
Condition cdIsChecked2 = new Condition(m_cffCheckFormField2, true) { LogicalConnective = Condition.LogicalConnectives.Or };
Condition cdIsChecked3 = new Condition(m_cffCheckFormField3, true);
Condition[] rcdConditions = new Condition[] { cdIsChecked1, cdIsChecked2, cdIsChecked3 };
' Create conditions
Dim cdIsChecked1 As Condition = New Condition(m_cffCheckFormField1, True)
Dim cdIsChecked2 As Condition = New Condition(m_cffCheckFormField2, True) With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim cdIsChecked3 As Condition = New Condition(m_cffCheckFormField3, True)
Dim rcdConditions As Condition() = New Condition() { cdIsChecked1, cdIsChecked2, cdIsChecked3 }

How-to: Creating Conditions for Text and Selection Form Fields

The value of both text and selection form fields are represented by the form field's Text property. Conditions for these kind of form fields can be divided into three categories:

The first one contains common string comparisons, where the text of the form field is tested for a specific string. Operators that can be used for this string comparison are Is, Is not, Contains, Starts with, Ends with, Does not contain, Does not start with and Does not end with.

Another option to define a condition is to compare the form field's text value with a specified comparison string value by using the operators Is greater than, Is greater than or equals, Is less than and Is less than or equals.

A more complex, but powerful way to create a string comparison condition is using regular expressions. That kind of condition checks whether the form field's text value matches or does not match a specified regular expression. In this context all regular expressions that are supported by the .NET Framework can be used.

Simple string comparison

A basic string comparison condition is checking whether the form field's text value (or parts of it) matches with a specific string. The Is and Is not operators check whether or not the form field's text equals to the specified string. The Contains and Does not contain operators can be used to test for a specific string sequence. Starts with, Does not start with, Ends with and Does not end with are provided to check whether the form field's text starts or ends (or does not start/end) with the specified string.

Some examples for applying such string comparisons are listed as follows:

Contains text

Many forms require that certain form fields have to be completed. To check whether or not a text or selection form field is filled in, the Is or Is not operator is used in combination with the corresponding Empty (no value set) flag.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdContainsText = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsNot, null);
Condition[] rcdConditions = new Condition[] { cdContainsText };
' Create conditions
Dim cdContainsText As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.[IsNot], Nothing)
Dim rcdConditions As Condition() = New Condition() { cdContainsText }

Is "Colorado" or "CO"

The following condition shows how to associate a specific value by matching different expressions. It identifies the state Colorado by its real name and the corresponding postal abbreviation. One condition checks whether the form field's text equals to the string "Colorado". Another one tests for the string "CO". Both conditions are connected by an OR logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsColorado = new Condition(m_tffTextFormField, Condition.ComparisonOperators.Is, "Colorado");
Condition cdIsCO = new Condition(m_tffTextFormField, Condition.ComparisonOperators.Is, "CO") { LogicalConnective = Condition.LogicalConnectives.Or };
Condition[] rcdConditions = new Condition[] { cdIsColorado, cdIsCO };
' Create conditions
Dim cdIsColorado As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.[Is], "Colorado")
Dim cdIsCO As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.[Is], "CO") With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim rcdConditions As Condition() = New Condition() { cdIsColorado, cdIsCO }

***@***.com

A simple e-mail validation condition for .com addresses can be constructed by checking whether the form field's text contains but not starts with the '@' character and ends with the string ".com" (but not with "@.com"). Four conditions have to be connected by an AND logical connective. The first condition uses the Contains operator to check whether the string contains the '@' character. The next condition ensures that the '@' is not the first character of form field's text (using the Does not start with operator). Condition three checks whether the text ends with ".com". And number four guarantees that a domain is defined for this address.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdContainsAt = new Condition(m_tffTextFormField, Condition.ComparisonOperators.Contains, "@");
Condition cdDoesNotStartWithAt = new Condition(m_tffTextFormField, Condition.ComparisonOperators.DoesNotStartWith, "@");
Condition cdEndsWithCOM = new Condition(m_tffTextFormField, Condition.ComparisonOperators.EndsWith, ".com");
Condition cdDoesNotEndWithAtCom = new Condition(m_tffTextFormField, Condition.ComparisonOperators.DoesNotEndWith, "@.com");
Condition[] rcdConditions = new Condition[] { cdContainsAt, cdDoesNotStartWithAt, cdEndsWithCOM, cdDoesNotEndWithAtCom };
' Create conditions
Dim cdContainsAt As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.Contains, "@")
Dim cdDoesNotStartWithAt As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.DoesNotStartWith, "@")
Dim cdEndsWithCOM As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.EndsWith, ".com")
Dim cdDoesNotEndWithAtCom As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.DoesNotEndWith, "@.com")
Dim rcdConditions As Condition() = New Condition() { cdContainsAt, cdDoesNotStartWithAt, cdEndsWithCOM, cdDoesNotEndWithAtCom }

As mentioned above, this condition is only a simple approach to validate an e-mail address. It won't recognize multiple '@' symbols or invalid characters. A more accurate approach is using a regular expression that identifies such e-mail addresses. How to create and use such a regular expression condition is defined in chapter Regular expression conditions.

String value comparison

In some cases it is necessary to compare the values that are represented by the form field text and comparison string. If both strings represent a number, a condition can check whether the number that is represented by the form field text is greater than, greater than or equals, less than or less than or equals the comparison value. Otherwise a string comparison is applied by the corresponding operators that checks the alphabetical order of the two strings.

Some examples for string value comparison are listed as follows:

Only positive numbers

To check whether the text represents a positive number, the Is greater than operator with the comparison value 0 or the Is greater than or equals operator with the comparison value 1 is used for the condition.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdGreaterThan0 = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThan, "0");
Condition[] rcdConditions = new Condition[] { cdGreaterThan0 };
' Create conditions
Dim cdGreaterThan0 As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThan, "0")
Dim rcdConditions As Condition() = New Condition() { cdGreaterThan0 }

As every condition that interprets the string values as numbers, decimal values are also accepted by this condition. In this context, it should be noted that the number format depends on the current System.Threading.Thread.CurrentThread.CurrentCulture value, which means, that the interpretation of a decimal separator can vary on different systems. For example: While on an English system the string "1.0" represents the number 1, a German system uses the character ',' to separate decimal numbers and ignores the '.' character ("1.0" would be interpreted as the number 10).

Numbers from 0 to 18

A range of numbers can be defined by creating two conditions that determine the start and the end of that range. The start condition can be defined by using the Is greater than or Is greater than or equals operator. The end of the range is determined by a condition that uses the Is less than or Is less than or equals operator.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdGreaterThanOrEqual0 = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, "0");
Condition cdLessThanOrEqual18 = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsLessThanOrEqual, "18");
Condition[] rcdConditions = new Condition[] { cdGreaterThanOrEqual0, cdLessThanOrEqual18 };
' Create conditions
Dim cdGreaterThanOrEqual0 As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, "0")
Dim cdLessThanOrEqual18 As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsLessThanOrEqual, "18")
Dim rcdConditions As Condition() = New Condition() { cdGreaterThanOrEqual0, cdLessThanOrEqual18 }

Strings beginning with the characters 'a', 'A', 'b', 'B', 'c' and 'C'

Besides using the Starts with operator to check whether a string starts with a specific character, the Is greater than, Is greater than or equals, Is less than and Is less than or equals operators can be used.

To identify a string beginning with specific characters, at least two conditions have to be specified. The first condition uses the Is greater than or equals operator to determine the first valid string of that range. The second condition uses the Is less than operator to specify the following character that follows the last valid string. Since the string comparison is case-sensitive, conditions must be created for both upper and lower case, if this is desired.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdFromFirstLowerCaseA = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, "a");
Condition cdToAllLowerCaseC = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsLessThan, "d");
Condition cdFromFirstUpperCaseA = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, "A") { LogicalConnective = Condition.LogicalConnectives.Or };
Condition cdToAllUpperCaseC = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsLessThan, "D");
Condition[] rcdConditions = new Condition[] { cdFromFirstLowerCaseA, cdToAllLowerCaseC, cdFromFirstUpperCaseA, cdToAllUpperCaseC };
' Create conditions
Dim cdFromFirstLowerCaseA As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, "a")
Dim cdToAllLowerCaseC As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsLessThan, "d")
Dim cdFromFirstUpperCaseA As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, "A") With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim cdToAllUpperCaseC As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.IsLessThan, "D")
Dim rcdConditions As Condition() = New Condition() { cdFromFirstLowerCaseA, cdToAllLowerCaseC, cdFromFirstUpperCaseA, cdToAllUpperCaseC }

Using regular expressions

A powerful approach to create conditions is using regular expression. Both simple conditions, such as checking for a certain number of characters, and more complex cases, such as the identification of an e-mail address, can be defined with a regular expression. To do so, a condition has to be created that uses the Match regular expression or Does not match regular expression operator in combination with a valid regular expression string.

Some examples for using regular expressions as conditions are listed as follows:

Text length is greater than 4 and less than 9

To define a condition that tests the form field's text length for a minimum and maximum length, the regular expression string "^.{min,max}$" can be used. The min placeholder represents the desired minimum length. The max placeholder the maximum length.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdMatchesLengthRange = new Condition(m_tffTextFormField, Condition.ComparisonOperators.Is, "^.{5,8}$", Condition.TextComparisonFlags.Regex);
Condition[] rcdConditions = new Condition[] { cdMatchesLengthRange };
' Create conditions
Dim cdMatchesLengthRange As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.[Is], "^.{5,8}$", Condition.TextComparisonFlags.Regex)
Dim rcdConditions As Condition() = New Condition() { cdMatchesLengthRange }

No digits and no white spaces

An option to create a condition that only accepts strings that do not contain digits or white spaces can be determined by setting the regular expression "[\s\d]+" in combination with the Does not match regular expression operator.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdNoDigitsNoWhiteSpace = new Condition(m_tffTextFormField, Condition.ComparisonOperators.IsNot, @"[\s\d]+", Condition.TextComparisonFlags.Regex);
Condition[] rcdConditions = new Condition[] { cdNoDigitsNoWhiteSpace };
' Create conditions
Dim cdNoDigitsNoWhiteSpace As Condition = New Condition(m_tffTextFormField, Condition.ComparisonOperators.[IsNot], "[\s\d]+", Condition.TextComparisonFlags.Regex)
Dim rcdConditions As Condition() = New Condition() {cdNoDigitsNoWhiteSpace}

Other useful regular expressions

Description 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}$
Mail address ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
SSN (social security number) ^\d{3}-\d{2}-\d{4}$
US telephone numbers ^[2-9]\d{2}-\d{3}-\d{4}$
US ZIP code ^(?!0{5})(\d{5})(?!-?0{4})(|-\d{4})?$

Specific selection form field conditions

The SelectionFormField class can be handled both as a combo box and a drop down list. Regarding to its item collection, the SelectionFormField class provides, in addition to the conditions listed above, two further options.

The first one is to create a condition, that compares the displayed text with the text of a specific item. The difference to a simple string comparison condition is, that the specified item must exist. If the SelectionFormField's Items property does not contain an item with the specified text, the condition is handled as unfulfilled, even if the text comparison succeeded.

The other option is to check whether any of the items are currently selected. Similar to checking for a specific item, the condition tests whether any string of the SelectionFormField items array equals to the displayed text.

Some examples for using item related conditions are listed as follows:

Equals to the text of item 'Economy class basic'

To test whether or not a specific item is selected, it has to be referenced by a condition in combination with an Is or Is not operator. This example shows how to create a condition that is fulfilled, if the item 'Economy class basic' is selected.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdIsEconomyClassBasicItem = new Condition(m_sffDropDownList, Condition.ComparisonOperators.Is, "   Economy class basic", Condition.ItemComparisonFlags.SpecificItem);
Condition[] rcdConditions = new Condition[] { cdIsEconomyClassBasicItem };
' Create conditions
Dim cdIsEconomyClassBasicItem As Condition = New Condition(m_sffDropDownList, Condition.ComparisonOperators.[Is], "   Economy class basic", Condition.ItemComparisonFlags.SpecificItem)
Dim rcdConditions As Condition() = New Condition() { cdIsEconomyClassBasicItem }

Get all 'Economy class' subcategories

In some cases, an item represents a main category, whose name appears in its subcategories. To observe these subcategory items, the Contains, Does not contain, Starts with, Does not start with, Ends with and Does not end with can be used to check whether the main category's name is part of the selected item. If the main category item should be ignored by this observation, an additional condition must be created to ensure that the corresponding item is not selected. Such a condition has to be connected by an And logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsNotEconomyClassItem = new Condition(m_sffDropDownList, Condition.ComparisonOperators.IsNot, "Economy class", Condition.ItemComparisonFlags.SpecificItem);
Condition cdContainsEconomyClassItem = new Condition(m_sffDropDownList, Condition.ComparisonOperators.Contains, "Economy class", Condition.ItemComparisonFlags.SpecificItem);
Condition[] rcdConditions = new Condition[] { cdIsNotEconomyClassItem, cdContainsEconomyClassItem };
' Create conditions
Dim cdIsNotEconomyClassItem As Condition = New Condition(m_sffDropDownList, Condition.ComparisonOperators.[IsNot], "Economy class", Condition.ItemComparisonFlags.SpecificItem)
Dim cdContainsEconomyClassItem As Condition = New Condition(m_sffDropDownList, Condition.ComparisonOperators.Contains, "Economy class", Condition.ItemComparisonFlags.SpecificItem)
Dim rcdConditions As Condition() = New Condition() { cdIsNotEconomyClassItem, cdContainsEconomyClassItem }

All sizes from XL to XXXL

Similar to a simple string comparison, it is possible to define a range condition by using the Is greater than, Is greater than or equals, Is less than or Is less than or equals operator. The Is greater than or Is greater than or equals operator can be used to determine the item that represents the lower threshold. The Is less than or Is less than or equals operator is used to set an upper threshold item.

The following examples shows how to check whether an item is selected that represents one of the XL clothing sizes. Due to the fact that there is no item that starts with a character whose integer value is greater than the value of 'X'., it is not necessary to define an upper threshold condition. However, another condition must be created that excludes the size XS. That condition is connected by an And logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsNotXS = new Condition(m_sffDropDownList, Condition.ComparisonOperators.IsNot, "XS", Condition.ItemComparisonFlags.SpecificItem);
Condition cdGreaterThanOrEqualXL = new Condition(m_sffDropDownList, Condition.ComparisonOperators.IsGreaterThanOrEqual, "XL", Condition.ItemComparisonFlags.SpecificItem);
Condition[] rcdConditions = new Condition[] { cdIsNotXS, cdGreaterThanOrEqualXL };
' Create conditions
Dim cdIsNotXS As Condition = New Condition(m_sffDropDownList, Condition.ComparisonOperators.[IsNot], "XS", Condition.ItemComparisonFlags.SpecificItem)
Dim cdGreaterThanOrEqualXL As Condition = New Condition(m_sffDropDownList, Condition.ComparisonOperators.IsGreaterThanOrEqual, "XL", Condition.ItemComparisonFlags.SpecificItem)
Dim rcdConditions As Condition() = New Condition() { cdIsNotXS, cdGreaterThanOrEqualXL }

Text matches a Pacific state item

To check whether or not the displayed text represents one of the SelectionFormField items, the Is or Is not operator can be used with the corresponding comparison flag A list item.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdIsListItem = new Condition(m_sffComboBox, Condition.ComparisonOperators.Is, null, Condition.ItemComparisonFlags.AnyItem);
Condition[] rcdConditions = new Condition[] { cdIsListItem };
' Create conditions
Dim cdIsListItem As Condition = New Condition(m_sffComboBox, Condition.ComparisonOperators.[Is], Nothing, Condition.ItemComparisonFlags.AnyItem)
Dim rcdConditions As Condition() = New Condition() { cdIsListItem }

How-to: Creating Conditions for Date Form Fields

Conditions based on the selected date of a date form field can be defined by a simple date comparison or in a more complex way, where recurring events compare the date with a range of days that are related to a specific year, month, week or weekday.

Date comparison

A date comparison condition compares the value of a date form field with a specific date. Besides using the basic comparison operators Is and Is not, the date form field value can be tested, if it is before or after the specified date.

Some examples for date comparisons are listed as follows:

Date form field is empty

There is no guarantee that a date field will always indicate a specific date. To test whether a date is not set, the Is operator is used in combination with the corresponding Empty (no value set)flag.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdIsEmpty = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, null);
Condition[] rcdConditions = new Condition[] { cdIsEmpty };
' Create conditions
Dim cdIsEmpty As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], Nothing)
Dim rcdConditions As Condition() = New Condition() { cdIsEmpty }

03/11/2020

The possibly most simple date field condition is to check whether the date form field represents a specific date. In case the Is operator is used in combination with the specified date.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdSpecificDate = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, new DateTime(2020, 03, 11));
Condition[] rcdConditions = new Condition[] { cdSpecificDate };
' Create conditions
Dim cdSpecificDate As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], New DateTime(2020, 03, 11))
Dim rcdConditions As Condition() = New Condition() { cdSpecificDate }

Except 03/11/2020

If all other dates, except a specified date, should fulfill the condition, the Is not operator has to be used.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdExceptSpecificDate = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsNot, new DateTime(2020, 03, 11));
Condition[] rcdConditions = new Condition[] { cdExceptSpecificDate };
' Create conditions
Dim cdExceptSpecificDate As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[IsNot], New DateTime(2020, 03, 11))
Dim rcdConditions As Condition() = New Condition() { cdExceptSpecificDate }

Before 03/11/2020

To define a condition looking for a date before the specified comparison date value, the Before operator is used.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdBeforeSpecificDate = new Condition(m_dffDateFormField,
Condition.ComparisonOperators.IsLessThan, new DateTime(2020, 03, 11));
Condition[] rcdConditions = new Condition[] { cdBeforeSpecificDate };
' Create conditions
Dim cdBeforeSpecificDate As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.IsLessThan, New DateTime(2020, 03, 11))
Dim rcdConditions As Condition() = New Condition() { cdBeforeSpecificDate }

From 12/24/2020 to 01/01/2021

A range of dates can be defined by creating two conditions. One condition defines the beginning of the date range by using the After or Is on or after operator. The other condition determines the end of the range. For this condition, the Before or Is on or before operator is used. Both conditions are connected by the And logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdFromDate = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, new DateTime(2020, 12, 24));
Condition cdToDate = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsLessThanOrEqual, new DateTime(2020, 01, 01));
Condition[] rcdConditions = new Condition[] { cdFromDate, cdToDate };
' Create conditions
Dim cdFromDate As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, New DateTime(2020, 12, 24))
Dim cdToDate As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.IsLessThanOrEqual, New DateTime(2020, 01, 01))
Dim rcdConditions As Condition() = New Condition() { cdFromDate, cdToDate }

Recurring events

Sometimes it is necessary to create conditions that consider recurring events. Such events could be specific dates in a year, such as birthdays, or not date specific events, where the date of the event is related to a specific year, month, week or weekday.

Some examples for recurring events are listed as follows:

December 25

A specific day of a specific month needs two conditions: A condition to determine a month and a condition to determine the day of the month. Both conditions have to be connected by an And logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsDecember = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, Condition.Month.December);
Condition cdIs25th = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, 25);
Condition[] rcdConditions = new Condition[] { cdIsDecember, cdIs25th };
' Create conditions
Dim cdIsDecember As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], Condition.Month.December)
Dim cdIs25th As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], 25)
Dim rcdConditions As Condition() = New Condition() { cdIsDecember, cdIs25th }

The 4th Thursday in November

To determine a specific weekday in a specific week of a specific month, four conditions have to be created that are joined by an And logical connective.

First, we have to create a condition that checks whether the date of the form field is in the specified month:

Image

The next condition determines that the date has to be on the requested weekday:

Image

The third and fourth one specifies the range of days of the month on which the weekday can be. To determine a weekday in the first week, the range has to be between the 1st and 7th day of the month. For the second week it has to be between the 8th and 14th, the third week is between the 15th and 21st and the fourth between the 22nd and 28th day of the month:

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsNovember = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, Condition.Month.November);
Condition cdIsThursday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Thursday);
Condition cdIsOnOrAfter22nd = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, 22);
Condition cdIsOnOrBefore28th = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsLessThanOrEqual, 28);
Condition[] rcdConditions = new Condition[] { cdIsNovember, cdIsThursday, cdIsOnOrAfter22nd, cdIsOnOrBefore28th };
' Create conditions
Dim cdIsNovember As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], Condition.Month.November)
Dim cdIsThursday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Thursday)
Dim cdIsOnOrAfter22nd As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, 22)
Dim cdIsOnOrBefore28th As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.IsLessThanOrEqual, 28)
Dim rcdConditions As Condition() = New Condition() { cdIsNovember, cdIsThursday, cdIsOnOrAfter22nd, cdIsOnOrBefore28th }

Last Monday in May

The range of days to determine the last specific weekday of a month depends on the day number of the specified month. For those months that have 31 days, the range starts with the 25th day. Potential days for the last week of months with 30 days begin at the 24th of the month. The range of February starts at the 22nd (or 23rd, if February has 29 days) day of the month.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsMonday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Monday);
Condition cdIsMay = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, Condition.Month.May);
Condition cdIsOnOrAfter25th = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, 25);
Condition[] rcdConditions = new Condition[] { cdIsMonday, cdIsMay, cdIsOnOrAfter25th };
' Create conditions
Dim cdIsMonday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Monday)
Dim cdIsMay As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], Condition.Month.May)
Dim cdIsOnOrAfter25th As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.IsGreaterThanOrEqual, 25)
Dim rcdConditions As Condition() = New Condition() { cdIsMonday, cdIsMay, cdIsOnOrAfter25th }

Weekend

To define the weekend, the date form field value has to be on a Saturday or a Sunday.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsSaturday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Saturday);
Condition cdIsSunday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Sunday) { LogicalConnective = Condition.LogicalConnectives.Or };
Condition[] rcdConditions = new Condition[] { cdIsSaturday, cdIsSunday };
' Create conditions
Dim cdIsSaturday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Saturday)
Dim cdIsSunday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Sunday) With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim rcdConditions As Condition() = New Condition() { cdIsSaturday, cdIsSunday }

Weekday

Checking for weekdays can be defined in the same way as checking for dates on a weekend (using Monday, Tuesday, Wednesday, Thursday and Friday, except Saturday and Sunday). A more smart approach is determining all days except Saturday and Sunday by using the Is not operator and connecting both connections by the And logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIsNotSaturday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsNot, System.DayOfWeek.Saturday);
Condition cdIsNotSunday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.IsNot, System.DayOfWeek.Sunday);
Condition[] rcdConditions = new Condition[] { cdIsNotSaturday, cdIsNotSunday };
' Create conditions
Dim cdIsNotSaturday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[IsNot], DayOfWeek.Saturday)
Dim cdIsNotSunday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[IsNot], DayOfWeek.Sunday)
Dim rcdConditions As Condition() = New Condition() { cdIsNotSaturday, cdIsNotSunday }

Each Monday in 2020

To define an event for a specific weekday in a specific year, an Is condition for the year and an Is condition for the weekday has to be defined. Both conditions are joined by an And logical connective.

Image

To create these conditions programmatically, use the following code snippet:

// Create conditions
Condition cdIs2020 = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, 2020);
Condition cdIsMonday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Monday);
Condition[] rcdConditions = new Condition[] { cdIs2020, cdIsMonday };
' Create conditions
Dim cdIs2020 As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], 2020)
Dim cdIsMonday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Monday)
Dim rcdConditions As Condition() = New Condition() {cdIs2020, cdIsMonday}

Each weekend in 2020

To check for weekends in a specific year, a combination of two separate weekdays in a year condition has to be created and connected by the Or logical connective. The first part checks whether the date form field value represents a date on a Saturday in 2020 and the second one tests for a Sunday in 2020.

Image

To create this condition programmatically, use the following code snippet:

// Create conditions
Condition cdIs2020 = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, 2020) { LogicalConnective = Condition.LogicalConnectives.Or };
Condition cdIsSaturday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Saturday);
Condition cdIsSunday = new Condition(m_dffDateFormField, Condition.ComparisonOperators.Is, System.DayOfWeek.Sunday);
Condition[] rcdConditions = new Condition[] { cdIs2020, cdIsSaturday, cdIs2020, cdIsSunday };
' Create conditions
Dim cdIs2020 As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], 2020) With {
    .LogicalConnective = Condition.LogicalConnectives.[Or]
}
Dim cdIsSaturday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Saturday)
Dim cdIsSunday As Condition = New Condition(m_dffDateFormField, Condition.ComparisonOperators.[Is], DayOfWeek.Sunday)
Dim rcdConditions As Condition() = New Condition() {cdIs2020, cdIsSaturday, cdIs2020, cdIsSunday}

How-to: Creating Instructions

Five types of instructions can be specified for a FormField>: 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. Set value as valid> and Set value as invalid> instructions can be used for form field validation. An object of type SelectionFormField additionally supports instructions of type Set new items> where the SelectionFormField.Items property value is replaced by another string array.

Enable/Disable form fields

For all types of form fields, instructions can be created that enable or disable the option to edit a FormField when the corresponding conditions are fulfilled. To do this by dialog the Instruction drop down provides the Allow editing item to enable changing the form field's value by user interaction. Deny editing disables it. For both instruction types the dialog creates automatically an else instruction, that represents the opposite of the defined type. The else instruction 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 (➕).

Image

To create these instructions programmatically, use one of the following code snippets.

Instructions without else instructions:

// Create instructions
Instruction isDenyEditing = new Instruction(m_dffDateFormField, Instruction.InstructionTypes.IsEnabled, false);
Instruction isAllowEditing = new Instruction(m_cffCheckFormField, Instruction.InstructionTypes.IsEnabled, true);
Instruction[] risInstructions = new Instruction[] { isDenyEditing, isAllowEditing };
' Create instructions
Dim isDenyEditing As Instruction = New Instruction(m_dffDateFormField, Instruction.InstructionTypes.IsEnabled, False)
Dim isAllowEditing As Instruction = New Instruction(m_cffCheckFormField, Instruction.InstructionTypes.IsEnabled, True)
Dim risInstructions As Instruction() = New Instruction() { isDenyEditing, isAllowEditing }

Instructions that include else instructions:

// Create instructions
Instruction isDenyEditing = new Instruction(m_dffDateFormField, Instruction.InstructionTypes.IsEnabled, false, true);
Instruction isAllowEditing = new Instruction(m_cffCheckFormField, Instruction.InstructionTypes.IsEnabled, true, false);
Instruction[] risInstructions = new Instruction[] { isDenyEditing, isAllowEditing };
' Create instructions
Dim isDenyEditing As Instruction = New Instruction(m_dffDateFormField, Instruction.InstructionTypes.IsEnabled, False, True)
Dim isAllowEditing As Instruction = New Instruction(m_cffCheckFormField, Instruction.InstructionTypes.IsEnabled, True, False)
Dim risInstructions As Instruction() = New Instruction() { isDenyEditing, isAllowEditing }

Mark form fields as valid/invalid

In some cases it is useful to inform the user that the displayed value of a form field is not valid. Such behavior can be implemented by applying an instruction that marks the related form field as valid or invalid. By using the dialog, the Instruction drop down list item Set value as invalid must be set to mark a form field as invalid, in case the corresponding conditions are fulfilled. The Set value as valid item marks the form field as valid. Similar to selecting the Allow editing or Deny editingitem, the dialog creates automatically an else instruction, which can also be modified by the Advanced Settings dialog.

To highlight form fields that are marked as invalid inside an application that uses the RibbonFormFieldsTab, the Highlight Invalid Values button must be toggled. To validate a form field programmatically, the ConditionalInstructionCollection.IsValueValid method can be used.

Image

To create these instructions programmatically, use one of the following code snippets.

Instructions without else instructions:

// Create instructions
Instruction isSetValueAsInvalid = new Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsValueValid, false);
Instruction isSetValueAsValid = new Instruction(m_sffDropDownList, Instruction.InstructionTypes.IsValueValid, true);
Instruction[] risInstructions = new Instruction[] { isSetValueAsInvalid, isSetValueAsValid };
' Create instructions
Dim isSetValueAsInvalid As Instruction = New Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsValueValid, False)
Dim isSetValueAsValid As Instruction = New Instruction(m_sffDropDownList, Instruction.InstructionTypes.IsValueValid, True)
Dim risInstructions As Instruction() = New Instruction() {isSetValueAsInvalid, isSetValueAsValid}

Instructions that include else instructions:

// Create instructions
Instruction isSetValueAsInvalid = new Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsValueValid, false, true);
Instruction isSetValueAsValid = new Instruction(m_sffDropDownList, Instruction.InstructionTypes.IsValueValid, true, false)
Instruction[] risInstructions = new Instruction[] { isSetValueAsInvalid, isSetValueAsValid };
' Create instructions
Dim isSetValueAsInvalid As Instruction = New Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsValueValid, False, True)
Dim isSetValueAsValid As Instruction = New Instruction(m_sffDropDownList, Instruction.InstructionTypes.IsValueValid, True, False)
Dim risInstructions As Instruction() = New Instruction() { isSetValueAsInvalid, isSetValueAsValid }

Check/Uncheck check box

To determine a new check state of an object of type CheckFormField, the Instruction drop down's Set new value item must be selected. The desired new value must be specified by choosing either the Checked or Unchecked item. An else instruction can be set by using the Advanced Settings dialog.

Image

To create these instructions programmatically, use one of the following code snippets.

Instructions without else instructions:

// Create instructions
Instruction isSetChecked = new Instruction(m_cffCheckFormField1, Instruction.InstructionTypes.SetValue, false);
Instruction isSetUnchecked = new Instruction(m_cffCheckFormField2, Instruction.InstructionTypes.SetValue, true);
Instruction[] risInstructions = new Instruction[] { isSetChecked, isSetUnchecked };
' Create instructions
Dim isSetChecked As Instruction = New Instruction(m_cffCheckFormField1, Instruction.InstructionTypes.SetValue, False)
Dim isSetUnchecked As Instruction = New Instruction(m_cffCheckFormField2, Instruction.InstructionTypes.SetValue, True)
Dim risInstructions As Instruction() = New Instruction() { isSetChecked, isSetUnchecked }

Instructions that include else instructions:

// Create instructions
Instruction isSetChecked = new Instruction(m_cffCheckFormField1, Instruction.InstructionTypes.SetValue, false, true);
Instruction isSetUnchecked = new Instruction(m_cffCheckFormField2, Instruction.InstructionTypes.SetValue, true, false);
Instruction[] risInstructions = new Instruction[] { isSetChecked, isSetUnchecked };
' Create instructions
Dim isSetChecked As Instruction = New Instruction(m_cffCheckFormField1, Instruction.InstructionTypes.SetValue, False, True)
Dim isSetUnchecked As Instruction = New Instruction(m_cffCheckFormField2, Instruction.InstructionTypes.SetValue, True, False)
Dim risInstructions As Instruction() = New Instruction() { isSetChecked, isSetUnchecked }

Change text form field text

The displayed value of a TextFormField can be modified by an instruction by using the Instruction drop down's Set new value item in combination with the desired string. To clear the text of the corresponding field, the Empty (no value set) flag must be selected.

Image

To create these instructions programmatically, use one of the following code snippets.

Instructions without else instructions:

// Create instructions
Instruction isSetNewText = new Instruction(m_tffTextFormField1, Instruction.InstructionTypes.SetValue, "TX Text Control");
Instruction isClearText = new Instruction(m_tffTextFormField2, Instruction.InstructionTypes.SetValue, null);
Instruction[] risInstructions = new Instruction[] { isSetNewText, isClearText };
' Create instructions
Dim isSetNewText As Instruction = New Instruction(m_tffTextFormField1, Instruction.InstructionTypes.SetValue, "TX Text Control")
Dim isClearText As Instruction = New Instruction(m_tffTextFormField2, Instruction.InstructionTypes.SetValue, Nothing)
Dim risInstructions As Instruction() = New Instruction() { isSetNewText, isClearText }

Instructions that include else instructions:

// Create instructions
Instruction isSetNewText = new Instruction(m_tffTextFormField1, Instruction.InstructionTypes.SetValue, "TX Text Control", "TX Spell");
Instruction isClearText = new Instruction(m_tffTextFormField2, Instruction.InstructionTypes.SetValue, null, "TX Text Control");
Instruction[] risInstructions = new Instruction[] { isSetNewText, isClearText };
' Create instructions
Dim isSetNewText As Instruction = New Instruction(m_tffTextFormField1, Instruction.InstructionTypes.SetValue, "TX Text Control", "TX Spell")
Dim isClearText As Instruction = New Instruction(m_tffTextFormField2, Instruction.InstructionTypes.SetValue, Nothing, "TX Text Control")
Dim risInstructions As Instruction() = New Instruction() { isSetNewText, isClearText }

Set new drop down list value

An Object of type SelectionFormField can be handled as drop down list (SelectionFormField.Editable value is set to false) or combo box. For both implementations an instruction can be created that sets a new string to display or removes the currently shown text. Similar to creating instructions for objects of type TextFormField, the Set new value item must be combined with a specific string or with the Empty (no value set) item. If the SelectionFormField.Items property is not empty, the elements of that array are provided to be chosen by the corresponding value drop down.

Image

To create these instructions programmatically, use one of the following code snippets.

Instructions without else instructions:

// Create instructions
Instruction isClearText = new Instruction(m_sffComboBox, Instruction.InstructionTypes.SetValue, null);
Instruction isSetNewText = new Instruction(m_sffDropDownList1, Instruction.InstructionTypes.SetValue, "Product Number");
Instruction isSetSpecificItem = new Instruction(m_sffDropDownList2, Instruction.InstructionTypes.SetValue, m_sffDropDownList2.Items[1]);
' Create instructions
Dim isClearText As Instruction = New Instruction(m_sffComboBox, Instruction.InstructionTypes.SetValue, Nothing)
Dim isSetNewText As Instruction = New Instruction(m_sffDropDownList1, Instruction.InstructionTypes.SetValue, "Product Number")
Dim isSetSpecificItem As Instruction = New Instruction(m_sffDropDownList2, Instruction.InstructionTypes.SetValue, m_sffDropDownList2.Items(1))
Dim risInstructions As Instruction() = New Instruction() {isClearText, isSetNewText, isSetSpecificItem}

Instructions that include else instructions:

// Create instructions
Instruction isClearText = new Instruction(m_sffComboBox, Instruction.InstructionTypes.SetValue, null, m_sffDropDownList2.Items[0]);
Instruction isSetNewText = new Instruction(m_sffDropDownList1, Instruction.InstructionTypes.SetValue, "Product Number", null);
Instruction isSetSpecificItem = new Instruction(m_sffDropDownList2, Instruction.InstructionTypes.SetValue, m_sffDropDownList2.Items[1], "Product Number");
Instruction[] risInstructions = new Instruction[] { isClearText, isSetNewText, isSetSpecificItem };
' Create instructions
Dim isClearText As Instruction = New Instruction(m_sffComboBox, Instruction.InstructionTypes.SetValue, Nothing, m_sffDropDownList2.Items(0))
Dim isSetNewText As Instruction = New Instruction(m_sffDropDownList1, Instruction.InstructionTypes.SetValue, "Product Number", Nothing)
Dim isSetSpecificItem As Instruction = New Instruction(m_sffDropDownList2, Instruction.InstructionTypes.SetValue, m_sffDropDownList2.Items(1), "Product Number")
Dim risInstructions As Instruction() = New Instruction() { isClearText, isSetNewText, isSetSpecificItem }

Set new date

Similar to objects of type TextFormField and SelectionFormField, for DateFormFields an instruction can be defined that sets a new value or clears the displayed text. To do this by dialog, to set a new date, the Set new value item must be combined with a string, that represents a specific date. To remove the displayed date, the Empty (no value set) flag must be set.

Image

To create these instructions programmatically, use one of the following code snippets.

Instructions without else instructions:

// Create instructions
Instruction isClearDate = new Instruction(m_dffDateFormField1, Instruction.InstructionTypes.SetValue, null);
Instruction isSetNewDate = new Instruction(m_dffDateFormField2, Instruction.InstructionTypes.SetValue, new System.DateTime(2020, 7, 15));
Instruction[] risInstructions = new Instruction[] { isClearDate, isSetNewDate };
' Create instructions
Dim isClearDate As Instruction = New Instruction(m_dffDateFormField1, Instruction.InstructionTypes.SetValue, Nothing)
Dim isSetNewDate As Instruction = New Instruction(m_dffDateFormField2, Instruction.InstructionTypes.SetValue, New DateTime(2020, 7, 15))
Dim risInstructions As Instruction() = New Instruction() { isClearDate, isSetNewDate }

Instructions that include else instructions:

// Create instructions
Instruction isClearDate = new Instruction(m_dffDateFormField1, Instruction.InstructionTypes.SetValue, null, new System.DateTime(2020, 7, 15));
Instruction isSetNewDate = new Instruction(m_dffDateFormField2, Instruction.InstructionTypes.SetValue, new System.DateTime(2020, 7, 15), null);
Instruction[] risInstructions = new Instruction[] { isClearDate, isSetNewDate };
' Create instructions
Dim isClearDate As Instruction = New Instruction(m_dffDateFormField1, Instruction.InstructionTypes.SetValue, Nothing, New DateTime(2020, 7, 15))
Dim isSetNewDate As Instruction = New Instruction(m_dffDateFormField2, Instruction.InstructionTypes.SetValue, New DateTime(2020, 7, 15), Nothing)
Dim risInstructions As Instruction() = New Instruction() { isClearDate, isSetNewDate }

Change combo box items

A type specific instruction can be set for objects of type SelectionFormField. By setting the Set new items flag, a new list of items can be specified that replaces the SelectionFormField.Items property value when the corresponding conditions are fulfilled. Like with all instruction types, an else instruction can be defined.

Image

To create this instruction programmatically, use one of the following code snippets.

Instruction without else instructions:

// Create instructions
Instruction isSetNewItems = new Instruction(m_sffComboBox, Instruction.InstructionTypes.SetItems, new string[] { "Text Control", "TX Spell", "TX Barcode" });
Instruction[] risInstructions = new Instruction[] { isSetNewItems };
' Create instructions
Dim isSetNewItems As Instruction = New Instruction(m_sffComboBox, Instruction.InstructionTypes.SetItems, New String() {"Text Control", "TX Spell", "TX Barcode"})
Dim risInstructions As Instruction() = New Instruction() { isSetNewItems }

Instruction that includes else instructions:

// Create instructions
Instruction isSetNewItems = new Instruction(m_sffComboBox, Instruction.InstructionTypes.SetItems, new string[] { "Text Control", "TX Spell", "TX Barcode" }, null);
Instruction[] risInstructions = new Instruction[] { isSetNewItems };
' Create instructions
Dim isSetNewItems As Instruction = New Instruction(m_sffComboBox, Instruction.InstructionTypes.SetItems, New String() {"Text Control", "TX Spell", "TX Barcode"}, Nothing)
Dim risInstructions As Instruction() = New Instruction() { isSetNewItems }

Reset form fields

Sometimes it is necessary to disable the possibility to edit a form field when certain conditions meet. In this context, also previously entered content should be removed and the invalid state, if set by another Conditional Instruction, be reset.

To do this, three instructions must be created. One, that uses the Deny editing instruction type to disable the corresponding form field. A second one, that applies the Empty (no value set) flag in combination with the Set new value type to remove the form field's content. And a last instruction that marks the form field as valid by using the Set value as valid instruction type.

When creating these instructions by dialog, for both Deny editing and Set value as valid else instructions are created automatically. Deny editing gets the else instruction Allow editing. It enables the form field when the conditions for the instruction Deny editing are not met. The defined else instruction for Set value as valid is Set value as invalid. Due to the fact that it is expected that another Conditional Instruction determines whether or not the form field should be marked as invalid, this else instruction is disabled by unchecking the corresponding check box inside the Advanced Settings dialog. Furthermore, there is no need to apply this Conditional Instruction during initializing the form. Because of this, for all instructions the Advanced Settings dialog is opened to uncheck the Is initial instruction check box.

These instructions can be applied to all types of form fields. The only difference is when applying the Set new value instruction to objects of type CheckFormField. Since the Empty (no value set) flag cannot be set for this type, either Checked or Unchecked must be set as reset value.

Image

To create these instructions programmatically, use the following code snippets.

// Create instructions
Instruction isDenyEditing = new Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsEnabled, false, true) { IsInitialInstruction = false };
Instruction isClearText = new Instruction(m_tffTextFormField, Instruction.InstructionTypes.SetValue, null) { IsInitialInstruction = false };
Instruction isSetValueAsValid = new Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsValueValid, true) { IsInitialInstruction = false };
Instruction[] risInstructions = new Instruction[] { isDenyEditing, isClearText, isSetValueAsValid };
' Create instructions
Dim isDenyEditing As Instruction = New Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsEnabled, False, True) With {
    .IsInitialInstruction = False
}
Dim isClearText As Instruction = New Instruction(m_tffTextFormField, Instruction.InstructionTypes.SetValue, Nothing) With {
    .IsInitialInstruction = False
}
Dim isSetValueAsValid As Instruction = New Instruction(m_tffTextFormField, Instruction.InstructionTypes.IsValueValid, True) With {
    .IsInitialInstruction = False
}
Dim risInstructions As Instruction() = New Instruction() { isDenyEditing, isClearText, isSetValueAsValid }

Mark combo box as invalid when initialized

The following instruction represents an application of Conditional Instructions where it is required to execute an instruction only when initializing the form. It marks a combo box, where no text is set, as invalid to inform the user that it is required to fill out that form field. In this context, it is assumed that another Conditional Instruction validates the displayed text when the user types in text or selects an item. Because of this, there is no guarantee that the combo box is marked as valid, if text is displayed or as invalid, if it is cleared. Considering this, applying the Conditional Instruction during user interaction could lead to an unwanted behavior. This makes it is necessary to limit the application of the Conditional Instruction to the moment of form initialization.

The following screenshot shows how such a Conditional Instruction is implemented by dialog. A condition is created, where it is guaranteed, that it is fulfilled when initializing the form. The instruction marks the drop down as invalid. No else instruction is needed and the instruction is only applied during the initialization of the form. Both is set by unchecking the corresponding check boxes inside the Advanced Settings dialog.

Image

To create this instruction programmatically, use the following code snippets.

// Create instructions
Instruction isSetValueAsInvalid = new Instruction(m_sffComboBox, Instruction.InstructionTypes.IsValueValid, false) { IsFormFieldChangeInstruction = false };
Instruction[] risInstructions = new Instruction[] { isSetValueAsInvalid };
' Create instructions
Dim isSetValueAsInvalid As Instruction = New Instruction(m_sffComboBox, Instruction.InstructionTypes.IsValueValid, False) With {
    .IsFormFieldChangeInstruction = False
}
Dim risInstructions As Instruction() = New Instruction() { isSetValueAsInvalid }

How-to: Creating a Radio Button Group

Many forms use radio button groups to restrict the number of selection options to just one. TX Text Control supports the corresponding behavior and appearance of radion button groups by using CheckFormFields in combination with Conditional Instructions.

As follows a sample with two CheckFormFields (radioButton1 and radioButton2) shows how to implement such a radio button group in four steps:

1. Set radio button appearance

The corresponding CheckFormFields should have the typical radio button appearance. To do this by using the RibbonFormFieldsTab, select the check form field inside the Text Control, go to the RibbonFormFieldsTab's Check Box Properties group and choose the correspnding Checked and Unchecked Symbols.

Image

When creating such a group by code, the corresponding characters must be set to the CheckFormField.CheckedCharacter and CheckFormField.UncheckedCharacter properties:

To create this condition programmatically, use the following code snippet:

// Set radio button appearance
cffRadioButton1.CheckedCharacter = cffRadioButton2.CheckedCharacter = '%c9';
cffRadioButton1.UncheckedCharacter = cffRadioButton2.UncheckedCharacter = '+55';
' Set radio button appearance
cffRadioButton1.CheckedCharacter = Convert.ToChar(Convert.ToInt32("25c9", 16))
cffRadioButton2.CheckedCharacter = Convert.ToChar(Convert.ToInt32("25c9", 16))
cffRadioButton1.UncheckedCharacter = Convert.ToChar(Convert.ToInt32("2b55", 16))
cffRadioButton2.UncheckedCharacter = Convert.ToChar(Convert.ToInt32("2b55", 16))

2. Uncheck all check form fields

In most cases, no radio button is selected when the form is initialized. To uncheck check form fields, select the corresponding check form field and uncheck it by mouse click or pressing the space key. To do this programmatically, the CheckFormField.Checked property must be set to false.

// Uncheck radio button
cffRadioButton1.Checked = false;
cffRadioButton2.Checked = false;
' Uncheck radio button
cffRadioButton1.Checked = False
cffRadioButton2.Checked = False

3. Handle CheckFormField.Checked value is changed to true

One basic behavior of a radio button group is, that when a radio button is chosen, all other radio buttons become deselected. To implement this, for each CheckFormField, that represents a radio button, a Conditional Instruction must be created. That Conditional Instruction contains a condition that is fulfilled, when the radio button is selected. In this case, instructions are executed, that deselect all other radio button.

In this sample, creating such a Conditional Instruction for CheckFormField radioButton1 by dialog looks as follows:

Image

Doing this for radioButton2 the dialog looks like:

Image

The following code snippet shows how to create both Conditional Instructions programmatically:

// Create 'Radio Button 1 Checked'

// Create condition and instruction
Condition cdIsChecked1 = new Condition(cffRadioButton1, true);
Instruction isUncheck2 = new Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, false);

// Create conditional instruction
ConditionalInstruction ciRadioButton1Checked = new ConditionalInstruction("Radio Button 1 Checked", new Condition[] { cdIsChecked1 }, new Instruction[] { isUncheck2 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton1Checked);


// Create 'Radio Button 2 Checked'

// Create condition and instruction
Condition cdIsChecked2 = new Condition(cffRadioButton2, true);
Instruction isUncheck1 = new Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, false);

// Create conditional instruction
ConditionalInstruction ciRadioButton2Checked = new ConditionalInstruction("Radio Button 2 Checked", new Condition[] { cdIsChecked2 }, new Instruction[] { isUncheck1 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton2Checked);
' Create 'Radio Button 1 Checked'

' Create condition and instruction
Dim cdIsChecked1 As Condition = New Condition(cffRadioButton1, True)
Dim isUncheck2 As Instruction = New Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, False)

' Create conditional instruction
Dim ciRadioButton1Checked As ConditionalInstruction = New ConditionalInstruction("Radio Button 1 Checked", New Condition() { cdIsChecked1 }, New Instruction() { isUncheck2 })

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


' Create 'Radio Button 2 Checked'

' Create condition and instruction
Dim cdIsChecked2 As Condition = New Condition(cffRadioButton2, True)
Dim isUncheck1 As Instruction = New Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, False)

' Create conditional instruction
Dim ciRadioButton2Checked As ConditionalInstruction = New ConditionalInstruction("Radio Button 2 Checked", New Condition() { cdIsChecked2 }, New Instruction() { isUncheck1 })

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

4. Handle CheckFormField.Checked value is changed to false

The other basic behavior of a radio button group is, that a radio button cannot be unckecked directly. To implement this, for each radio button a Conditional Instruction must be created, where the condition tests the CheckFormField whether its Checked property changed to false. If that condition is met, the Conditional Instruction executes an instruction, that resets the CheckFormField.Checked property value to true.

Due to the fact, that all Conditional Instructions inside the document are automatically applied when changing the document to write-protected, the corresponding Unchecked Conditional Instruction of a radio button would be fulfilled and applied when initializing the form. This means that, the radio button of the last handled Conditional Instruction is displayed as selected after initializing the form, even if it was set as deselected when creating the document.

To prevent this, the instruction's Advanced Settings dialog must be opened to unckeck the Is initial instruction check box. This disables applying the instruction when the document is changing to write-protected. To implement this programmatically, the Instruction.IsInitialInstruction property must be set to false.

In this sample, creating such a Conditional Instruction for CheckFormField radioButton1 by dialog looks as follows

Image

Doing this for radioButton2 the dialog looks like:

Image

The following code snippet shows how to create both Conditional Instructions programmatically:

// Create 'Radio Button 1 Unchecked'

// Create condition and instruction
Condition cdIsUnchecked1 = new Condition(cffRadioButton1, false);
Instruction isCheck1 = new Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, true) { IsInitialInstruction = false };

// Create conditional instruction
ConditionalInstruction ciRadioButton1Unchecked = new ConditionalInstruction("Radio Button 1 Unchecked", new Condition[] { cdIsUnchecked1 }, new Instruction[] { isCheck1 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton1Unchecked);


// Create 'Radio Button 2 Unchecked'

// Create condition and instruction
Condition cdIsUnchecked2 = new Condition(cffRadioButton2, false);
Instruction isCheck2 = new Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, true) { IsInitialInstruction = false };

// Create conditional instruction
ConditionalInstruction ciRadioButton2Unchecked = new ConditionalInstruction("Radio Button 2 Unchecked", new Condition[] { cdIsUnchecked2 }, new Instruction[] { isCheck2 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton2Unchecked);
' Create 'Radio Button 1 Unchecked'

' Create condition and instruction
Dim cdIsUnchecked1 As Condition = New Condition(cffRadioButton1, False)
Dim isCheck1 As Instruction = New Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, True) With {
    .IsInitialInstruction = False
}

' Create conditional instruction
Dim ciRadioButton1Unchecked As ConditionalInstruction = New ConditionalInstruction("Radio Button 1 Unchecked", New Condition() { cdIsUnchecked1 }, New Instruction() { isCheck1 })

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


' Create 'Radio Button 2 Unchecked'

' Create condition and instruction
Dim cdIsUnchecked2 As Condition = New Condition(cffRadioButton2, False)
Dim isCheck2 As Instruction = New Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, True) With {
    .IsInitialInstruction = False
}

' Create conditional instruction
Dim ciRadioButton2Unchecked As ConditionalInstruction = New ConditionalInstruction("Radio Button 2 Unchecked", New Condition() { cdIsUnchecked2 }, New Instruction() { isCheck2 })

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