Tools

Each app can consist of multiple tools, which each have specific capabilities. Tools have a configuration which the displayer uses in creating what the user sees. Each tool can have multiple views.

AtomTool

An AtomTool is used to display data from the data_source releases you have created.

Attributes:

• type: “AtomTool”
• id: A unique id to identify this tool.
• title: The name for this tool that will be displayed to users.
• views: An array of views.
• initial_view: The id of the view that should be shown initially.

View types are AtomList and AtomDetail.

AtomList view

This is the primary way to display data, and can be thought of as a view for multiple columns of a data_source. It presents information on many items of one type. For instance, it can show info on many products, OR many people, but it can’t show info on many products AND people.

The initial view for this is a list view, and can be thought of as a column in the dataset.

The list view may only use fields from the primary data_source. The detail view may use fields from other data_sources.

Attributes

• data_source: Deprecated in v1.4.0. Use data_sources instead.
• data_sources: An array of data source definitions. Data sources in tools
• id: A unique id to identify this view.
• title: The name for this view that will be shown to users. If this is a field attribute, the value from the first row returned from the server will be used.
• type: “AtomList”
• item_title: The id of the attribute in data_source where the name of the item can be found.
• item_subtitle: The id of the attribute in data_source where secondary information on the item can be found. To hide the subtitle, set a static value to false.
• summary_metrics: An array of metrics to be shown on the list of all items. Not all metrics are available within the summary view. This will be shown as stacked if possible. If there is not room (no subtitle) or if there are more than 2 metrics, this will switch to a cycle view.
• detail_metrics: An array of metrics to be shown on the detail page for one item. All metrics are available in this view.
• detail_action: An object defining a custom action instead of a detail page.
• summary_config: An object defining additional configurations for the summary view.

Summary metrics

In the list view, it can be useful to show a few high level stats. This allows users to see some info at a glance without navigating to a detail page, as well as compare values across Atoms.

There are 2 view modes- static and cycle. The view mode is determined implicitly by your content. Static is the simplest, and simply shows one or two metrics without any interaction.

If the display is unable to fit all the metrics on the screen at once, users will be able to tap to cycle through. This can happen in several scenarios-

• You have more than one metric, and no subtitle
• You have more than 2 metrics
• You use the displaySummaryStack metric type

The following metric types are supported: numberAbsolute, numberCurrency, numberRelative, textShort. In addition, there is a summary specific display type, displaySummaryStack.

Summary config

Added in v1.9.0.

• view.summary_config.item_title.title - an attribute specifying the column header for the title. Only shown in Sightglass Browser.
• view.summary_config.item_subtitle.title - an attribute specifying the column header for the subtitle. Only shown in Sightglass Browser.

If the type for either is field, the value for that field in the first row will be used.

Example:

    "summary_config": {
      "item_title": {
          "title": {
            "type": "static",
            "value": "Title Header"
          }
      },
      "item_subtitle": {
        "title": {
          "type": "static",
          "value": "Subtitle Header"
        }
      }
    }

Detail action

Added in v1.4.0.

By default, selecting a list item takes you to a detail view for that item. This detail view shows the metrics listed in detail_metrics. However, sometimes you may need more control over what is shown, or you may want to go directly to another AtomList. In that case, you can use a detail_action.

Supported actions are link-external, link-new-view. Context will be taken from the attributes for that row in the data_source.

Example:

    "detail_action": {
      "type": "link-new-view",
      "view": {
        "type": "static",
        "value": "company_list"
      },
      "context": [
        {
          "type": "field",
          "field": "country",
          "name": "country"
        }
      ]
    }

Atom Detail view

This is a highly configurable view that displays a single atom of information, and can be thought of as a single row in a dataset, similar to the detail page in an Atom List.

It can be used as a summary page for a solution, or as a recursive drill down tool for your data.

Linking between views is possible using actions.

Attributes

• id: A unique id to identify this view.
• type: “AtomDetail”
• title: The name for this view that will be displayed to users. This is an attribute, and can be a field or static.
• metrics: An array of metrics to be displayed to the user.
• data_sources: An array of data source definitions. Data sources in tools

AtomTool view configuration options

These options can be set on a per-view basis.

List options

Search, filter, and sort options are all customizable based on the config of the AtomTool.

• Filters
• Default filters
• Display filters
• Sort
• Default sort
• Search
• Limit

Updated at display

view.updated_at_display = {}

It can often be useful for users to know how current data is. You can configure each view to display when the view’s sources were last updated.

Configurations for the updated_at_display object-

updated_source - Define where to get the updated time from. Options are:

• primary - Show the time when the primary data_source for this view was updated. This is the only supported option for AtomLists.
• last_updated - If you have multiple data_sources, show the last time any of the data_sources for this view was updated.
• data_source_ref - Specify a specific data_source used by this view to always get the time from. You must specify this in a data_source_ref attribute.
• attribute - Use a value in one of the view’s data_sources. You must specify this in an attribute attribute.
• none - Don’t show the updated information.

data_source_ref - The id of the data_source to show the updated at time.

• attribute - A static or field attribute referring to an attributes in one of the view’s data_sources. The value must be an ISO 8601 date string, for instance “2018-06-14T17:21:10.867Z”.

  • For AtomList views, this will use the attribute value from the first row. To ensure this works with any sort or filtering, you should have the value on each row in the data_source.
  • For AtomDetail views, you can refer to any data_source by adding a data_source field to the attribute. If one is not defined, it will default to the primary data_source.

