CATSWeb Manager User Guide - Managing Dashboards and Display Parts

One Dashboard Template - The Dashboard Template provides the layout for the Dashboard and consists of Fixed Text Areas and Section Breaks. The Dashboard Templates button on the Manage page is used to create and configure the templates, using the familiar form design process. The presentation of a Dashboard is also affected by settings in the Dashboards section of the user's current Interface Preference. You can choose to limit who can modify the Dashboard Template by specifying ownership.
One or more Display Parts - Display Parts contain the actual content of the Dashboard, such as buttons, links, selection lists and data displays. When a Dashboard is rendered, the configurable content from a Display Part is inserted into designated Fixed Text Area fields on the Dashboard Template. The Display Parts button on the Manage page provides direct acces to create and manage Display Parts, which are actually stored as Component and Subcomponent records. You can choose to limit who can modify the Display Parts by specifying ownership.

The Dashboards feature was designed to allow a Dashboard to contain all content traditionally available on the CATSWeb Home and Task Lists pages, and to be extensible to additional content types in the future. Display Parts may also be used to provide custom content for Issue, Action and Subtask forms when they are displayed in View mode (ex: to provide a custom subtask listing for an Action form). To add a Display Part to an Issue, Action or Subtask form you may either select it as a Child Subform, or specify it to provide content for a Fixed Text Area.

Many types of Display Parts are available, each with its own configuration form. The Display Part types are:

Ad Hoc HTML - Provides a means of directly specifying ad hoc HTML, or including HTML from a file on the Web server. AssurX recommends that you use this Display Part type only if the ones listed below do not meet your needs.

Buttons and Links - Provides a variety of buttons and links that would typically appear on a Home page, such as Queries, Personal Tasks and Department Tasks, Change Passwords, etc. Buttons and links may also use URL Data Links to provide navigation to any location on the Internet or intranet. Each item may be formated as a graphic image or a text link.

Calendar - A Calendar display part displays a calendar view based on dates stored within CATSWeb records. Various information about each record may be displayed within the calendar. See this topic for more information.

Chart - Chart display parts can produce 3D charts and graphs from virtually any data source. See this topic for more information.

Data - Provides formatted data displays with content coming from publicly saved queries, filters and full text searches, or from custom content provided via Data Links or ad hoc SQL statements defined in the Display Part. The current user's Hot List may also be made available.

Data Row Selector - The Data Row Selector display part is available for special applications that require the ability to select and process many data records (rows) from a data source during a single submission. When the user submits the display part, their row selections are passed directly to an ActiveX DLL or Web Service data link. See this topic for more information.

Datasheet Display Part The Datasheet display part is available for special applications that require the ability to select and edit many data records (rows) from a data source during a single submission. The display part creates a user interface for selecting the data records and data entry fields for changing record values. When the user submits the display part, the changes made to the selected records are submitted to CATSWeb. See this topic for more information.

Gauge - The Gauge display part allows an actual or calculated numeric value from a data source to be displayed in a graphical, linear gauge (similar to an automobile gas gauge). The gauge may be oriented horizontally or vertically. See this topic for more information.

Image Map Navigator - The Image Map Navigator is similar to the Image Map Viewer, but only displays the clickable image, instead of a window with two panes. When a user clicks a region of the image, they navigate to the location you have defined for that region. The navigation capabilities are the same as a Buttons and Links display part, but you may define an unlimited number of regions in the image.

Image Map Viewer - The Image Map Viewer provides an intuitive means for users to view a variety of content by clicking on regions of a graphic image that you provide. The display part consists of a window with two panes: one pane displays the clickable image, and the other pane displays content. You may define any number of regions in the graphic image, and associate each region with any type of content. For example, you may have a flowchart which depicts how data and records flow through a business process. By incorporating the flowchart in an Image Map Viewer, users can click on the shapes in the flowchart to view the current data in that stage of the process. All of the content types available in a Data display part are available in Image Map Viewers.

Measurement Summary - A Measurement Summary display part is used to display current information from one or more Measurements. See this topic for more information.

