Presentation > content > Property Category Specification
Edit this page

Property category specification

TypeScript type: PropertyCategorySpecification.

Content modifier for defining custom property categories. Custom categories are not present in the result unless they contain at least one property. One way to assign a property to the category is by using property overrides.

See property categorization page for more details.

Attributes

Name Required? Type Default
id Yes string
parentId No string | CategoryIdentifier
label Yes string
description No string ""
priority No number 1000
autoExpand No boolean false
renderer No RendererSpecification undefined

Attribute: id

Category identifier used to reference the category definition from property overrides or other category definitions. The identifier has to be unique within the list of category definitions where this specification is used.

Type string
Is Required Yes 
// There's a content rule for returning content of given `bis.Subject` instance. The rule contains a custom
// category specification that is referenced by properties override, putting all properties into the
// "Custom" category.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyCategories: [{
        id: "custom-category",
        label: "Custom",
      }],
      propertyOverrides: [{
        name: "*",
        categoryId: "custom-category",
      }],
    }],
  }],
};

Example of referencing category by "id"

Attribute: parentId

Identifier of a parent category. When specifying the parent category by ID, it has to be available in the scope of this category definition.

Type string | CategoryIdentifier
Is Required No
Default Value No parent 
// There's a content rule for returning content of given `bis.Subject` instance. In addition, it
// puts all properties into a custom category with "Nested Category" label which in turn is put into "Root Category".
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyCategories: [{
        id: "root-category",
        label: "Root Category",
      }, {
        id: "nested-category",
        parentId: "root-category",
        label: "Nested Category",
      }],
      propertyOverrides: [{
        name: "*",
        categoryId: "nested-category",
      }],
    }],
  }],
};

Example of using "parent id" attribute

Attribute: label

Display label of the category. May be localized.

Type string
Is Required Yes 
// There's a content rule for returning content of given `bis.Subject` instance. In addition,
// it puts all properties into a custom category with "Custom Category" label.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyCategories: [{
        id: "custom-category",
        label: "Custom Category",
      }],
      propertyOverrides: [{
        name: "*",
        categoryId: "custom-category",
      }],
    }],
  }],
};

Example of using "label" attribute

Attribute: description

Extensive description of the category. The description is assigned to the category object that's set on content fields and it's up to UI component to decide how the description is displayed.

Type string
Is Required No
Default Value "" 
// There's a content rule for returning content of given `bis.Subject` instance. In addition, it puts
// all properties into a custom category with a description.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyCategories: [{
        id: "custom-category",
        label: "Custom Category",
        description: "Lorem Ipsum is simply dummy text of the printing and typesetting industry.",
      }],
      propertyOverrides: [{
        name: "*",
        categoryId: "custom-category",
      }],
    }],
  }],
};

// Ensure category description is assigned
const content = (await Presentation.presentation.getContent({
  imodel,
  rulesetOrId: ruleset,
  keys: new KeySet([{ className: "BisCore:Subject", id: "0x1" }]),
  descriptor: {},
}))!;
expect(content.descriptor.categories).to.containSubset([{
  label: "Custom Category",
  description: "Lorem Ipsum is simply dummy text of the printing and typesetting industry.",
}]);

Attribute: priority

Assign a custom CategoryDescription.priority to the category. It's up to the UI component to make sure that priority is respected - categories with higher priority should appear before or above categories with lower priority.

Type number
Is Required No
Default Value 1000 
// There's a content rule for returning content of given `bis.Subject` instance. The produced content
// is customized to put `CodeValue` property into "Category A" category and `UserLabel` property into
// "Category B" category. Both categories are assigned custom priorities.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyOverrides: [{
        name: "CodeValue",
        categoryId: "category-a",
      }, {
        name: "UserLabel",
        categoryId: "category-b",
      }],
      propertyCategories: [{
        id: "category-a",
        label: "Category A",
        priority: 1,
      }, {
        id: "category-b",
        label: "Category B",
        priority: 2,
      }],
    }],
  }],
};

// Ensure that correct category priorities are assigned
const content = (await Presentation.presentation.getContent({
  imodel,
  rulesetOrId: ruleset,
  keys: new KeySet([{ className: "BisCore:Subject", id: "0x1" }]),
  descriptor: {},
}))!;
expect(content.descriptor.fields).to.containSubset([{
  label: "Code",
  category: {
    label: "Category A",
    priority: 1,
  },
}]);
expect(content.descriptor.fields).to.containSubset([{
  label: "User Label",
  category: {
    label: "Category B",
    priority: 2,
  },
}]);

Example of using "priority" attribute

Attribute: autoExpand

Controls the value of CategoryDescription.expand which tells the UI component displaying the category to auto-expand the category.

Type boolean
Is Required No
Default Value false 
// There's a content rule for returning content of given `bis.Subject` instance. The produced content
// is customized to put all properties into a custom category which has the `autoExpand` flag.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyOverrides: [{
        name: "*",
        categoryId: "custom-category",
      }],
      propertyCategories: [{
        id: "custom-category",
        label: "Custom Category",
        autoExpand: true,
      }],
    }],
  }],
};

// Ensure that categories have the `expand` flag
const content = (await Presentation.presentation.getContent({
  imodel,
  rulesetOrId: ruleset,
  keys: new KeySet([{ className: "BisCore:Subject", id: "0x1" }]),
  descriptor: {},
}))!;
expect(content.descriptor.categories).to.containSubset([{
  label: "Custom Category",
  expand: true,
}]);
autoExpand: false autoExpand: true
Example of using "auto expand" attribute set to "false" Example of using "auto expand" attribute set to "true"

Attribute: renderer

Custom category renderer specification that allows assigning a custom category renderer to be used in UI. This specification is used to set up CategoryDescription.renderer for this category and it's up to the UI component to make sure appropriate renderer is used to render the category.

See Custom property category renderers page for information on how custom categories are handled in our UI components.

Type RendererSpecification
Is Required No
Default Value undefined 
// There's a content rule for returning content of given instance. The produced content
// is customized to put all properties into a custom category which uses a custom "my-category-renderer"
// renderer.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyOverrides: [{
        name: "*",
        categoryId: "custom-category",
      }],
      propertyCategories: [{
        id: "custom-category",
        label: "Custom Category",
        renderer: {
          rendererName: "my-category-renderer",
        },
      }],
    }],
  }],
};

// Ensure that categories have the `expand` flag
const content = (await Presentation.presentation.getContent({
  imodel,
  rulesetOrId: ruleset,
  keys: new KeySet([{ className: "BisCore:Subject", id: "0x1" }]),
  descriptor: {},
}))!;
expect(content.descriptor.categories).to.containSubset([{
  label: "Custom Category",
  renderer: {
    name: "my-category-renderer",
  },
}]);

Last Updated: 24 January, 2023