This page is a Draft, its content is not complete and might contain errors.
As of version 4.2 of
CWR Mobile CRM a new model is used to create controls. This model will allow more control over the form and its controls. The ICustomControl interface is now deprecated but still available for legacy controls.
EditInterfaces
EditIFormControl
All controls on forms now derive from the IFormControl interface. This interface is also used by the control generated in the Form designer. This will allow users to access certain properties on the standard controls which where previously not available.
All Custom Form Controls must inherit directly or indirectly from the System.Windows.Control class and must implement the IFormControl interface.
The IFormControl interface provides the following members:
| void Configure(IFormContext, string, string) | This method is called after the control is instantiated and passed a reference to the FormContext, tag name for the control and the configuration xml |
| RequirementLevel RequirementLevel | This property indicates the requirement level of the control |
| bool IsReadOnly | This property indicates if this control is readonly |
| bool Focus() | This method should handle the standard Focus behaviour as implemented by .NET controls |
| bool Validate (out string) | Performs validation of this control |
| object SaveState() | Returns the current state of the control. This is used if the user navigates away from this form by for example opening a related view |
| void LoadState(object) | Restores the state when the user returns to the form |
EditIFormContext2
The IFormContext2 interface allows custom controls to access data, events and other controls.
These are the most important methods on the IFormContext
| object GetValue(string) | Returns the value of the attribute. Note that this method may return a null value if the property value has not been set. |
| void SetValue(string, object) | Sets the value of an attribute. |
| IFormControl GetFormControl(string) | Returns a control by its tag. The result can also be cast to System.Windows.Control |
| EventHandler SourceRecordChange | Event indicating the underlying record has changed and the new data is available for populating in the controls. For new record this means the record mapping has been completed, for existing records the record has retrieved from the database. |
EditImplementation guidelines
- The SaveState/LoadState methods should never update or alter the IFormContext or other controls.
- The IFormContext.SetValue method should only be called if the value was changed by an action initiated by the user and only if the value must actually be changed. Triggering the IfromContext.SetValue (indirectly) from the IFormContext.FormChanged event may otherwise result in a loop.
- Controls showing UI which allow modification of attributes should bind to the IFormContext.FormChanged event and update their values if the attribute is changed by an other control.
- It is recommended that the IsReadonly and RequiredLevel are implemented for controls showing UI and are configurable in the Form editor.
EditChanges from version 4.1
New in version 4.2 are the
SaveState/LoadState methods. A form may be opened multiple times (for example clicking on a parent account in the account form) the form control it self is reused but the contents should remain. To allow each control to maintain its own state the SaveState method is called prior to the new data being loaded. When the user returns to a form the LoadState method is called, this should restore the control to the same state it had when the user left.
To allow all controls (standard and custom) to be accessible a
tag is defined for all controls. For standard controls this is the attribute name, for custom controls a tag must be defined in the form editor.
The
Clear and
SetDefault of the ICustomControl interface are not present on the IFormControl interface instead custom controls should use the SourceRecordChanged on the IFormContext. This event is fired whenever the underlying is changed. The controls should retrieve the value from the record (using IFormContext.GetValue) and update itself accordingly. That is set the value if present for both new and existing records, set a default if there is no value and the IFormContext.ObjectId property is empty and otherwise clear itself.
Hidden controls are no longer necesary to enable access to attributes of the entity. All attributes can be retrieved and stored using the GetValue/SetValue methods on the IFormContext.
ICustomControl interface is still available in the 4.2 SDK, this is only for backwards compatibility. To use the new options available in the 4.2 SDK controls must implement the IFormControl interface. It is not a supported practice to implement both interfaces on the same control as this may lead to unpredicteble behaviour.
EditSee Also