Meter - A Meter display part creates a circular or angular meter, much like a classic automobile speedometer or tachometer. Any number of colored zones may be added to the meter to indicate ranges. See this topic for more information.

Parameters - The Parameters display part type is designed to do nothing other than host Display Part Parameters. It may be used (for example) to localize all input parameters for a Dashboard in one location. See this topic for more information.

Query Lists - Any of the lists from the Query Menu page may be included in this Display Part. These lists allow users to create new queries, advanced searches and Dashboards, or access ones that were saved publicly or privately.

Slider - A Slider display part is similar to a Gauge, but allows a configurable fill color or pattern fill to be used between the beginning of the scale and the current slider position. See this topic for more information.

Special Functions - Enables the Main Page, Query Menu or Reports Menu special functions listings to be used as Display Parts.

System Lists - This Display Part provides selection lists used to add new Issue and Action records, change Department and Personality, select Dashboards, Interface Preferences, etc. CATSWeb automatically provides a standard list when you select the List Type. If you prefer, the bindings for each list may be customized via an Advanced Settings mode (check the box and click the iconic reload button). The Tags (All) and Tags (User) list types produce lists that allow for tag-based navigation, similar to the My Tags and Everyone's Tags lists on the My CATSWeb page.

Thermometer - A Thermometer display part is similar to Gauges and Sliders but uses only the configurable color or pattern fill to indicate the current value (in a traditional thermometer the "fill" is the red or silver liquid). See this topic for more information.

TreeView - The TreeView display part is available to select data from a data source and represent the results as a hierarchical structure using folder images. See this topic for more information.

Virtual Folders - The Virtual Folders display part works like the Image Map Viewer, but uses an arbitrary folder hierarchy as a means of selecting content instead of an image map. When a user clicks a folder in the folder pane, the contents of that folder are displayed in the contents pane. You may also designate "action folders" that take actions (open a form, navigate to another location, etc.) instead of displaying contents. You may create an unlimited number of folders in each display part, arrange them in a tree with an unlimited number of nesting levels, and associate any content or action with each folder. All of the content types available in a Data display part are available in Virtual Folders.

Working with Display Parts and Dashboards

The best way to gain experience with Display Parts and Dashboards is to take a "learn by doing" approch. Experimentation can't harm the CATSWeb system, since Display Parts and Dashboards display information as opposed to creating, editing or deleting information. If you need more detailed information about a particular setting, use the Tool Tip Help available for each field in the configuration forms, or refer to the Settings for Display Parts section below.

Display Part configuration forms are designed to support a wide variety of possible configurations. All of them rely on Reload buttons to allow them to adapt to your needs on-the-fly, as you specify additional information. Most forms have many reload buttons for your convenience, but they all do the same thing: adapt the form based on what you have entered so far.

Some Display Part configuration forms allow you to specify multiple Display Part elements within a single configuration form. For example, the Buttons and Links configuration form allows you to specify up to 10 buttons or links per Display Part. You are not required to use all 10 of the available elements, nor are you required to use them in the order presented without "gaps". At runtime, CATSWeb will generate a Display Part containing only the elements you have specified, in the order you specified them, and will ignore unused "gaps" in the sequence.

Other Display Part configuration forms allow you to specify an unlimited number of elements. You begin by entering a Display Part record that defines the Display Part as a whole (the "parent"), then add as many "child" records as needed to define the desired elements. The Virtual Folders, Image Map Viewer and Image Map Navigator all work in this way. Create the main configuration record first, then use the Add links above the main configuration record's form to add Folders/Subfolders or Regions, as appropriate.

Settings for Display Parts

The following settings apply to Display Parts:

Available - Determines whether or not the Display Part appears in Display Part selection lists. This setting has no effect on the Template list (containing Display Parts) that appears in the Query Chart or Indicator section of query forms. That list is instead controlled by the Query Template settings in Display Parts.
Click Behavior - In an Image Map Viewer, this setting specifies what happens if a user clicks a region that is already active and displaying contents. The Toggle Opened/Closed option causes it to emulate a folder: each click toggles the region between active (open) and inactive (closed).
Columns to Show - When a Measurement or similar data source type is chosen, this setting is made available. It is used to select the data fields (columns) that are made visible in record listings (ex: in the Data Pane of a Trend Chart).
Component Name - The name of the parent Component record for all Display Parts ("Display Parts", read-only).

