Presentation › customization › Sorting Rule
Edit this page

Sorting rule

TypeScript type: SortingRule.

Sorting rules provide a way to either disable sorting or sort instances by specific properties. There are 2 types of sorting rules for both of these scenarios.

Property sorting rule

Rule to configure sorting for certain ECInstances in the hierarchy and/or content. It is possible to configure different sorting for different types of ECInstances.

Multiple sorting rules may be applied for the same instances - in this case the instances are first sorted by the highest priority rule and then the lower priority ones.

Note: This rule is not meant to be used to sort grouping nodes, custom nodes or other non ECInstance type of nodes.

Attributes

Name Required? Type Default
Filtering
requiredSchemas No RequiredSchemaSpecification[] []
priority No number 1000
condition No ECExpression ""
class No SingleSchemaClassSpecification All classes in current context
isPolymorphic No boolean false
Sorting
propertyName Yes string
sortAscending No boolean true

Attribute: requiredSchemas

A list of ECSchema requirements that need to be met for the rule to be used.

Type RequiredSchemaSpecification[]
Is Required No
Default Value [] 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there is a customization rule to sort
// instances by `Pitch` property. Sorting rule requires `BisCore` schema to be higher than 1.0.2.
// If this requirement is not met sorting rule does not take effect.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
      propertyName: "Pitch",
    },
  ],
};
Result
minVersion: 1.0.2 Example of using required schemas condition
minVersion: 2.0.2 Example of using required schemas condition

Attribute: priority

Defines the order in which rules are handled - higher priority means the rule is handled first. If priorities are equal, the rules are handled in the order they're defined.

Type number
Is Required No
Default Value 1000 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are two customization rules to sort
// instances by `Roll` and `Pitch` properties. The rules have different priorities and higher priority
// rule is handled first.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      priority: 1,
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      propertyName: "Roll",
    },
    {
      ruleType: "PropertySorting",
      priority: 2,
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      propertyName: "Pitch",
    },
  ],
};

Example of using priority attribute

Attribute: condition

Defines a condition which needs to be met in order for the rule to be used. The condition is an ECExpression which has to evaluate to a boolean value.

Type ECExpression
Is Required No
Default Value "" 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// instances by `Pitch` property.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      condition: "TRUE",
      propertyName: "Pitch",
    },
  ],
};
Condition evaluation result Result
true Example of using rule condition
false Example of using rule condition

Attribute: class

Specifies ECClass whose ECInstances should be sorted.

Type SingleSchemaClassSpecification
Is Required No
Default value All classes in current context 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// `bis.SpatialViewDefinition` instances by `Pitch` property
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      propertyName: "Pitch",
    },
  ],
};

Example of using class attribute

Attribute: isPolymorphic

Specifies that class attribute defined in this rule should be handled polymorphically.

Type boolean
Is Required No
Default Value false 
// This ruleset lists `bis.SpatialViewDefinition` instances with their `Roll` and `Pitch` properties as instance
// labels. Sorting rule targets `bis.ViewDefinition3d`, the base class of `bis.SpatialViewDefinition`, so to
// sort instances of the derived classes, `isPolymorphic` attribute needs to be `true`.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      class: { schemaName: "BisCore", className: "ViewDefinition3d" },
      isPolymorphic: true,
      propertyName: "Pitch",
    },
  ],
};
Result
isPolymorphic: true Example of using isPolymorphic attribute
isPolymorphic: false Example of using isPolymorphic attribute

Attribute: propertyName

Specifies name of the property which should be used for sorting.

Type string
Is Required Yes 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// instances of any class by `Pitch` property.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      propertyName: "Pitch",
    },
  ],
};

Example of using propertyName attribute

Attribute: sortAscending

Specifies whether instances should be sorted in ascending order or descending.

Type boolean
Is Required No
Default Value true 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// instances by `Pitch` property in descending order
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      propertyName: "Pitch",
      sortAscending: false,
    },
  ],
};
Result
sortAscending: true Example of using isPolymorphic attribute
sortAscending: false Example of using isPolymorphic attribute

Disabled sorting rule

Rule to disable sorting for certain ECInstances in the hierarchy and/or content.

Note: Disabling sorting increases performance

Attributes