format - Set to absolute to show the time and date. Set to relative to show the time since the last update. Default is absolute.

Currently, only static attributes are supported. The updated time is the time when the current data_source release was created.

Example:

    "updated_at_display": {
      "updated_source": {
        "type": "static",
        "value": "data_source_ref"
      },
      "data_source_ref": {
        "type": "static",
        "value": "foo"
      },
      "format": {
        "type": "static",
        "value": "relative"
      }
    }

This will show the time elapsed since the data_source foo was last updated.

Example:

    "updated_at_display": {
      "updated_source": {
        "type": "static",
        "value": "attribute"
      },
      "attribute": {
        "type": "field",
        "field": "updated_time",
        "data_source": "view_metadata"
      },
      "format": {
        "type": "static",
        "value": "absolute"
      }
    }

This will show the time and date using the field updated_time from the data_source view_metadata.

View Titles and Subtitles

tool.view.title = {} tool.view.subtitle = {}

There are two types of titles that you can define- a tool title and a view title.

If there are multiple tools in your solution, and your solution has a tab layout that shows the title, the tool title will appear at the bottom of the screen as a tab. The tool title must be a static attribute.

Each view may also specify a view title, which will be shown at the top of the screen in the navigation bar.

Static Tool Title example:

    {
      "title": {
        "type": "static",
        "value": "Dashboard"
      },
      "type": "AtomTool",
      "initial_view": "overview"
      "views": {
        "overview": {
          "id": "overview",
          "type": "AtomList",
          "title": {
            "type": "static",
            "value": "Overview"
          },
          "subtitle": {
            "type": "static",
            "value": "Additional context"
          }
          ...
        }
      }
    }

This tool will have a tab called “Dashboard”. The title at the top will be “Overview”, and underneath the title will be a smaller subtitle “Additional context”.

Field Tool Title example:

    {
      "title": {
        "type": "static",
        "value": "Dashboard"
      },
      "type": "AtomTool",
      "initial_view": "overview"
      "views": {
        "overview": {
          "id": "overview",
          "type": "AtomList",
          "title": {
            "type": "field",
            "field": "country_name"
          }
          ...
        }
      }
    }

This tool will have a tab called “Dashboard”. The title at the top will be the value of field “country_name”. Because it is an AtomList view, this value will be taken from the first row returned from the primary data source. Note that any filters, sorts or searches will impact this, so it’s strongly encouraged that you set the field to a value that is the same for every row that may be returned given your view configuration.

You can not directly use filter values or link context values as the title. However, if you are filtering on those values, those values will be included in the returned data, and can be used as the title.

Additional Subtitle info

Subtitles are available on AtomList and AtomDetail views, but they are not supported on the secondary detail page of an AtomList, as defined by the detail_metrics.

View Info

view.info = { type: 'static', value: 'Info'}

To add a small amount of additional info to a view, for instance legal info, or a short description, you can add info to a specific view. This will show an Info icon which will open a modal with the information and a single button to close the modal.

Only static values are allowed.

The following HTML markup is allowed- b, i, em, strong, sup.

This is available on AtomList and AtomDetail views, but is not supported on the secondary detail page of an AtomList, as defined by the detail_metrics.

View Data Download

view.download = {}

On an AtomList view, you have the option to allows users to download the backing data. There are a few limitations to this:

• This is is only enabled for Sightglass Browser users.
• It is only available on AtomList views.
• It does not support joining, so only allows users to download from the single primary data_source that backs the AtomList.

Properties:

• allow: A boolean to specify whether users can download the data from this view. Defaults to false, so this must be enabled per view.
• fields: An array of attributes from the data_source that the user can download. If not specified, all attributes will be downloaded. This should be curated to ensure unhelpful fields such as sentiment or other Sightglass metadata are not included.

Example:

    ...
    "download": {
      "allow": true,
      "fields": ["name", "country", "sector"]
    }
    ...

Insights

Insights are a list of key understandings that come from our data. They should be timely and actionable. No configuration is needed for this to be displayed in the app.

Example:

    {
      "id": "insights",
      "title": {"type": "static", "value": "Insights"},
      "type": "Insights"
    }

More info on Creating insights.

Configuration

Most app display logic will be contained within one display. You may apply some settings across multiple tools using a config object.

Add a tool_config attribute at the top level of your app config.

Global filters

root.tool_config.global_filters = []

If the same filter should be applied to multiple tool displays, you can add a Global Filter.

Tool order

root.tool_config.tool_order = []

Set the order the tools are shown in by adding a tool_order array to the tool_config.

Tools that are not listed in the array will not be shown. This can be useful for not showing a tool that is a work in progress.

To provide consistency, Insights should always be the last tool in the list, so it is the right most tab.

Example:

    "tool_order": [
      "overview",
      "detail",
      "insights"
    ]

Tool tab configuration

Tab layout

root.tool_config.tabLayout = {}

Each tool has a tab in the app. By default, this shows the name of the tool. To change it, you can add a tab_config object to the tool.

One of title_and_icon|title|icon. Defaults to title.

Example:

    "tabLayout": {
      "type": "static",
      "value": "title_and_icon"
    }

Tool icon

tool.tab_config.icon = {}

If the tab layout for a solution is title_and_icon or icon, each tool must have an icon.

Example:

    "tool_config": {
      "icon": {
        "type": "static",
        "value": "circle"
      }
    }