List options

Provide ways for users to interact with the data using these list options.

Filter options

Filters

view.filters = []

An array of objects that define the filters available to users. Filters can be predefined or options that a user can pick from.

Predefined filters

Predefined filters are “on or off” with no other options available to the user. These are useful for simpler fields like sentiment as well as for using your data analysis skills to define helpful views for the user.

Example:

    "filters": [{
      "id": "field_sentiment_negative",
      "name": "Negative field",
      "filter": {
        "field": "field_sentiment",
        "value": "negative"
      }
    }]

Enum filters

For more complex cases where a user should be able to pick between multiple possibilities, use an enum to define the options.

Example:

    "filters": [{
      "id": "field_options",
      "name": "Item",
      "filter": {
        "field": "field_name",
        "type": "enum",
        "values": [
          "Item A",
          "Item B",
          "Item C"
        ]
      }
    }]

“All” option for enum filters

You can also add an “All” option that will allow users to see other a subset of the data, or all rows. This only applies to AtomList tools, as AtomDetail tools or views will only show one row. This also does not aggregate rows for you- if you’d like an AtomDetail with an aggregated “All” option, you will need to aggregate it before creating the release, and add it as a row to the dataset.

You are encouraged to use “All” as the label, but you can use whatever makes the most sense for your data.

If there is no default filter value set for the filter, the default value will be set to the allLabel value. The allValue should not appear in the enum.

Example:

    "filters": [{
      "id": "field_options",
      "name": "Item",
      "filter": {
        "field": "field_name",
        "type": "enum",
        "allLabel": "All",
        "values": [
          "Item A",
          "Item B",
          "Item C"
        ]
      }
    }]

“Multiple” option for enum filters

You can also allow users to select multiple values from a single field. This will be applied as an “OR” statement, so any rows that match any of the items will be returned.

This is not compatible with the “All” filter option.

Example:

    "filters": [{
      "id": "field_options",
      "name": "Item",
      "filter": {
        "field": "field_name",
        "type": "enum",
        "multiple": true,
        "values": [
          "Item A",
          "Item B",
          "Item C"
        ]
      }
    }]

Distinct filters

You often will want the filter values that are displayed to a user to be the distinct set of options in a filter. You can do that with a distinct filter.

Global filters can not use this option, as it would require syncing across multiple data sources.

Example:

    "filters": [{
      "id": "field_options",
      "name": "Item",
      "filter": {
        "field": "field_name",
        "type": "distinct",
        "multiple": true
      }
    }]

This would create a multi-select filter that would have the unique set of values in the field field_name.

Global Filters

root.tool_config.global_filters = []

If a filter should stay in sync across multiple tools, you can define a global filter.

Global filters are required to have a default_value or an allLabel, or both.

In the tools config object, add an array with key global_filters.

Example:

    "global_filters": [
      {
        "id": "globalPhysicianFilter",
        "filter": {
          "type": "enum",
          "values": ["Value 1", "Value 2"]
        },
        "default_value": "Value 1",
        "allLabel": "All"
      }
    ]

Then, in each tool display where this filter should be applied, add a filter of type global.

• field refers to an attribute in the tool’s data source.
• filter_source is the id of the global filter it should use.

Example:

    {
      "id": "physician",
      "name": "Physician",
      "filter": {
        "type": "global",
        "field": "Physician",
        "filter_source": "globalPhysicianFilter"
      }
    }

Default filters

view.default_filters = []

This is an array of filter definitions that should be used when loading data initially. This filter should also exist in the filters field.

Key: default_filters

Example:

    "default_filters": [{
      "id": "physician",
      "name": "Physician",
      "filter": {
        "field": "Physician",
        "value": "Smith, Dana"
      }
    }],

Note that global filters require a default value to be set on the global filter directly.

Display filters

view.filter_display = []

When a list filter is crucial for understanding the data, you may want to show the filter value prominently in the display. For instance, if a dataset shows a breakdown of items by a person, you may wish to show the person’s name.

Key: filter_display

Takes an array of filter ids and link context names. If a value is set, the name and value will be displayed. This filter must be present in the default filters array.

Example:

    "filter_display": ["physician"]

Sort options

Sort

view.sorts = []

An array of sort definitions that should be available for this list. If this is not present, no sort options will be given to the user.

Key: sorts

Example:

    "sorts": [{
      "id": "total_desc",
      "field": "total",
      "direction": "DESC",
      "name": "Total High to Low"
    }]

Default sort

view.default_sort = []

An array of sort definitions that should be used when loading data initially or when no sort is selected. If this should be available as an option to users, it also needs to be defined in Sort.

Key: default_sort

Display sort

view.sort_display = boolean

On Atom List tools, show the active sort at the top of the list by setting sort_display to true.

In general, this option should be avoided. The default sort option should be intuitive enough that users can easily discern the sort. To accomplish this, the best practice is for the default sort to either be on the item title or on the first summary metric. If at all possible, avoid sorting on values that are not visible.

Search

view.search_fields = []

Key: search_fields

Provide an array of fields that will be exposed through search of the list. This should include any visible text fields on the summary view (title, subtitle), and may include other fields if search results from that field are desired and intuitive for the user.

If this is not present, no search capability will be given to the user.

Example:

    "search_fields": ["title","subtitle","alternate_title"]

Search Operators

Added in v1.7.0.

You can also specify that search should only match the beginning or end of a string on a per-field basis.

Instead of a string, supply an object with a field key and an op key.

Valid operators are:

• in - the default- will match if the term matches any part of the field
• startswith - will only match if the term matches the beginning of the field
• endswith - will only match if the term matches the end of the field

These can be mixed and matched. Example:

    "search_fields": ["title", {"field": "subtitle", "op": "startswith"}, {"field": "alternate_title", "op": "endswith"}]

If the user type “data”, this example will return Atoms where:

• the “title” field contains “data”, or
• the “subtitle” field starts with “data”, or
• the “alternate_title” field ends with “data”

Limit

view.limit = int

Key: limit

Integer. Sets the maximum number of rows that will be loaded from the dataset. If none is given, all rows matching sort and filter options will be shown.

Example:

    "limit": 20

Skip

view.skip = int

Key: skip

Integer. Sets a number of items that will always be skipped from a query. Use case: tool 1 shows top 10 using limit, tool 2 shows the rest.

Note that the items skipped will be sort-dependent.

Example:

    "skip": 20