Form WebPart
The Form Web Part can be configured with various fields that can be configured to provide an input form. This functionality allows two application scenarios:
- Search Form: User input can be processed using the connection framework, i.e. to filter the results of a Data Grid Web Part using a condition on the grid's data provider.
- Custom View/Edit/Create Form: In combination with a data adapter, the Form Web Part can be used for viewing, editing and creating items. This allows the configuration of customized input fields with extended functionality (i.e. field validation or dynamic read-only conditions based on the expression engine).
Important configuration parameters
- The configuration parameter Columns can be used to modify the layout of the form.
- The CloseAction property specifies the behavior of the form when the user selects the 'Save' or 'Cancel' button. This is especially relevant if the form is displayed within a dialog window.
- The Name property specifies a name that can be used for accessing the Form Web Part from the expression engine. If the form is configured with a data adapter, the specified name has to correspond to a field/property on the item that is accessed. Also, the name is used when field values are accessed from the expression engine, i.e. for configuring dependent fields using the ConnectionData expression variable.
- The ReadOnlyExpression parameter defines how the form is displayed per default (Read-only or Editable). If "Read-only" is selected, the user can only switch to "edit" mode if the EnableToggleEdit property is specified as true.
Some parameters are only relevant, if the form is configured with a data adapter:
The setting for the ReadOnlyExpression parameter is only evaluated on post-back, i.e. when the page is loaded and therefore a field cannot be set to read-only dynamically with the AJAX connection framework.
Form Fields
General Field Behavior
A lot of the configuration properties for the different field types are identical:
- The Name property specifies a name that can be used to access the field value from the expression engine. Also, if configured with a data adapter, this name has to correspond to a property on the item that is currently edited/displayed.
- Just like for the form, the ReadOnlyExpression property specifies, whether the field is rendered in Read-only or in Editable mode.
- The Required property specifies, whether a field is mandatory.
- If the form is configured with a data adapter, the WriteMode parameter defines, whether values of the field should be written to the item. If this value is specified as Ignore or IgnoreIfHidden, no values will be written.
- The DefaultValue or DefaultValueExpression property specifies a default value for the field.
The default value for a field is only evaluated when the form is loaded. Therefore, it is not possible to use the expression engine to change this value dynamically.
On most field types, the DataFieldValidator element can be used to validate user with the expression engine. Likewise, the VisibilityCondition element can be used to define the visibility of a field dynamically.
For text- or number fields, the TriggerBehavior field can be used to determine the trigger behavior.
Field Types
The Form Web Part can be configured with of different field types within the Fields element:
| Field Type | Functionality | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AttachmentsField | Allows specifying an attachment for an item. | ||||||||||||||
| BooleanField | Allows input of a boolean value. This field can be made mandatory to be checked. | ||||||||||||||
| ChoiceField |
The available choice items for a choice field can be aggregated by different choice providers. The following choice providers are available:
|
||||||||||||||
| CompositeField | Allows displaying information based on a transformer configuration. This allows creating unique layouts, depending on the requirements of the information to be displayed. The displayed data is aggregated by a data provider. The behavior of this field is identical to the Composite Web Part. | ||||||||||||||
| DateField | Allows input of date information. | ||||||||||||||
| ExpressionField | Allows evaluating an expression and displaying the result value. This functionality is similar to a CalculatedColumn within a Data Grid Web Part. If a data adapter has been specified, the value can be written to the item when it is saved. For more information on how to use the expression engine. | ||||||||||||||
| FieldRef | Allows referencing an existing field, depending on the configured data adapter. For instance, this could be a column on a SharePoint list (if a ListDataProvider is used). It is possible to overwrite some parameters (e.g. the ReadOnlyExpression) on the configuration. | ||||||||||||||
| ImageTagField | Allows selection from a number of predefined tags by clicking on an image. This functionality is identical to the functionality of the Image Tag Web Part. | ||||||||||||||
| LinkField | Allows input of a hyperlink. | ||||||||||||||
| NumberField | Allows input of numerical data. With the Format parameter, a number format can be specified for the number. This field supports a placeholder value. | ||||||||||||||
| PersonField | The PersonField element allows the selection of a user or group account. | ||||||||||||||
| RichTextField |
The RichTextField allows specifying HTML and rich text. The UseToolbar property specifies, whether the rich text field should use a toolbar instead of the SharePoint ribbon for command buttons. Within the HiddenRibbonElements property, commands can be disabled.
The RichTextField control is not connectable to other MatchPoint controls. |
||||||||||||||
| SectionField | This field has no meaning as an input field. It is a graphical element that allows grouping of the different fields in sections. The Style property defines whether a section is collapsed or expanded by default. | ||||||||||||||
| TextField | Allows input of free text. This field supports a placeholder value. | ||||||||||||||
| TagChoiceField | Allows the selection of MatchPoint tags. | ||||||||||||||
| TermChoiceField | Allows the selection of SharePoint terms. |
Custom Fields
MatchPoint supports the implementation of custom fields for the Form Web Part. There are two classes that have to be extended:
- FieldControl implements functionality for rendering the field within the Form Web Part.
- FormDataField Class implements functionality for the actual data field.
For code samples refer to the Colygon.MatchPoint.Samples.zip provided with every MatchPoint release.
Post Actions
Post actions can be configured to execute additional actions when the user clicks the "Save" (or "Create") button on a Form Web Part. This provides a lot of flexibility when using the Form Web Part.
The available actions are identical to the actions that can be configured within a MatchPoint Workflow. The following actions are available for the PostActions configuration element:
| Action | Functionality |
|---|---|
| CopyFileAction | Copies or moves a file |
| CheckInFileAction | Checks in a file |
| CheckOutFileAction | Checks out a file |
| CreateListItemAction | Creates a new list item with tags and field values |
| CreateTaskAction | Creates a new task item |
| CreateWebAction | Creates a new web or site collection |
| CreateWorkspaceAction | Creates a new MatchPoint workspace |
| DeleteFileAction | Deletes a file |
| DeleteItemAction | Deletes a list item |
| EvaluateAction | Evaluates a MatchPoint expression |
| ForEachAction | Evaluates an expression that returns an IEnumerable object and executes one or more actions on each of the objects. |
| ModifyItemAction | Modifies a list item (tags, field values) |
| ModifyUpdatableAction | Modifies an object implementing the IUpdatable interface |
| SendMailAction | sends an email message to recipients from the AD |
| SetFieldAction | Sets a field value on the item. |
| SetPermissionsAction | Sets permissions on the item. |
| SetTagsAction | Sets tags on the item. |
| SetVariableAction | Sets a value for a variable on the workflow instance. |
| SwitchAction | Executes a set of actions, based on initial conditions. |
The functionality of some post actions depends on the kind of item that is available within the Form Web Part. Therefore, it is possible that an action cannot be used even though it is available as a configuration element. For instance, the SetTagsAction is only available if the current item supports the use of MatchPoint tags.
By implementing the BaseAction class, custom workflow actions can be implemented. The base class provides access to the WorkflowScope object that provides access to the current workflow item. It is required to implement the Run method.
For code samples refer to the Colygon.MatchPoint.Samples.zip provided with every MatchPoint release.