Content rule

TypeScript type: ContentRule.

Content rules are used to define content that is displayed for specific type of input. Input consists of either ECInstances or nodes and to make things simpler everything is considered a node - instances get converted to ECInstance nodes (thus the SelectedNode symbol in condition ECExpression).

Attributes

Name Required? Type Default
Picking attributes
condition No ECExpression ""
requiredSchemas No RequiredSchemaSpecification[] []
priority No number 1000
onlyIfNotHandled No boolean false
Content attributes
specifications Yes ContentSpecification[]

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 most commonly used symbols are:

  • SelectedNode to define which type of input this rule is creating content for.

    // The ruleset has two content rules:
    // - the one for `bis.Element` returns content for input instances
    // - the one for `bis.Model` returns content for input model's contained elements
    const ruleset: Ruleset = {
      id: "example",
      rules: [{
        ruleType: "Content",
        condition: `SelectedNode.IsOfClass("Element", "BisCore")`,
        specifications: [{
          specType: "SelectedNodeInstances",
        }],
      }, {
        ruleType: "Content",
        condition: `SelectedNode.IsOfClass("Model", "BisCore")`,
        specifications: [{
          specType: "ContentRelatedInstances",
          relationshipPaths: [{
            relationship: { schemaName: "BisCore", className: "ModelContainsElements" },
            direction: "Forward",
          }],
        }],
      }],
    };
    
    Input instance Result
    bis.Element Example of using SelectedNode symbol in rule condition for bis.Element
    bis.Model Example of using SelectedNode symbol in rule condition for bis.Model
  • Ruleset variables to dynamically enable / disable the rule.

    // The ruleset has two content rules that return content for `bis.SpatialCategory` and `bis.GeometricModel` instances. Both
    // rules can be enabled or disabled with a ruleset variable.
    const ruleset: Ruleset = {
      id: "example",
      rules: [{
        ruleType: "Content",
        condition: `GetVariableBoolValue("DISPLAY_CATEGORIES")`,
        specifications: [{
          specType: "ContentInstancesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialCategory"] },
          handleInstancesPolymorphically: true,
        }],
      }, {
        ruleType: "Content",
        condition: `GetVariableBoolValue("DISPLAY_MODELS")`,
        specifications: [{
          specType: "ContentInstancesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel"] },
          handleInstancesPolymorphically: true,
        }],
      }],
    };
    
    Ruleset variable values Result
    DISPLAY_CATEGORIES = false
    DISPLAY_MODELS = false
    Example of using ruleset variables in rule condition
    DISPLAY_CATEGORIES = false
    DISPLAY_MODELS = true
    Example of using ruleset variables in rule condition
    DISPLAY_CATEGORIES = true
    DISPLAY_MODELS = true
    Example of using ruleset variables in rule condition

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 one content rule that returns content of `bis.ExternalSourceAspect` instances. The
// ECClass was introduced in BisCore version 1.0.2, so the rule needs a `requiredSchemas` attribute
// to only use the rule if the version meets the requirement.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
    specifications: [{
      specType: "ContentInstancesOfSpecificClasses",
      classes: [{
        schemaName: "BisCore",
        classNames: ["ExternalSourceAspect"],
      }],
    }],
  }],
};

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. The attribute may be especially useful when combined with onlyIfNotHandled attribute.

Type number
Is Required No
Default Value 1000
// The ruleset has two content rules that return content for `bis.SpatialCategory` and
// `bis.GeometricModel` respectively. The rules have different priorities and higher priority
// rule is handled first - it's content appears first.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    priority: 1,
    specifications: [{
      specType: "ContentInstancesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialCategory"] },
      handleInstancesPolymorphically: true,
    }],
  }, {
    ruleType: "Content",
    priority: 2,
    specifications: [{
      specType: "ContentInstancesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["GeometricModel"] },
      handleInstancesPolymorphically: true,
    }],
  }],
};

Example of using priority attribute

Attribute: onlyIfNotHandled

When true, the rule takes effect only when all other content rules with higher priority are ruled out. This attribute is most useful for defining fallback rules.

Type boolean
Is Required No
Default Value false
// The ruleset has two root node rules that return content for `bis.SpatialCategory` and
// `bis.GeometricModel` respectively. The `bis.SpatialCategory` rule has lower priority and `onlyIfNotHandled`
// attribute, which allows it to be overriden by higher priority rules.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    priority: 1,
    onlyIfNotHandled: true,
    specifications: [{
      specType: "ContentInstancesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialCategory"] },
      handleInstancesPolymorphically: true,
    }],
  }, {
    ruleType: "Content",
    priority: 2,
    specifications: [{
      specType: "ContentInstancesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["GeometricModel"] },
      handleInstancesPolymorphically: true,
    }],
  }],
};

Example of using onlyIfNotHandled attribute

Attribute: specifications

A list of content specifications that define what content is going to be returned. This is the most important attribute which is responsible for defining what instances' properties are included in the returned content. There are 4 types of specifications:

Multiple specifications can contribute to the resulting content by specifying multiple specifications in a single content rule or specifying multiple rules that match the same input.

Type ContentSpecification[]
Is Required Yes

Last Updated: 30 November, 2023