Name Required? Type Default
Filtering
requiredSchemas No RequiredSchemaSpecification[] []
priority No number 1000
condition No ECExpression ""
class No SingleSchemaClassSpecification All classes in current context
isPolymorphic No boolean false

Attribute: requiredSchemas

A list of ECSchema requirements that need to be met for the rule to be used.

Type RequiredSchemaSpecification[]
Is Required No
Default Value [] 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there is a customization rule to sort
// instances by `Pitch` property. Sorting rule requires `BisCore` schema to be higher than 1.0.2.
// If this requirement is not met sorting rule does not take effect.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
      propertyName: "Pitch",
    },
  ],
};
Result
minVersion: 1.0.2 Example of using required schemas condition
minVersion: 2.0.2 Example of using required schemas condition

Attribute: priority

Defines the order in which rules are handled - higher priority means the rule is handled first. If priorities are equal, the rules are handled in the order they're defined.

Type number
Is Required No
Default Value 1000 
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are two customization rules to sort
// instances by `Roll` property and to disable `bis.SpatialViewDefinition` instances sorting.
// The disabled sorting rule has higher priority and it is handled first.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " x ",
          parts: [{ spec: { specType: "Property", propertyName: "Roll" } }, { spec: { specType: "Property", propertyName: "Pitch" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      priority: 1,
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      propertyName: "Pitch",
    },
    {
      ruleType: "DisabledSorting",
      priority: 2,
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    },
  ],
};

Example of using priority attribute

Attribute: condition

Defines a condition which needs to be met in order for the rule to be used. The condition is an ECExpression which has to evaluate to a boolean value.

Type ECExpression
Is Required No
Default Value "" 
// The ruleset has root node rule that returns `bis.ViewDefinition` instances with labels
// consisting of `CodeValue` property value. Also there are customization rule to disable
// instances sorting.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "ViewDefinition" },
      values: [
        {
          specType: "Property",
          propertyName: "CodeValue",
        },
      ],
    },
    {
      ruleType: "DisabledSorting",
      condition: "TRUE",
    },
  ],
};
Condition evaluation result Result
true Example of using rule condition
false Example of using rule condition

Attribute: class

Specifies ECClass whose instances should not be sorted.

Type SingleSchemaClassSpecification
Is Required No
Default value All classes in current context 
// The ruleset has root node rule that returns `bis.ViewDefinition` instances with labels
// consisting of class name and `CodeValue` property value. Also there two are customization rules to sort
// instances by `CodeValue` property and to disable `bis.SpatialViewDefinition` instances sorting.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "ViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " - ",
          parts: [{ spec: { specType: "ClassName" } }, { spec: { specType: "Property", propertyName: "CodeValue" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      priority: 1,
      class: { schemaName: "BisCore", className: "ViewDefinition" },
      propertyName: "CodeValue",
      isPolymorphic: true,
    },
    {
      ruleType: "DisabledSorting",
      priority: 2,
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    },
  ],
};

Example of using class attribute

Attribute: isPolymorphic

Specifies that class attribute defined in this rule should be handled polymorphically.

Type boolean
Is Required No
Default Value false 
// The ruleset has root node rule that returns `bis.ViewDefinition` instances with labels
// consisting of class name and `CodeValue` property value. Also there are two customization rules to sort
// instances by `CodeValue` property and to disable `bis.ViewDefinition2d` instances sorting polymorphically.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "ViewDefinition" },
      values: [
        {
          specType: "Composite",
          separator: " - ",
          parts: [{ spec: { specType: "ClassName" } }, { spec: { specType: "Property", propertyName: "CodeValue" } }],
        },
      ],
    },
    {
      ruleType: "PropertySorting",
      priority: 1,
      class: { schemaName: "BisCore", className: "ViewDefinition" },
      propertyName: "CodeValue",
      isPolymorphic: true,
    },
    {
      ruleType: "DisabledSorting",
      priority: 2,
      class: { schemaName: "BisCore", className: "ViewDefinition2d" },
      isPolymorphic: true,
    },
  ],
};
Result
isPolymorphic: true Example of using isPolymorphic attribute
isPolymorphic: false Example of using isPolymorphic attribute

Last Updated: 03 April, 2024