Forms and Conditional Instructions

Forms that users fill out on screen, such as a booking request or a checklist, are ordinary documents with form fields in them. In a WPF application, the TextControl holds the form: code-behind inserts text boxes, check boxes, drop-down lists and date pickers, protects everything else, listens to the values users enter and adds conditional instructions, validation rules that travel with the document and run while the form is filled out.

Below are the classes, properties and events your code works with, each with the page that explains it: the ribbon, the code that inserts, protects and reads a form in Form Fields and Conditional Instructions, the validation rules in Conditional Instructions and filling forms from data in Merge Fields. Form fields are part of the Enterprise edition, as Editions shows.

Form Field Types

Each form field is a FormField, which derives from TextField, and WPF.TextControl.FormFields returns the FormFieldCollection of the whole document. Your code reads and sets the value of each type through a different property, and each type has its own event for the values users enter:

The drop-down lists, combo boxes and what users see are described in Form Field Types.

Create a Form

FormFieldCollection.Add inserts a new form field at the input position and returns true when it has been inserted. Insert Form Fields in Code writes a booking form with one field of each type and explains the constructors; besides the width overload used there, the DateFormField constructor also takes an initial date, as in new DateFormField(DateTime.Today, 0). The TX Text Control format, DOCX, DOC and RTF keep form fields, and a PDF created from the document contains them as PDF form fields.

Protect the Form

A form is ready for users when DocumentPermissions.ReadOnly and AllowEditingFormFields are true and the EditMode is ReadAndSelect; EditMode.Edit removes the protection. The code is in Protect the Form, and passwords and further permissions in Document Protection and User Permissions.

React to Values the User Enters

The events of the table above are raised when the user changes a value, and for typed text and dates when the user leaves the field. Setting SelectedIndex, Checked or Date in code raises none of them. Read the Values reads every field of a form and handles FormFieldCheckChanged.

Validate Values With Conditional Instructions

A conditional instruction ties conditions on form field values to instructions that change form fields: mark a value as valid or invalid, enable or disable a field, set a value or replace the items of a drop-down list. The rules are stored in the document and applied while the protected form is filled out, as long as IsFormFieldValidationEnabled is true. Conditional Instructions explains how to create them with the ribbon and in code, the operators of each form field type, And/Or groups, the instruction types and a complete booking form.

Read and Flatten the Values

Read each value from the property of its field type, as listed in the first table. Before a filled form is archived, replace the fields with their text so that the values can't be changed: TextFieldCollection.Clear with true removes the fields that GetTextFields returns for TextFieldType.FormFields and keeps their text. Exporting Interactive and Flattened Forms shows the code, and PDF forms returned by users are read as described in Reading Form Fields and Values.

Next Steps

• Form Fields and Conditional Instructions: the Form Fields ribbon tab, inserting, protecting and reading forms.
• Conditional Instructions: every condition and instruction, with a complete booking form.
• Document Protection and User Permissions: permissions and passwords.
• Merge Fields: fill form fields with data.
• Fields and Subtext Parts: the other kinds of fields.