The Dashboard Builder include file feature provides a way to partition dashboard development and to reuse content in multiple dashboards. It allows you to include in a dashboard the objects, functions, and variables of another rtv file. Unlike the Composite object, the included file is not in an object; rather, the contents of the included file are added to the dashboard.

A common use of include files is for navigation controls and status bars that are part of multiple dashboards. The following illustration shows a simple status bar. Here the status bar contains an indicator (the green circle) of connectivity to the correlator, as well as the Apama logo. These objects could be defined in the rtv file statusbar.rtv file as follows:

The file statusbar.rtv could then be included in another dashboard.

To include an rtv file in a dashboard, select IncludeFiles in the Tools menu. This will display the Include Files dialog.

The Add and Remove buttons are used to add and remove included rtv files. More than one rtv file can be included, and the included files can themselves include other files. However, a file will only be included once.

All the objects, functions, and variables that are defined in an included file become part of the dashboard. Within the Dashboard Builder these are, with one exception, read-only. They appear, can be copied, and can be used in attachments, but they cannot be modified. To modify included elements, open the file containing them in the Dashboard Builder.

The exception is for the initial value of an included variable. Within a dashboard, you can override the initial value of included variables. Consider, for example, an included file that contains a label that is attached to the variable headerTitle. When you include this file in a dashboard, the value of the variable headerTitle can be set to the title of the dashboard.

Note: If objects from an included display file have the same value for the objName property as objects in the current display, or other included displays, this may cause links to attach to the wrong object. To avoid this overlap, assign a unique value to the objName property of objects in files that you intend to include in other displays.

The background properties such as Model Width, Model Height, and bgColor of included files are ignored.

Substitutions such as $instanceId may be used in attachments in included files. Substitutions and variables in included files are scoped to the including dashboard. Runtime changes to their values will be reflected in included objects and functions. An attachment in an included file filtering on $instanceId will update whenever $instanceId changes in the dashboard.