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 }