Presentation: Learning snippets cleanup

common/changes/@itwin/presentation-backend/presentation-docs-learning-snippets-cleanup_2022-03-22-13-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/presentation-backend",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/presentation-backend"
+}

docs/presentation/Advanced/RulesetVariables.md

@@ -24,23 +24,23 @@ The below example creates either a models' or an elements' hierarchy based on th
 By default the ruleset value is not set, which means neither of the two root node rules pass the condition. The result is empty hierarchy:
 
 ```ts
-[[include:RulesetVariables.InRuleCondition.Ruleset]]
+[[include:Presentation.RulesetVariables.InRuleCondition.Ruleset]]
 ```
 
 ![Empty Hierarchy](./media/ruleset-variables/empty-hierarchy.png)
 
 Setting the ruleset value to `models` creates a models' hierarchy:
 
 ```ts
-[[include:RulesetVariables.InRuleCondition.SetToModels]]
+[[include:Presentation.RulesetVariables.InRuleCondition.SetToModels]]
 ```
 
 ![Models' Hierarchy](./media/ruleset-variables/models-hierarchy.png)
 
 Setting the ruleset value to `elements` creates an elements' hierarchy:
 
 ```ts
-[[include:RulesetVariables.InRuleCondition.SetToElements]]
+[[include:Presentation.RulesetVariables.InRuleCondition.SetToElements]]
 ```
 
 ![Elements' Hierarchy](./media/ruleset-variables/elements-hierarchy.png)
@@ -54,23 +54,23 @@ The below example shows a hierarchy of elements grouped by class. When the `elem
 By default the ruleset value is not set - a hierarchy for all elements is created:
 
 ```ts
-[[include:RulesetVariables.InInstanceFilter.Ruleset]]
+[[include:Presentation.RulesetVariables.InInstanceFilter.Ruleset]]
 ```
 
 ![Empty Hierarchy](./media/ruleset-variables/elements-hierarchy.png)
 
 Setting the ruleset value to specific IDs creates the hierarchy only for specific elements:
 
 ```ts
-[[include:RulesetVariables.InInstanceFilter.SetIds]]
+[[include:Presentation.RulesetVariables.InInstanceFilter.SetIds]]
 ```
 
 ![Filtered Elements' Hierarchy](./media/ruleset-variables/filtered-elements-hierarchy.png)
 
 Clearing the ruleset value brings us back to the initial unfiltered view:
 
 ```ts
-[[include:RulesetVariables.InInstanceFilter.Unset]]
+[[include:Presentation.RulesetVariables.InInstanceFilter.Unset]]
 ```
 
 ![Elements' Hierarchy](./media/ruleset-variables/elements-hierarchy.png)
@@ -84,15 +84,15 @@ The below example shows a hierarchy that loads *Spatial View Definition* element
 By default the ruleset value is not set - *CodeValue* property value is used as the label:
 
 ```ts
-[[include:RulesetVariables.InCustomizationRuleValueExpression.Ruleset]]
+[[include:Presentation.RulesetVariables.InCustomizationRuleValueExpression.Ruleset]]
 ```
 
 ![Spatial View Definitions](./media/ruleset-variables/spatial-view-definitions.png)
 
 Setting the ruleset variable value makes it appear in front of every node's label:
 
 ```ts
-[[include:RulesetVariables.InCustomizationRuleValueExpression.SetValue]]
+[[include:Presentation.RulesetVariables.InCustomizationRuleValueExpression.SetValue]]
 ```
 
 ![Spatial View Definitions - Prefixed Labels](./media/ruleset-variables/spatial-view-definitions-prefixed.png)

docs/presentation/Advanced/SchemaRequirements.md

@@ -34,7 +34,7 @@ used in it.
 ### Specifying required schema in a hierarchy rule
 
 ```ts
-[[include:Hierarchies.RequiredSchemas.Ruleset]]
+[[include:Presentation.Hierarchies.RequiredSchemas.Ruleset]]
 ```
 
 ### Specifying required schema in content modifier

docs/presentation/Advanced/Testing.md

@@ -1,33 +1,51 @@
 # Testing
 
-Although the presentation framework itself is thoroughly tested, consumers
-should still verify they get expected results for their iModel + ruleset
-combinations. The **@itwin/presentation-testing** package is delivered
+Although the presentation framework itself is thoroughly tested, consumers should still verify they get expected results for their iModel + ruleset combinations. The **@itwin/presentation-testing** package is delivered
 purely for that reason.
 
-The package delivers an API that allows creating hierarchies for supplied
-iModels and rulesets. Consumers can then verify the result using tools of
-their liking. Our recommendation is to use snapshot testing for 2 reasons:
+The package delivers an API that allows creating hierarchies for supplied iModels and rulesets. Consumers can then verify the result using tools of their liking. Our recommendation is to use snapshot testing for 2 reasons:
 
-1. resulting hierarchies get rather large - testing the them in
-code might be difficult
-2. snapshots protect against regressions
+1. Resulting hierarchies get rather large — testing them in code might be difficult.
+2. Snapshots protect against regressions.
 
 ## Example
 
 An example of setting up snapshot tests with the **@itwin/presentation-testing** package:
 
-``` ts
-[[include:Presentation.Testing.Rulesets]]
-```
+1. Initialize testing library and open iModel
+
+    ```ts
+    [[include:Presentation.Testing.Rulesets.Setup]]
+    ```
+
+2. Generate and verify results:
+
+    2.1. Hierarchies:
+
+      ```ts
+      [[include:Presentation.Testing.Rulesets.Hierarchies]]
+      ```
+
+    2.2. Content:
+
+      ```ts
+      [[include:Presentation.Testing.Rulesets.Content]]
+      ```
+
+3. Close iModel and terminate testing library:
+
+    ```ts
+    [[include:Presentation.Testing.Rulesets.Terminate]]
+    ```
+
+**Note:** The above example uses [mocha](https://www.npmjs.com/package/mocha) and [chai-jest-snapshot](https://www.npmjs.com/package/chai-jest-snapshot) packages to perform snapshot testing. `createSnapshotPath` function retrieves a path to the snapshot for the current test.
 
 ## Things to keep in mind
 
-- Run initialize() before and terminate() after the tests
-- Don't forget to close the iModel connection
-- Ruleset can be provided either as an ID of already registered ruleset or
-  as a `Ruleset` object. The object can even be imported from a JSON file:
+- Run initialize() before and terminate() after the tests.
+- Don't forget to close the iModel connection.
+- Ruleset can be provided either as an ID of already registered ruleset or as a `Ruleset` object. The object can even be imported from a JSON file:
 
   ```ts
-  await builder.createHierarchy(require("rulesets/YourRuleset"))
+  await builder.createHierarchy(require("rulesets/YourRuleset.json"))
   ```

docs/presentation/Content/CalculatedPropertiesSpecification.md

@@ -17,7 +17,7 @@ This content modifier allows including additional calculated properties into the
 Specifies label of the calculated property. Supports [localization](../Advanced/Localization.md).
 
 ```ts
-[[include:Content.Customization.CalculatedPropertiesSpecification.Label.Ruleset]]
+[[include:Presentation.Content.Customization.CalculatedPropertiesSpecification.Label.Ruleset]]
 ```
 
 ![Example of using "label" attribute](./media/calculatedpropertiesspecification-with-label-attribute.png)
@@ -28,7 +28,7 @@ Defines an expression to calculate the value. The expression can use [ECInstance
 and [Ruleset Variables](../Advanced/ECExpressions.md#ruleset-variables-user-settings) symbol contexts.
 
 ```ts
-[[include:Content.Customization.CalculatedPropertiesSpecification.Value.Ruleset]]
+[[include:Presentation.Content.Customization.CalculatedPropertiesSpecification.Value.Ruleset]]
 ```
 
 ![Example of using "value" attribute](./media/calculatedpropertiesspecification-with-value-attribute.png)
@@ -41,7 +41,7 @@ Assign a custom [Field.priority]($presentation-common) to the property. It's up
 is respected - properties with higher priority should appear before or above properties with lower priority.
 
 ```ts
-[[include:Content.Customization.CalculatedPropertiesSpecification.Priority.Ruleset]]
+[[include:Presentation.Content.Customization.CalculatedPropertiesSpecification.Priority.Ruleset]]
 ```
 
 | `priority: 9999`                                                                                                                 | `priority: -9999`                                                                                                                |

docs/presentation/Content/ContentInstancesOfSpecificClasses.md

@@ -29,7 +29,7 @@ This specification creates content for all instances of specific ECClasses.
 Defines a set of [multi schema classes](../MultiSchemaClassesSpecification.md) that specify which ECClasses need to be selected to form the result.
 
 ```ts
-[[include:ContentInstancesOfSpecificClasses.Classes.Ruleset]]
+[[include:Presentation.ContentInstancesOfSpecificClasses.Classes.Ruleset]]
 ```
 
 ![Example of using "classes" attribute](./media/contentinstancesofspecificclasses-with-classes.png)
@@ -39,7 +39,7 @@ Defines a set of [multi schema classes](../MultiSchemaClassesSpecification.md) t
 Defines a set of [multi schema classes](../MultiSchemaClassesSpecification.md) that prevents specified ECClasses and subclasses from being selected by [`classes` attribute](#attribute-classes).
 
 ```ts
-[[include:ContentInstancesOfSpecificClasses.ExcludedClasses.Ruleset]]
+[[include:Presentation.ContentInstancesOfSpecificClasses.ExcludedClasses.Ruleset]]
 ```
 
   |                                       | Result                                                                                                                               |
@@ -54,7 +54,7 @@ Defines a set of [multi schema classes](../MultiSchemaClassesSpecification.md) t
 Specifies whether properties of derived `classes` should be included in the content.
 
 ```ts
-[[include:ContentInstancesOfSpecificClasses.HandlePropertiesPolymorphically.Ruleset]]
+[[include:Presentation.ContentInstancesOfSpecificClasses.HandlePropertiesPolymorphically.Ruleset]]
 ```
 
   | handlePropertiesPolymorphically | Result                                                                                                                                            |
@@ -67,7 +67,7 @@ Specifies whether properties of derived `classes` should be included in the cont
 Specifies an [ECExpression](./ECExpressions.md#instance-filter) for filtering instances of ECClasses specified through the [`classes` attribute](#attribute-classes).
 
 ```ts
-[[include:ContentInstancesOfSpecificClasses.InstanceFilter.Ruleset]]
+[[include:Presentation.ContentInstancesOfSpecificClasses.InstanceFilter.Ruleset]]
 ```
 
   |                | Result                                                                                      |
@@ -82,7 +82,7 @@ Specifies an [ECExpression](./ECExpressions.md#instance-filter) for filtering in
 Specifies whether this specification should be ignored if another specification was handled before as determined by rule and specification priorities. This provides a mechanism for defining a fallback specification.
 
 ```ts
-[[include:SharedAttributes.OnlyIfNotHandled.Ruleset]]
+[[include:Presentation.SharedAttributes.OnlyIfNotHandled.Ruleset]]
 ```
 
   | onlyIfNotHandled | Result                                                                                                     |
@@ -97,7 +97,7 @@ Specifies whether this specification should be ignored if another specification
 Controls the order in which specifications are handled — specification with higher priority value is handled first. If priorities are equal, the specifications are handled in the order they appear in the ruleset.
 
 ```ts
-[[include:SharedAttributes.Priority.Ruleset]]
+[[include:Presentation.SharedAttributes.Priority.Ruleset]]
 ```
 
 ![Example of using "priority" attribute](./media/sharedattributes-with-priority.png)
@@ -107,7 +107,7 @@ Controls the order in which specifications are handled — specification with hi
 Specifications of [related properties](./RelatedPropertiesSpecification.md) which are included in the generated content.
 
 ```ts
-[[include:SharedAttributes.RelatedProperties.Ruleset]]
+[[include:Presentation.SharedAttributes.RelatedProperties.Ruleset]]
 ```
 
   | without related properties                                                                          | with related properties                                                                                    |
@@ -119,7 +119,7 @@ Specifications of [related properties](./RelatedPropertiesSpecification.md) whic
 Specifications of [calculated properties](./CalculatedPropertiesSpecification.md) whose values are generated using provided [ECExpressions](../Advanced/ECExpressions.md#ecinstance).
 
 ```ts
-[[include:SharedAttributes.CalculatedProperties.Ruleset]]
+[[include:Presentation.SharedAttributes.CalculatedProperties.Ruleset]]
 ```
 
 ![Example of using "calculated properties" attribute](./media/sharedattributes-with-calculatedproperties.png)
@@ -131,7 +131,7 @@ Defines a list of [custom categories](PropertyCategorySpecification.md).
 Custom categories are not present in the result unless they contain at least one property. To assign a property to the category, reference its `id` in [`PropertySpecification.categoryId`](./PropertySpecification.md) when defining [`propertyOverrides`](#attribute-propertyoverrides).
 
 ```ts
-[[include:SharedAttributes.PropertyCategories.Ruleset]]
+[[include:Presentation.SharedAttributes.PropertyCategories.Ruleset]]
 ```
 
 ![Example of using "property categories" attribute](./media/sharedattributes-with-propertycategories.png)
@@ -141,7 +141,7 @@ Custom categories are not present in the result unless they contain at least one
 Specifications of various [property overrides](./PropertySpecification.md) that allow customizing individual properties display.
 
 ```ts
-[[include:SharedAttributes.PropertyOverrides.Ruleset]]
+[[include:Presentation.SharedAttributes.PropertyOverrides.Ruleset]]
 ```
 
   |        | Result                                                                                                     |
@@ -164,7 +164,7 @@ Specifications of [related instances](../RelatedInstanceSpecification.md) that c
   [alias](../RelatedInstanceSpecification.md#attribute-alias).
 
 ```ts
-[[include:SharedAttributes.RelatedInstances.Ruleset]]
+[[include:Presentation.SharedAttributes.RelatedInstances.Ruleset]]
 ```
 
   |                                                                   | Result                                                                                                                                |

docs/presentation/Content/ContentModifier.md

@@ -23,7 +23,7 @@ Content modifiers are used to modify how instances of specified ECClasses are di
 Specification of ECClass whose content should be modified. The modifier is applied to all content if this attribute is not specified.
 
 ```ts
-[[include:ContentModifier.Class.Ruleset]]
+[[include:Presentation.ContentModifier.Class.Ruleset]]
 ```
 
 ![Example of using class attribute](./media/modifier-with-class-attribute.png)
@@ -33,15 +33,15 @@ Specification of ECClass whose content should be modified. The modifier is appli
 A list of ECSchema requirements that need to be met for the rule to be used. See more details in [Defining ECSchema Requirements for Presentation Rules](../Advanced/SchemaRequirements.md).
 
 ```ts
-[[include:ContentModifier.RequiredSchemas.Ruleset]]
+[[include:Presentation.ContentModifier.RequiredSchemas.Ruleset]]
 ```
 
 ### Attribute: `priority`
 
 Defines the order in which rules are handled, higher number means the rule is handled first. If priorities are equal, the rules are handled in the order they're defined.
 
 ```ts
-[[include:ContentModifier.Priority.Ruleset]]
+[[include:Presentation.ContentModifier.Priority.Ruleset]]
 ```
 
 ![Example of using priority attribute](./media/modifier-with-priority-attribute.png)
@@ -51,7 +51,7 @@ Defines the order in which rules are handled, higher number means the rule is ha
 Specifications of [related properties](./RelatedPropertiesSpecification.md) which are included in the generated content.
 
 ```ts
-[[include:ContentModifier.RelatedProperties.Ruleset]]
+[[include:Presentation.ContentModifier.RelatedProperties.Ruleset]]
 ```
 
 ![Example of using relatedProperties attribute](./media/modifier-with-relatedproperties-attribute.png)
@@ -61,7 +61,7 @@ Specifications of [related properties](./RelatedPropertiesSpecification.md) whic
 Specifications of [calculated properties](./CalculatedPropertiesSpecification.md) whose values are generated using provided ECExpressions.
 
 ```ts
-[[include:ContentModifier.CalculatedProperties.Ruleset]]
+[[include:Presentation.ContentModifier.CalculatedProperties.Ruleset]]
 ```
 
 ![Example of using calculatedProperties attribute](./media/modifier-with-calculatedproperties-attribute.png)
@@ -71,7 +71,7 @@ Specifications of [calculated properties](./CalculatedPropertiesSpecification.md
 Specifications for [custom categories](./PropertyCategorySpecification.md). Simply defining the categories does nothing - they have to be referenced from [PropertySpecification]($presentation-common) defined in [propertyOverrides](#attribute-propertyoverrides) by `id`.
 
 ```ts
-[[include:ContentModifier.PropertyCategories.Ruleset]]
+[[include:Presentation.ContentModifier.PropertyCategories.Ruleset]]
 ```
 
 ![Example of using propertyCategories attribute](./media/modifier-with-propertycategories-attribute.png)
@@ -81,7 +81,7 @@ Specifications for [custom categories](./PropertyCategorySpecification.md). Simp
 Specifications for various [property overrides](./PropertySpecification.md) that allow customizing property display.
 
 ```ts
-[[include:ContentModifier.PropertyOverrides.Ruleset]]
+[[include:Presentation.ContentModifier.PropertyOverrides.Ruleset]]
 ```
 
 ![Example of using propertyOverrides attribute](./media/modifier-with-propertyoverrides-attribute.png)