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

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

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

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.getContentIterator({
  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.getContentIterator({
  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,
    },
  },
]);

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.getContentIterator({
  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

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.getContentIterator({
  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",
    },
  },
]);