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

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.

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
  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
  DISPLAY_CATEGORIES = false DISPLAY_MODELS = true
  DISPLAY_CATEGORIES = true DISPLAY_MODELS = true

Attribute: requiredSchemas

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

// 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.

// 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,
    }],
  }],
};

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.

// 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,
    }],
  }],
};

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:

• Selected node instances specification returns properties of the input instance.
• Content instances of specific classes specification returns properties of instances of given classes. The returned content doesn't depend on the input.
• Content related instances specification returns properties of instances that are related to input instances through given relationship(s).

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.

Last Updated: 20 June, 2023