Extension 2.0 Screens - How to add filtering

[Radu]

Use case: Enabling filtering and filter bars to entity lists of screens created from an Extension 2.0 YAML.

Example context: I have an entity type "my:interface" that has a RUNS_ON relationship to an entity type "my:device". I have an Entities List card which already lists all "my:interface" entities I want to filter.

All definitions are given based on schema version 1.239 and may or may not change in the future.

Example 1: I want to filter my list by the interface names.
YAML definition:

filtering:
  entityFilters:
    - displayName: Interface
      filters:
        - type: entityName
          displayName: Name
          freeText: true
          modifier: contains
          defaultSearch: true
          distinct: false
          entityTypes:
            - my:interface

YAML explanation:

• filtering - the block which defines the filtering capability
• entityFilters - the block which defines the groups of filters (these are displayed slightly greyed out in the filtering list)
• filters - the actual filters that are part of this group
  
  • displayName - how this filter is labelled within the UI
    
  • type - must reference an attribute of the entity you are filtering. Note: every entity has entityName as a default attribute.
  • freeText - if true, the user can freely type text; otherwise they must select from a list of suggestions. Note: only default attributes such as entityName are capable of offering list of suggestions.
  • modifier - when freeText is true, this defines how the text should be matched against the attribute. When freeText is false, this must be omitted. Note: all non-default attributes must match as "equals" regardless of this option.
  • defaultSearch - when true, if the user starts typing without selecting a filter first, this filter will be selected by default. Only one filter within the filtering block may have this enabled.
  • distinct - when true, only one instance of this filter can be applied
  • entityTypes - A mandatory list of entity types that this filter applies to. If you omit this, your filtering bar will just show a spinning wheel because of the incomplete definition.

Example 2: Given example 1, I also want to filter by the device these interfaces are running on

YAML definition:

filtering:
  relationships:
    - type(my:device),toRelationships.runsOn($(entityConditions))
  entityFilters:
    - displayName: Interface
      filters:
        - type: entityName
          displayName: Name
          freeText: true
          modifier: contains
          defaultSearch: true
          distinct: false
          entityTypes:
            - my:interface
    - displayName: Related entity
      filters:
        - type: entityName
          displayName: Device name
          freeText: false
          defaultSearch: false
          distinct: true
          entityTypes:
            - my:device          

YAML Explanation:

Most of the definition is the same as above. Changes include:

• filters
  • entityTypes - For the second filter, this is now "my:device". This is because despite filtering a list of interfaces, the filter attribute belongs to devices.
• relationships
  • any entity that is not directly part of the entity list must have a relationship defined to the listed entity for it to be considered. $(entityConditions) here resolves to each of the "my:interface" entities.

[ChadTurner]

Great Tip @Radu