Presentation > customization > Sorting Rule

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`
`minVersion: 2.0.2`

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`
`false`

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`
`isPolymorphic: false`

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`
`sortAscending: false`

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`
`minVersion: 2.0.2`

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`
`false`

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`
`isPolymorphic: false`

Last Updated: 24 January, 2023

Sorting rule

Property sorting rule

Attributes

Attribute: requiredSchemas

Attribute: priority

Attribute: condition

Attribute: class

Attribute: isPolymorphic

Attribute: propertyName

Attribute: sortAscending

Disabled sorting rule

Attributes

Attribute: requiredSchemas

Attribute: priority

Attribute: condition

Attribute: class

Attribute: isPolymorphic

Attribute: `requiredSchemas`

Attribute: `priority`

Attribute: `condition`

Attribute: `class`

Attribute: `isPolymorphic`

Attribute: `propertyName`

Attribute: `sortAscending`

Attribute: `requiredSchemas`

Attribute: `priority`

Attribute: `condition`

Attribute: `class`

Attribute: `isPolymorphic`