Data Section control
Use this control to provide a collapsible coach view section that displays the business data for an instance. A configuration property determines whether users can change the values of these variables.
Restrictions and limitations
- Restrictions
- This control supports only the Required, Hidden, and None visibility properties.
- If you use this control in a custom dashboard, you also need to add the Refresh Controller control to the custom dashboard to enable the contents of the view to be refreshed. To enable users to also manually refresh the contents of the view, add the Refresh Button control to the dashboard too. For more information, see Refresh Controller control and Refresh Button control.
- Limitations
- None
Configuration properties
Set or modify control configuration in the Configuration properties tab.| Configuration property | Property variable | Description |
|---|---|---|
| Section title | sectionTitle (String) | The title that is displayed in the section
header. Default: "Data" |
| Collapsible | collapsible (Boolean) | Indicates whether
the section can be collapsed. Default: false (not collapsible) |
| Collapsed | collapsed (Boolean) | Indicates whether the section is collapsed when the view opens. Default: false (not collapsed) |
| Height | height (Integer) | The height of the control in pixels. When no value is specified, the height of the control is 100 pixels by default. |
| Instance ID | instanceId (String) | The instance to which the data belongs. Default: None |
| Retrieve data | retrieveDataService (Default Retrieve Data Service) | The service that retrieves the data. Default: Default Retrieve Data Service |
| Refresh trigger | refreshTrigger (Boolean) | Enables the contents of the control to be
refreshed. Bind this property to the private variable that is used
by the Refresh Controller control, the Refresh Button controls, or
both controls. When the value of the bound variable changes to true, the view is refreshed. After the view is refreshed, the value of the variable returns to false. Default: false (no refresh pending) |
| Edit mode | editMode (Boolean) | Determines whether the ready-to-use Data
control or the content box is used for the data implementation. Default: false (The Data control is used) |
| Instance status | instanceStatus (String) | The value of the configuration property
determines whether the instance data that is displayed in the view
can be edited. For example, if the status of the instance is completed,
the data cannot be edited. If the data cannot be edited, the Data
section is shown in read-only mode. This property is available only when the value of the Edit mode property is set to true. |
| Failed save message | failedSaveMessage (String) | The name of the variable that contains the
message that is displayed when the changes that the user made to the
data cannot be saved. This property is available only when the value of the Edit mode property is set to true. Default: None |
| Localization Service | localizationService | The service that is used to retrieve
the globalized strings for use with this coach view Default: Dashboards Localized Messages Loader |
| Boundary event type | boundaryEventType (String) | The type of boundary event that is triggered
by the coach view. This property is available only when the value
of the Edit mode property is set to true. If
a variable is bound to this property, the coach view displays save
and merge options that trigger the corresponding type of boundary
event. Depending on the user's selection, the variable is set to one
of the following values:
If a variable is not bound to this property, the Save button triggers the boundary event. |
| Incoming changes | incomingChanges (Any) | The updated values from the server for the
variables in the instance data in the coach view. The property contains
an entry for each changed variable; the entry name is the variable
name and the value is the new server value. For example, tw.local.myVariable maps
to incomingChanges.myVariable. This property is available only when the value of the Edit mode property is set to true. |
| Local changes | localChanges (Any) | The updated values in the coach view for
the variables in the instance data. The property contains an entry
for each changed variable; the entry name is the variable name and
the value is the new server value. For example, tw.local.myVariable maps
to localChanges.myVariable. This property is available only when the value of the Edit mode property is set to true. |
| Incoming changes merged | incomingChangesMerged (Boolean) | Indicates that incoming changes were automatically
merged into the local data. This property is available only when the value
of the Edit mode property is set to true. Bind this property to a Boolean variable. When the value of the bound variable changes to true, it indicates that incoming changes were merged and the user is notified. After the notification is posted, the value of the variable is reset to false. |
| Unsaved local changes | unsavedLocalChanges (Boolean) | Indicates whether the Data Section coach
view contains unsaved changes. This property is available only when the value
of the Edit mode property is set to true. If a variable is bound to this property, the property value is set to true when local changes are detected. The user is notified if an attempt is made to navigate away from the page without saving the changes. To disable the notification, set the value of the property to false. |
| Initial values | initialValues (Any) | The initial values for the variables in
the coach view before any changes were made. These values are used
to determine whether conflicts exist between the local and incoming
changes. This property is available only when the value of the Edit mode property is set to true. |
Customizing the Data Section coach view
You can customize the Data Section coach view in the following ways:- Data implementation
- The data for the coach view can be implemented by using either
the ready-to-use Data control or the content box for a custom implementation.
The value of the Edit mode configuration property
determines which implementation is used:
- Data control implementation
- Use the Data control to display a read-only view of the business
data; the data is provided by the default Retrieve Data Service.
For this implementation, ensure that the value of the Edit mode configuration property is set to false (the default setting).
- Custom implementation
- Use a custom implementation that is based on the content box to
provide users with a view for viewing and updating business data.
They can save their changes by clicking the Save button
that is rendered in the header. For this implementation, set the value
of the Edit mode configuration property to true.
In addition, bind a variable to the Failed save message configuration
property to provide an error message when updates to the data cannot
be saved.
The Save button is enabled when a change is detected to data that is bound to a coach view in the content box. When the button is clicked, a boundary event is triggered, which can trigger a service call to save the data. For example, in a custom instance UI, you can wire the event to a General System service that is configured to send the variable updates to the parent instance. The Instance Details UI Service template in the Dashboards toolkit contains an example implementation.
The edit mode also supports data synchronization if the Boundary event type, Incoming changes, and Local changes configuration properties are bound to variables. When updates to instance data are detected on the server, information in these variables is used to display merge options to the user in the coach view.
- Header section
- Customize the header of the section in the following ways:
- Change the name of the section by updating the Section title configuration property
- Change the expand and collapse behavior of the view by updating the Collapsible and Collapsed configuration properties