Data Section

Edit online

Use Data Section 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.

The Data Section control is a composite coach view that includes the Data control and a content box. Configuration properties are provided so that you can implement the coach view by using either the ready-to-use Data control, or the content box for a customized implementation. For custom implementations, you can also configure how local and incoming changes to the variables are handled in the coach view.

Restrictions and limitations

Restrictions

This view supports only the Required, Hidden, and None visibility properties.
If you use this view in a custom dashboard, you also need to add the Refresh Controller view 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 Refresh Button to the dashboard, too. For more information, see Refresh Controller control and Refresh Button control.

Limitations: None

Configuration properties

Set or modify view configuration in the Configuration properties tab.

Table 1. Data Section configuration properties
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 view to be refreshed. Bind this property to the private variable that is used by Refresh Controller, Refresh Button, or both. 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 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: `SAVE` Local changes are saved `DISCARD` Incoming changes overwrite local changes `KEEP_LOCAL` Local changes are not overwritten by incoming changes `KEEP_NON_CONFLICTING_LOCAL` Only non-conflicting local changes are kept; conflicting local changes are overwritten 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