Contents - Specifies the HTML contents of an Ad Hoc HTML display part. Do not include the <HTML> or <BODY> tags in the HTML, only specify the interior page content (as in a Fixed Text Area). If the contents include standard tokens (variables) such as "{My Name}", these tokens will automatically be replaced with values from the current user's session record when the display part is viewed. The Replacements setting allows for additional replacements and substitutions. The contents may be directly entered, or a file that contains the desired HTML may be referenced like this:

{File: YourFile}

UNC paths may not be used. Here are some examples:

Example	Result
{File: ReadMe.txt}	Loads the contents of the ReadMe.txt file in the CATSWeb folder into the Display Part.
{File: C:\YourFolder\YourFile.dat}	Loads the contents of the YourFile.dat file in the C:\YourFolder folder into the Display Part.
{File: {CATSWeb}\YourSubfolder\YourFile.dat}	Loads the contents of the YourFile.dat file from the YourSubfolder subfolder of the CATSWeb folder into the Display Part. The "{CATSWeb}" token represents the CATSWeb folder on the Web server.

Convert Line Breaks - Used in an Ad Hoc HTML display part, this setting enables the carriage return/line feed pairs in the contents to be converted to HTML line breaks (the <br> tag). Checking this box is appropriate when the contents are being loaded from a file containing plain text, such as the CATSWeb ReadMe.txt file. If the box is left unchecked, such text would appear as a continuous stream (no line breaks) when viewed. See also: Display as Text

Coordinates - This setting is used to define a region in an Image Map Viewer or Image Map Navigator display part. The coordinates are specified as a comma-delimited string, and the format of the string depends on the type of region:

Circle - CenterX, CenterY, Radius

Rectangle - LeftX, TopY, RightX, BottomY

Polygon - X1,Y1, X2,Y2, X3,Y3...

The X & Y values are measured in pixels from the top-left corner of the associated region. The X & Y values may also include a "%" suffix on each value that causes them to be interpretted as percentages instead of pixels (Ex: 0, 0, 50%, 100%).

Data Source Type - The type of data source that provides the contents or action for a Display Part element. After selecting a type, click the iconic reload button to choose the specific data source from a list (if applicable). Most data source types are self-explanatory.

The Containing Record data source type is available for some Display Part types (e.g. Indicator display parts). It provides a means of using the current Issue, Action or Subtask record from a form that contains the Display Part. For example, if the Part Nonconformance issue form has been configured to contain a Meter display part in one of its fixed text areas, and Part Nonconformance #123 is being viewed, then the Part Nonconformance #123 record would be the Containing Record for the Meter. If the Meter's purpose is to to display the value in the Quantity field, then "Quantity" may be entered as the Field Expression setting for the Meter, and Single Value chosen as the Calculation option.

Note that there is no Containing Record when a Display Part is contained in a Dashboard, so this data source type should not be used in Display Parts that will appear in Dashboards. There is also no Containing Record when a form is in Add mode.

The Measurement data source type is a recordset containing all fields in all of the Measurement Data records for the specified Measurement, sorted by the date/time of the Measurement (latest record first). It is typically used in Indicator and Trend Chart display parts that are associated with Measurements. When this data source type is chosen, you may use the Columns to Show setting to select the Measurment Data fields that are made visible in Measurement Data record listings (ex: in the Data Pane of a Trend Chart).

The Tagged Records data source type is a recordset containing information about all the records that have been tagged with one or more public Tags. When it is displayed as the contents of a display part or as drill down information within a display part, it shows a listing of linked records such as Your Form 123, and can optionally Include Management Links. When the recordset is used as a source of data for a display part such as a Meter or Chart, the following fields are available:

