Presentation: Customization rules documentation improvement (#3267)

* Update StyleOverride rule docs

* Update LabelOverride rule docs

* Update ImageIdOverride rule docs

* Update CheckBoxRule docs

* Add way to customize tree node items in data provider

* Deprecated some customization rules and corresponding node properties

* Add learning snippets for customization rules

* Add example snippets for SortingRule attributes

* Add example snippets for InstanceLabelOverride rule attributes

* Add example snippets for ExtendedDataRule attributes

* Restructure customization rules docs index

* Deprecated Item.imageId property

* Add docs for ExtendedDataRule usage

* Cleanup ExtendedDataUsage docs

* Add example images

* Fix node order check in hierarchies test

* Add links to attributes table

* Deprecate showImages attribute

* Make types referenced comment into links

* Sort imports

* Commit missing snapshot

* Fix typo in ExtendedDataRule ruleset snippet

* Fix typo

* Update instance label override class attribute snippet

* Fix identation

* Remove unnecessary suggestion to use InstanceLabelOverride

* Add more links to extended data usage page

* Update callouts in example images

* Improve sorting rule required schemas example

* extract-api

* Fix typos

* Fix typo

* Fix ruleset description

* Add better examples for disabled sorting rule

* Remove remark

* Rush change

* Add illustrations for requiredSchemas attribute

* Improve condition result value column naming

* Add missing comma

* Fix test

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: saskliutas

common/api/presentation-common.api.md

@@ -141,7 +141,7 @@ export interface CategoryDescriptionJSON {
 // @public
 export type CategoryIdentifier = ParentCategoryIdentifier | RootCategoryIdentifier | IdCategoryIdentifier;
 
-// @public
+// @public @deprecated
 export interface CheckBoxRule extends RuleBase, ConditionContainer {
     condition?: string;
     defaultValue?: boolean;
@@ -270,6 +270,7 @@ export enum ContentFlags {
     KeysOnly = 1,
     MergeResults = 8,
     NoFields = 32,
+    // @deprecated
     ShowImages = 2,
     ShowLabels = 4
 }
@@ -363,6 +364,7 @@ export interface ContentSpecificationBase extends ContentModifiersList {
     onlyIfNotHandled?: boolean;
     priority?: number;
     relatedInstances?: RelatedInstanceSpecification[];
+    // @deprecated
     showImages?: boolean;
     specType: ContentSpecificationTypes;
 }
@@ -384,8 +386,11 @@ export type ContentUpdateInfo = typeof UPDATE_FULL;
 export function createFieldHierarchies(fields: Field[], ignoreCategories?: Boolean): FieldHierarchy[];
 
 // @public
-export type CustomizationRule = InstanceLabelOverride | CheckBoxRule | GroupingRule | ImageIdOverride | LabelOverride | // eslint-disable-line deprecation/deprecation
-SortingRule | StyleOverride | ExtendedDataRule | NodeArtifactsRule;
+export type CustomizationRule = InstanceLabelOverride | CheckBoxRule | // eslint-disable-line deprecation/deprecation
+GroupingRule | ImageIdOverride | // eslint-disable-line deprecation/deprecation
+LabelOverride | // eslint-disable-line deprecation/deprecation
+SortingRule | StyleOverride | // eslint-disable-line deprecation/deprecation
+ExtendedDataRule | NodeArtifactsRule;
 
 // @public
 export interface CustomNodeSpecification extends ChildNodeSpecificationBase {
@@ -1129,7 +1134,7 @@ export interface IdCategoryIdentifier {
     type: "Id";
 }
 
-// @public
+// @public @deprecated
 export interface ImageIdOverride extends RuleBase, ConditionContainer {
     condition?: string;
     imageIdExpression: string;
@@ -1313,6 +1318,7 @@ export class Item {
         [key: string]: any;
     };
     static fromJSON(json: ItemJSON | string | undefined): Item | undefined;
+    // @deprecated
     imageId: string;
     // @beta
     inputKeys?: InstanceKey[];
@@ -1336,7 +1342,7 @@ export interface ItemJSON {
     extendedData?: {
         [key: string]: any;
     };
-    // (undocumented)
+    // @deprecated (undocumented)
     imageId: string;
     // @beta (undocumented)
     inputKeys?: InstanceKeyJSON[];
@@ -1472,7 +1478,7 @@ export interface LabelGroupingNodeKeyJSON extends GroupingNodeKeyJSON {
     type: StandardNodeTypes.DisplayLabelGroupingNode;
 }
 
-// @public
+// @public @deprecated
 export interface LabelOverride extends RuleBase, ConditionContainer {
     condition?: string;
     description?: string;
@@ -1592,17 +1598,24 @@ export interface NoCategoryIdentifier {
 
 // @public
 export interface Node {
+    // @deprecated
     backColor?: string;
     description?: string;
     extendedData?: {
         [key: string]: any;
     };
+    // @deprecated
     fontStyle?: string;
+    // @deprecated
     foreColor?: string;
     hasChildren?: boolean;
+    // @deprecated
     imageId?: string;
+    // @deprecated
     isCheckboxEnabled?: boolean;
+    // @deprecated
     isCheckboxVisible?: boolean;
+    // @deprecated
     isChecked?: boolean;
     isEditable?: boolean;
     isExpanded?: boolean;
@@ -1675,27 +1688,27 @@ export interface NodeInsertionInfoJSON {
 
 // @public
 export interface NodeJSON {
-    // (undocumented)
+    // @deprecated (undocumented)
     backColor?: string;
     // (undocumented)
     description?: string;
     // (undocumented)
     extendedData?: {
         [key: string]: any;
     };
-    // (undocumented)
+    // @deprecated (undocumented)
     fontStyle?: string;
-    // (undocumented)
+    // @deprecated (undocumented)
     foreColor?: string;
     // (undocumented)
     hasChildren?: boolean;
-    // (undocumented)
+    // @deprecated (undocumented)
     imageId?: string;
-    // (undocumented)
+    // @deprecated (undocumented)
     isCheckboxEnabled?: boolean;
-    // (undocumented)
+    // @deprecated (undocumented)
     isCheckboxVisible?: boolean;
-    // (undocumented)
+    // @deprecated (undocumented)
     isChecked?: boolean;
     // (undocumented)
     isEditable?: boolean;
@@ -2807,7 +2820,7 @@ export interface StructTypeDescription extends BaseTypeDescription {
     valueFormat: PropertyValueFormat.Struct;
 }
 
-// @public
+// @public @deprecated
 export interface StyleOverride extends RuleBase, ConditionContainer {
     backColor?: string;
     condition?: string;

common/api/presentation-components.api.md

@@ -500,6 +500,8 @@ export interface PresentationTreeDataProviderDataSourceEntryPoints {
 export interface PresentationTreeDataProviderProps extends DiagnosticsProps {
     appendChildrenCountForGroupingNodes?: boolean;
     // @beta
+    customizeTreeNodeItem?: (item: Partial<DelayLoadedTreeNodeItem>, node: Partial<Node>) => void;
+    // @beta
     dataSourceOverrides?: Partial<PresentationTreeDataProviderDataSourceEntryPoints>;
     imodel: IModelConnection;
     pagingSize?: number;

common/api/summary/presentation-common.exports.csv

@@ -16,6 +16,7 @@ public;CategoryDescription
 public;CategoryDescriptionJSON
 public;CategoryIdentifier = ParentCategoryIdentifier | RootCategoryIdentifier | IdCategoryIdentifier
 public;CheckBoxRule 
+deprecated;CheckBoxRule 
 public;ChildNodeRule 
 public;ChildNodeSpecification = CustomNodeSpecification | InstanceNodesOfSpecificClassesSpecification | RelatedInstanceNodesSpecification | CustomQueryInstanceNodesSpecification
 public;ChildNodeSpecificationBase
@@ -155,6 +156,7 @@ public;Id64sRulesetVariable
 public;Id64sRulesetVariableJSON 
 public;IdCategoryIdentifier
 public;ImageIdOverride 
+deprecated;ImageIdOverride 
 public;InstanceId = Id64String
 public;InstanceKey
 public;InstanceKey
@@ -197,6 +199,7 @@ public;LabelDefinitionJSON
 public;LabelGroupingNodeKey 
 public;LabelGroupingNodeKeyJSON 
 public;LabelOverride 
+deprecated;LabelOverride 
 public;LabelRawValue = string | number | boolean | LabelCompositeValue
 public;LabelRawValueJSON = string | number | boolean | LabelCompositeValueJSON
 beta;MultiElementPropertiesRequestOptions
@@ -368,6 +371,7 @@ public;StrippedRelationshipPath = StrippedRelatedClassInfo[]
 public;StructFieldMemberDescription
 public;StructTypeDescription 
 public;StyleOverride 
+deprecated;StyleOverride 
 public;SubCondition 
 public;Subtract
 public;SupplementationInfo

common/changes/@itwin/presentation-common/presentation-customization_docs_improvement_2022-03-09-08-13.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/presentation-common",
+      "comment": "Deprecated StyleOverrideRule, ImageIdOverrideRule, CheckboxRule and LabelOverrideRule",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/presentation-common"
+}

common/changes/@itwin/presentation-components/presentation-customization_docs_improvement_2022-03-09-08-13.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/presentation-components",
+      "comment": "Added ability to customize TreeNodeItems produced by PresentationTreeDataProvider",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/presentation-components"
+}

docs/presentation/Content/ContentInstancesOfSpecificClasses.md

@@ -21,7 +21,6 @@ This specification creates content for all instances of specific ECClasses.
 | [`calculatedProperties`](#attribute-calculatedproperties)                       | No        | `CalculatedPropertiesSpecification[]`                                                                           | `[]`    |
 | [`propertyCategories`](#attribute-propertycategories)                           | No        | `PropertyCategorySpecification[]`                                                                               | `[]`    |
 | [`propertyOverrides`](#attribute-propertyoverrides)                             | No        | `PropertySpecification[]`                                                                                       | `[]`    |
-| [`showImages`](#attribute-showimages)                                           | No        | `boolean`                                                                                                       | `false` |
 | *Misc.*                                                                         |
 | [`relatedInstances`](#attribute-relatedinstances)                               | No        | [`RelatedInstanceSpecification[]`](../RelatedInstanceSpecification.md)                                          | `[]`    |
 
@@ -150,12 +149,6 @@ Specifications of various [property overrides](./PropertySpecification.md) that
   | before | ![Example when doing normal property select](./media/sharedattributes-with-propertyoverrides-1.png)        |
   | after  | ![Example when selecting with "property overrides"](./media/sharedattributes-with-propertyoverrides-2.png) |
 
-### Attribute: `showImages`
-
-> **Default value:** `false`
-
-Should image IDs be calculated for the returned instances. When `true`, [ImageIdOverride](../customization/ImageIdOverride.md) rules get applied when creating the content.
-
 ### Attribute: `relatedInstances`
 
 Specifications of [related instances](../RelatedInstanceSpecification.md) that can be used when creating the content. There are several use cases when this is useful:
@@ -190,3 +183,13 @@ Tells whether selecting instances from ECClasses specified in [`classes`](#attri
 
 The attribute was replaced by [MultiSchemaClasses.arePolymorphic](../MultiSchemaClassesSpecification.md#attribute-arepolymorphic) attribute specified individually for each class definition under [`classes`](#attribute-classes)
 and [`excludedClasses`](#attribute-excludedclasses) attributes. At the moment, to keep backwards compatibility, this attribute acts as a fallback value in case the flag is not specified individually for a class definition.
+
+## Deprecated attributes
+
+### Attribute: `showImages`
+
+> **Default value:** `false`
+
+Should image IDs be calculated for the returned instances. When `true`, [ImageIdOverride](../customization/ImageIdOverride.md) rules get applied when creating the content.
+
+[ExtendedDataRule](../customization/ExtendedDataRule.md) should be used instead to provide image data to content items created by this specification. See [extended data usage page](../customization/ExtendedDataUsage.md) for more details

docs/presentation/Content/ContentRelatedInstances.md

@@ -19,7 +19,6 @@ Returns content for instances related to the selected (input) instances.
 | [`calculatedProperties`](#attribute-calculatedproperties) | No        | `CalculatedPropertiesSpecification[]`                                                        | `[]`    |
 | [`propertyCategories`](#attribute-propertycategories)     | No        | `PropertyCategorySpecification[]`                                                            | `[]`    |
 | [`propertyOverrides`](#attribute-propertyoverrides)       | No        | `PropertySpecification[]`                                                                    | `[]`    |
-| [`showImages`](#attribute-showimages)                     | No        | `boolean`                                                                                    | `false` |
 | *Misc.*                                                   |
 | [`relatedInstances`](#attribute-relatedinstances)         | No        | [`RelatedInstanceSpecification[]`](../RelatedInstanceSpecification.md)                       | `[]`    |
 
@@ -122,12 +121,6 @@ Specifications of various [property overrides](./PropertySpecification.md) that
   | before | ![Example when doing normal property select](./media/sharedattributes-with-propertyoverrides-1.png)        |
   | after  | ![Example when selecting with "property overrides"](./media/sharedattributes-with-propertyoverrides-2.png) |
 
-### Attribute: `showImages`
-
-> **Default value:** `false`
-
-Should image IDs be calculated for the returned instances. When `true`, [ImageIdOverride](../customization/ImageIdOverride.md) rules get applied when creating the content.
-
 ### Attribute: `relatedInstances`
 
 Specifications of [related instances](../RelatedInstanceSpecification.md) that can be used when creating the content. There are several use cases when this is useful:
@@ -151,3 +144,13 @@ Specifications of [related instances](../RelatedInstanceSpecification.md) that c
   | `SpatialViewDefinition` instances                                 | ![A list of spatial view definitions](./media/sharedattributes-with-relatedinstances-3.png)                                           |
   | `ModelSelector` instances                                         | ![A list of model selectors](./media/sharedattributes-with-relatedinstances-2.png)                                                    |
   | `ModelSelector` instances filtered by `SpatialViewDefinition.Yaw` | ![A list of model selectors filtered by yaw of related spatial view definition](./media/sharedattributes-with-relatedinstances-1.png) |
+
+## Deprecated attributes
+
+### Attribute: `showImages`
+
+> **Default value:** `false`
+
+Should image IDs be calculated for the returned instances. When `true`, [ImageIdOverride](../customization/ImageIdOverride.md) rules get applied when creating the content.
+
+[ExtendedDataRule](../customization/ExtendedDataRule.md) should be used instead to provide image data to content items created by this specification. See [extended data usage page](../customization/ExtendedDataUsage.md) for more details.

docs/presentation/Content/SelectedNodeInstances.md

@@ -20,7 +20,6 @@ Returns content for selected (input) instances.
 | [`calculatedProperties`](#attribute-calculatedproperties)           | No        | `CalculatedPropertiesSpecification[]`                                  | `[]`    |
 | [`propertyCategories`](#attribute-propertycategories)               | No        | `PropertyCategorySpecification[]`                                      | `[]`    |
 | [`propertyOverrides`](#attribute-propertyoverrides)                 | No        | `PropertySpecification[]`                                              | `[]`    |
-| [`showImages`](#attribute-showimages)                               | No        | `boolean`                                                              | `false` |
 | *Misc.*                                                             |
 | [`relatedInstances`](#attribute-relatedinstances)                   | No        | [`RelatedInstanceSpecification[]`](../RelatedInstanceSpecification.md) | `[]`    |
 
@@ -143,12 +142,6 @@ Specifications of various [property overrides](./PropertySpecification.md) that
   | before | ![Example when doing normal property select](./media/sharedattributes-with-propertyoverrides-1.png)        |
   | after  | ![Example when selecting with "property overrides"](./media/sharedattributes-with-propertyoverrides-2.png) |
 
-### Attribute: `showImages`
-
-> **Default value:** `false`
-
-Should image IDs be calculated for the returned instances. When `true`, [ImageIdOverride](../customization/ImageIdOverride.md) rules get applied when creating the content.
-
 ### Attribute: `relatedInstances`
 
 Specifications of [related instances](../RelatedInstanceSpecification.md) that can be used when creating the content. There are several use cases when this is useful:
@@ -172,3 +165,13 @@ Specifications of [related instances](../RelatedInstanceSpecification.md) that c
   | `SpatialViewDefinition` instances                                 | ![A list of spatial view definitions](./media/sharedattributes-with-relatedinstances-3.png)                                           |
   | `ModelSelector` instances                                         | ![A list of model selectors](./media/sharedattributes-with-relatedinstances-2.png)                                                    |
   | `ModelSelector` instances filtered by `SpatialViewDefinition.Yaw` | ![A list of model selectors filtered by yaw of related spatial view definition](./media/sharedattributes-with-relatedinstances-1.png) |
+
+## Deprecated attributes
+
+### Attribute: `showImages`
+
+> **Default value:** `false`
+
+Should image IDs be calculated for the returned instances. When `true`, [ImageIdOverride](../customization/ImageIdOverride.md) rules get applied when creating the content.
+
+[ExtendedDataRule](../customization/ExtendedDataRule.md) should be used instead to provide image data to content items created by this specification. See [extended data usage page](../customization/ExtendedDataUsage.md) for more details.