RecordType - A short integer CWEB_RECTYPE value that indicates the type of record (1=Issue, 2=Action, 5=Subtask).

RecordID - The ID of the record, as a string (ex: "123").

Category - The category (form name) of the record.

RecordIDStr - The descriptive name of the record that is displayed, such as Your Form 123.

Default Folder/Region - Used in Virtual Folders and Image Map Viewer Display Parts, this specifies the folder or region that displays its contents when the page containing the Display Part first loads. Leave this blank if you prefer the contents pane to be empty when the page first loads.

Description - An optional description of the Display Part.

Destination - The destination of a button, link or clickable region. After specifying a type of destination, click the iconic reload button to choose the specific destination from a list (if applicable). The Anchor destination may be used to navigate to HTML Anchors on the same page as the display part, such as anchors included in a CATSWeb form when a field's HTML Anchor setting is enabled.

Display As Text - Used in an Ad Hoc HTML display part, this setting enables HTML tags and other special characters in the contents to be replaced with escaped character sequences, rendering them inoperative and causing them to display as-is. See also: Convert Line Breaks

Display Part Name - A unique name for the Display Part. DO NOT use special characters used for URL encoding (such as #, ?, %, etc.) in the Display Part Name.

Element Spacers - When a Display Part consists of multiple elements (lists, buttons, links, etc.) this setting determines the type of spacer used between them. You may also specify the number of spacers.

Fields to Hide - You may enter a comma-delimited list of field names to hide in the data table associated with the display part. Columns will not be present for the fields that you specify, the but the fields and their values will still be available to use as data fields for charts, etc.

Folder ID - A unique ID that CATSWeb automatically assigns to each folder in a Virtual Folders display part.

Graphics File/Image File - The filename of a graphics or image file used for a button, picture or image map (typically a GIF or JPG file). CATSWeb looks for the file in its graphics subdirectory, or in an alternate graphics subdirectory if specified in the user's current Interface Preference.

Help Text - The text that a user sees when they float their mouse over a graphic image. Web developers often refer to this as Alternative Text or just "Alt Text". The Help Text is displayed in the same way as the Description for field definitions.

Horizontal Alignment - Specifies the horizontal alignment (Left, Center or Right) for the contents within the window, pane or other container. When a Display Part is being used in a Dashboard or within the body of an Issue/Action/Subtask form, the horizontal alignment for the Display Part as a whole is controlled by the Horizontal Alignment setting of the Fixed Text Area it appears within. Display Parts that appear in the subform region of Issue/Action/Subtask forms are automatically centered.

(Image) Height/Width - The height and width of an image (graphics) file in pixels. When the settings are not mandatory in a display part form, they can typically be omitted with no adverse effects.

Ignore Context Error - If checked, data source errors are ignored when the display part is used in a context in which the data source is invalid. The No Data Message (if any) will be displayed instead.

For example, if a meter display part using a Containing Record data source is placed on an Issue/Action/Subtask form, the data source will be invalid when the form first opens in Add mode. If the display part is visible on add, and Ignore Context Error is not checked, an error message will be displayed in place of the meter. Checking this setting will cause the No Data Error message to be displayed instead (or nothing at all to be displayed if the No Data Error message is blank).

(Include) Legend - This setting determines if a color-coding data legend is shown above initial or drill down data in a Contents or Data pane, when the data comes from a saved filter, hot list or other data source that offers legends.

Include Management Links - When the data source type is Tagged Records, this setting determines if the tag deletion and management links are included in the visible table of tagged records.

Line Break after Caption - This setting applies to Display Parts that display selection lists. It determines whether or not a line break is inserted between the list caption and the actual selection list.

Links in Data (section) - Present in Display Parts that can display data, this section is used in the same way as the Optional Links in Results section of the Drill Down form. If the data is from saved queries or filters, you do not need to define links for the record key fields (ActionID, SubtaskID, etc.) since CATSWeb provides these links automatically.

List Rows - This setting is present in System List display parts and can be used to specify the number of visible rows in a list when a multi-select list is appropriate (ex: the Tags list types). The setting is ignored for lists where it is not appropriate (ex: the Change Department list). A value of 0 or 1 will cause a standard pull-down list to be displayed, larger values will cause a multi-select list to be displayed.

Max Items - Limits the number of items that are displayed in the Display Part. For example, if the Display Part is displaying items from a saved query that returns 1,714 rows, this setting can be used to limit the display to the top 20. The View All Items Link setting may be used to provide a way for the user to view all the rows.

Min Width (pixels) - This setting applies to windows or window panes, and allows the minimum width of the pane or window to be set (specified in pixels). The value 0 (zero) means there is no minimum width, and the window or pane will shrink as needed to fit its current contents.

No Data Message (section) - Present in Display Parts that use or display data, this section allows for an optional message to be displayed when the data source returns no data, or experiences a context error when Ignore Context Error is enabled.

Number of Spacers - The quantity of element spacers used between elements in a Display Part.

Pane Position - This setting allows the position of one window pane to be specified relative to another window pane. For example, the Pane Position setting in the Image Pane section of the Image Map Viewer configuration form provides options of Left of Contents Pane and Above Contents Pane. If the image map graphic is wide and short, the Above Contents Pane option is preferable, while Left of Contents Pane is preferable for images that are narrow and tall.

Parameter1-10 (Optional Parameters Section) - These optional parameters may be used to provide parameter values for stored procedure or URL data links, or used for any other purpose. The corresponding table field names for these fields are Memo031-Memo040, and the table field value can be read via Tool Tip Help for each parameter.

Persist Dashboard Change - This setting causes a Go To Dashboard or View Dashboard button, link, region or folder to set the destination dashboard as the user's Home page for the remainder of their session. After the user's session ends and they begin a new one, their home page preference will revert to what it was previously.

When the setting is present in the Window Buttons section of a form, it applies to any window buttons that use the Go To Dashboard option. When present in the Contents or Destination section, it applies when the destination is a public dashboard.

Query Parameter Replacements - A delimited string of QueryFieldName=ContainerFieldName pairs, with multiple pairs separated by a pair of pipe characters ("||"). This allows parameters (query field values) in saved queries and filters to be replaced with values from the Display Part configuration record, or from the record that is containing the Display Part, such as an Issue/Action/Subtask record. For example, this Query Parameter Replacement can be used in Display Parts that are contained in Action forms:

ParentID=ActionID||Title=Title

It retrieves the ActionID and Title field values from the Action record that is being displayed, and uses those values for the ParentID and Title parameters in the saved query or filter that is providing the data for the Display Part.

Query Template - Determines whether or not the Display Part appears in the Template list within the Query Chart or Indicator section of query forms. See also these guidelines for managing Query Chart and Indicator templates.

Region ID - A unique ID that CATSWeb automatically assigns to each region in an Image Map Viewer or Image Map Navigator display part.

Region Type - The type of region being defined in an Image Map: Circle, Rectangle or Polygon. The region type determines how the Coordinates are specified.

Replacements - Used in an Ad Hoc HTML display part, this is a delimited string of TextToReplace=ContainerFieldName pairs, with multiple pairs separated by a pair of pipe characters ("||"). This allows text or HTML in the contents to be replaced with values from the Display Part configuration record, or from the record that is containing the Display Part, such as an Issue/Action/Subtask record. For example, this Replacement can be used in Display Parts that are contained in Action forms:

YYY=ActionID||ZZZ=Title

It retrieves the ActionID and Title field values from the Action record that is being displayed, and uses those values to replace all occurrences of "YYY" and "ZZZ" in the contents. This Replacement may be used for any Ad Hoc HTML Display Part, since it uses values from the Display Part's optional parameters:

MyZIPCodePlaceholder=Memo031||MyCityNamePlaceholder=Memo032

Standard tokens (variables) such as "{My Name}" may be specified directly in the Contents.

Secondary Data Source - If a Display Part uses a Data Link to provide its primary contents, a secondary data source selection may be available. A secondary data source is only available to the Data Link when the Display Part is used in a Dashboard. The secondary data source will not work when a Display Part is used in a CATSWeb form (Issue, Action, Subtask, etc.).

If a secondary data source is specified, CATSWeb will use the following process to generate the Display Part:

Retrieves a recordset of data from the secondary data source.
Passes the recordset to the primary data link as the rsParams recordset.
Receives the data or HTML returned from the primary data link and uses it as the contents of the Display Part.

In this sequence, the secondary data source is being used as a convenience for the primary data link, to allow CATSWeb to perform the "heavy lifting" associated with retrieving preliminary data it wishes to process.

SQL - The SQL statement that provides data for the Display Part when the Data Source Type is SQL. The SQL may use tokens or field value replacements as described here. Named values from Display Part Parameters or or the Display Part's configuration record may also be substituted into the SQL at runtime using the same tilde-delimited technique (~MyDisplayPartParameterName~).

Subcomponent Type - The type of Display Part (read-only).

Subscribe Link - If the Subscriptions feature is installed, and the Display Part is of a type that can be subscribed to, this setting will be present and allows you to choose an option for the Subscribe link. This link will appear near the bottom of the Display Part. In Container means that the link is present when the Display Part is rendered in a Dashboard, record or other container. The other options are self-explanatory.

Subtitle - The visible subtitle of the Display Part. If specified, this is displayed above the Display Part and below the Title using Page Subtitle formatting when the Display Part is viewed as a full page, or displayed using General Text formatting when the Display Part is contained in a Dashboard or placed on an Issue/Action/Subtask form.

Tags - When the data source type is Tagged Records, this setting is used to specify the tags. A single tag may be specified, or many tags may be specified as a comma-delimited list (ex: "Tag 1, Tag 2, Tag 3").

Text Style - The style used for captions, links or other text in the Display Part. The choices correspond to sections in the current Interface Preference.

Title - The visible title of the Display Part. If specified, this is displayed above the Display Part using Page Title formatting when the Display Part is viewed as a full page, or displayed using Page Subtitle formatting when the Display Part is contained in a Dashboard or placed on an Issue/Action/Subtask form.

Use Advanced Settings - This setting applies to Display Parts that display selection lists, and allows custom list bindings to be specified for the lists. Click the iconic reload button after changing the setting. When Advanced Settings are not enabled, CATSWeb will generate the same standard lists that would normally be present on the Home page, Query Menu page, My CATSWeb page, etc. These lists will be filtered based on the user's current permissions, and the filtering will automatically accommodate Personality changes.

When Advanced Settings are enabled, you may specify two sources for each list: one that applies immediately after a user logs in and up to the time that they make a Personality change, and the other that applies from the time of the first Personality change until the end of their session. You may specify the same source for each case if the list contents do not need to vary following a Personality change. You may also choose to leave either of the list sources blank, and CATSWeb will use its standard list, just as if Advanced Settings were not enabled.

Vertical Alignment - Specifies the vertical alignment (Top, Center or Bottom) for the contents within the window, pane or other container. When a Display Part is being used in a Dashboard or Issue/Action/Subtask form, the vertical alignment for the Display Part as a whole is controlled by the Vertical Alignment setting of the Fixed Text Area it appears within.

View All Items Link - When a Display Part is displaying a collection or listing of items that have been limited by a Max Items setting in the Display Part, this setting determines whether or not a View All Items link is provided with the Display Part. If a user clicks this link, the Max Items setting will be ignored and the user will see all available items.

View Full Page Link - When a Display Part is being viewed in a container (Dashboard, form, etc.) and not on a full page, this setting determines whether or not a link to a full page view is provided with the Display Part.

Window Buttons (section) - This section is available for Display Parts that are rendered in a window format, such as Image Map Viewers and Virtual Folders. The section provides configuration parameters for a set of optional Window Buttons that may be configured to perform any functionality you wish. The section is configured in a manner similar to Buttons and Links display parts, and may also include the following settings:

Button Type - Choose to use graphic buttons or text links for all buttons. Click the iconic reload button after making your selection.

Position - Window buttons may be positioned along the top or bottom of the window, or in both locations.