[WIP] PIM training raw draft

Author: adriendupuis

docs/trainings/commerce/pim/000_syllabus.md

@@ -0,0 +1,68 @@
+---
+description: PIM training
+---
+
+[[% include 'snippets/experience_badge.md' %]] [[% include 'snippets/commerce_badge.md' %]]
+# PIM (Product Information Management)
+
+## Syllabus
+
+In this training, you learn how to create complex products, to quote their prices, and to organize them in catalogs, using the build-in features.
+
+| Section                                         | Estimated | Description                                                                   |
+|:------------------------------------------------|----------:|:------------------------------------------------------------------------------|
+| [Product modeling](011_product_modeling.md)     | X minutes | Learn about product types, products and product variants.                     |
+| [Product shelving](012_product_shelving.md)     | Y minutes | Organize your products with categories and catalogs.                          |
+| [Product displaying](013_product_displaying.md) | Z minutes | Template the product page.                                                    |
+| [Product pricing](021_product_pricing.md)       | N minutes | Manage currencies and VAT rates, compute prices. (TODO: discount needs users) |                               
+
+## Requirements
+
+### Previous knowledge
+
+- [Content management](content_management.md)
+  - [Content types](content_types.md) and [content items](content_model.md#content-items)
+  - [Taxonomy](taxonomy.md)
+- [Templating](templating.md)
+
+### Ibexa DXP edition
+
+[[= product_name_headless =]] is the minimal edition required for this training.
+
+- [[= product_name_headless =]] [[= latest_tag_4_6 =]]
+- [[= product_name_exp =]] [[= latest_tag_4_6 =]]
+- [[= product_name_com =]] [[= latest_tag_4_6 =]]
+
+TODO: Make sure that everything used is in Ibexa DXP Headless scope, so to speak, ibexa/product-catalog
+TODO: Trainees working on Ibexa DXP Commerce could pick examples from ibexa/storefront but others mustn't be frustrated of having installed an inferior edition.
+
+!!! note
+
+    You can use [`experience-skeleton`'s DDEV feature](ddev_interactive_launcher.md#experience)
+
+    For more suggestions about your training environment, see [Training environment](trainings.md#training-environment).
+
+### Cluster elements
+
+This training needs a reverse proxy for HTTP cache. For a local installation, Varnish is recommended.
+
+|       Service | Required | Value        |
+|--------------:|:--------:|:-------------|
+| Search engine |    No    | (Legacy)     |
+|    Cache pool |    No    | (Filesystem) |
+|    HTTP cache |    No    |              |
+
+### Starting state
+
+To follow this training, you must install code, config and data on top of a fresh installation.
+
+1. Download the [starting state archive](download/a_late_training.start.zip).
+1. Put this archive at the root of your [[= product_name =]] training installation.
+1. In a terminal, run the following commands at the root of your [[= product_name =]] training installation:
+   ```bash
+   unzip a_late_training.start.zip
+   tail -n+2 config/append_to_services.yaml >> config/services.yaml
+   rm config/append_to_services.yaml
+   php bin/console ibexa:migrations:migrate --file=a_late_training_content_types.yml --siteaccess=admin
+   php bin/console ibexa:migrations:migrate --file=a_late_training_contents.yml --siteaccess=admin
+   ```

docs/trainings/commerce/pim/011_product_modeling.md

@@ -0,0 +1,185 @@
+---
+description: "PIM training: Product modeling"
+edition: experience
+page_type: training
+---
+
+# Product modeling
+
+## Product types
+
+The product type base concept is close to the content type one.
+Like a content type structures a family content items, a product type structures products.
+
+See a first conceptualisation of what a product is, and what a product type is, in [Documentation > PIM (Product management) > Products](products.md).
+
+In fact, a product type is really a content type from the hidden system group `product` with a field of type “Product specification” (`ibexa_product_specification`).
+
+The presence of an `ibexa_product_specification` field is what distinct product type from content type.
+Don't remove this field from a product type (or it will become a unreachable hidden content type).
+Don't add such field to a content type (or it will become an uneditable broken product type).
+
+TODO: What happens if you have several `ibexa_product_specification` fields?
+
+You can trick the system URL to display a product type as a content type but know that this is dangerous and mustn't be exposed to final users.
+Always prefer the dedicated route (as the Back Office does) `/product-type/view/<product_type_identifier` (`ibexa.product_catalog.product_type.view`).
+To view it through `/contenttypegroup/<product_group_id>/contenttype/<product_type_id>` (`ibexa.content_type.view`) is doable. You could even edit it from there. But this is strongly not recommended.
+
+TODO: move to somewhere in the exercise
+If you're curious, after having created a product type, you can run the following SQL query to see the database representation.
+
+```sql
+SELECT cg.group_id, cg.group_name, g.is_system, c.id, c.identifier, c.version
+    FROM ezcontentclass AS c
+        JOIN ezcontentclass_classgroup AS cg ON c.id = cg.contentclass_id AND c.version = cg.contentclass_version
+        JOIN ezcontentclassgroup AS g ON cg.group_id = g.id
+    ORDER BY cg.group_id ASC, c.id ASC
+;
+```
+
+The "Product specification" field type (`ibexa_product_specification`) brings in the power of attributes.
+
+Notice that you don't need to add a field or an attribute for price.
+Prices are handled by a particular side mechanism, the price engine, which is treated later in the training with VAT, currencies, etc.
+
+## Attributes VS Fields
+
+Like fields, attributes are typed.
+
+Unlike fields, attributes are never translatable.
+Attributes are product constant properties.
+Attributes values can't be translated because those properties don't change with the language.
+Only the display of those properties changes with the language. See the following concept examples:
+
+- The color of a product is the same whatever the language is, only the corresponding color name is translated.
+- The radius of a sphere doesn't depend on the language, only its numeral representation need translation according to local length units.
+
+TODO: Later in the training, in the templating part, is shown how to localize the attributes.
+
+Unlike fields, attributes are first defined outside the product types.
+Attributes and attribute groups are to be reused from product type to product type.
+
+An attribute can be used to make product variant.
+
+TODO: Best practices:
+How to think product types?
+How to not have a product type per product?
+How to not want a "god" product type trying to cover everything?
+
+TODO: Variants
+TODO: attribute value display translation
+
+## Product and product variants
+
+Technically, a product is a content item.
+
+But a variant isn't.
+
+TODO: Continue content VS product VS variant
+
+## Exercise: Bikes and bike parts modeling
+
+Exercise: Think about attributes and content type to sell full bicycles and bicycle parts.
+
+The following is an example of a bicycle feature model sketch.
+As you can see, it's a rich and complex matrix.
+And it doesn't involve different brands and models for the same feature yet.
+
+- Bicycle:
+  - Frameset:
+    - Frame:
+      - Size: [XS, S, M, L, XL]
+      - Shape/Features: [Diamond, Step-through, Diamond w/ suspension, Folding, Recumbent, Cargo, Tandem, …]
+      - Material: [Steel, Aluminium, Titanium, Carbon, Wood, Bamboo, Mixed, …]
+      - Paint job: […]
+    - Fork
+      - Size: [XS, S, M, L, XL]
+      - Suspension: yes/no
+      - Paint job: […]
+  - Handlebar:
+    - Shape: [Standard, Drop, Bullhorn, Flat, Riser, …]
+    - Paint job: […]
+  - Saddle:
+    - Shape: [Thin, Large, Noseless, …]
+    - Cushion material: [Foam, Gel, …]
+    - Cover material: [Spandex, Vinyl, Kevlar, Leather, …]
+    - Paint job: […]
+  - Saddlepost:
+    - Material: [Steel, Aluminium, Titanium, Carbon, Wood, Bamboo, Mixed, …]
+    - Type: [Rigid, Suspension, Dropper, …]
+    - Attachment: [Quick release, Bolt/nut, Anti-thief, …]
+  - Gears:
+    - Front gears:
+      - Speed count: [1…3]
+      - Type: [Single, External, Hub internal, Crank gearbox, …]
+      - Control transmission: [Bowden cable, Hydraulic, Electronic, …]
+      - Control type: [Lever, Ring, …]
+      - Control placement: [Handlebar, Frame, …]
+    - Rear gears:
+      - Speed count: [1…8]
+      - Control type: [Bowden cable, Hydraulic, Electronic, …]
+      - Type: [Single, External, Hub internal, Crank gearbox, …]
+      - Control transmission: [Bowden cable, Hydraulic, Electronic, …]
+      - Control type: [Lever, Ring, …]
+      - Control placement: [Handlebar, Frame, …]
+  - Transmission: [Chain, Belt, Shaft, …]
+  - Wheel set:
+    - Rear wheel:
+      - Axle attachment: [Quick release, Bolt/nut, Thru, Anti-thief, …]
+      - Diameter: [622 mm (road 700C, mountain 29″), 584 mm (road 650B, mountain 27.5″), 559 mm (mountain 26″), 406 mm (mountain 20″), …]
+      - Type: [Standard spokes, G3 spokes, Disc, …]
+      - Brake: [Caliper, Disk, Roller, Drum, …]
+      - Rim material: [Aluminium, Steel, Carbon, …]
+      - Tire shape: [City, Race, Mountain, Fat, Mixed, …]
+      - Tire insert: [Clincher/Tube, Tubular, Tubeless, Foam, Solid, …]
+      - Paint job: […]
+    - Front wheel:
+      - Same as rear: ☑yes/☐no
+      - Axle attachment: [Same as rear, Quick release, Bolt/nut, Thru, Anti-thief, …]
+      - Diameter: [Same as rear, 622 mm (road 700C, mountain 29″), 584 mm (road 650B, mountain 27.5″), 559 mm (mountain 26″), 406 mm (mountain 20″), …]
+      - Type: [Same as rear, Standard spokes, G3 spokes, Disc, …]
+      - Brake: [Same as rear, Caliper, V, Disk, Roller, …]
+      - Rim material: [Same as rear, Aluminium, Steel, Carbon, …]
+      - Tire shape: [Same as rear, City, Race, Mountain, Fat, Mixed, …]
+      - Tire insert: [Same as rear, Clincher/Tube, Tubular, Tubeless, Foam, Solid, …]
+      - Paint job: [Same as rear, Same as rear, …]
+  - Electric assistance:
+    - Electric assistance: ☐yes/☑no
+    - Motor placement: [Front wheel, Rear wheel, Crank, …]
+    - Battery placement: [Center, Rear, …]
+    - Regulation: [EU pedelec, EU speed pedelec, …]
+
+A bad practice would be to try to have a unique product type for modeling all the bikes from the catalog.
+For example, series of product won't necessarily vary on the same attributes.
+TODO: To have one product type per base product can happen.
+
+
+
+
+Mountain Bike (MTB)
+- MTB 4 series
+    - Fuji (3776€) (MTBS4-4)
+      - Frame: [Diamond, Step-through]
+      - TODO
+    - Matterhorn (4478€) (MTBS4-5)
+    - Annapurna (8091€) (MTBS4-6)
+      - Frame: [Diamond w/ suspension]
+    - Etna (3369€) (MTBS4-7)
+- MTB 5 series
+  - Kilimanjaro (5895€) (MTBS5-0)
+  - Stádda (1392€) (MTBS5-1)
+  - Aconcagua (6960€) (MTBS5-2)
+  - Ventoux (1910€) (MTBS5-3)
+  - Castor (4225€) (MTBS5-4)
+
+
+- Create the attribute groups
+- Create the attributes
+- Create the product types
+- Create the products
+
+TODO: Variants
+TODO: [Create custom product code generator strategy](create_product_code_generator.md) 
+
+Your new products are in the "Uncategorized products" section of the **Products** admin page.
+It's now time to fix this in the next chapter.

docs/trainings/commerce/pim/012_product_shelving.md

@@ -0,0 +1,43 @@
+---
+description: "PIM training: Product shelving"
+edition: experience
+page_type: training
+---
+
+# Product shelving
+
+There is several ways to group and sort products. TODO
+
+## Catalogs
+
+[Catalogs](catalogs.md) group products by filtering on product data.
+
+TODO: What having several catalogs implies (navigation, customer experience,…)
+TODO: How catalogs are displayed? Move this concern to "Product displaying"
+TODO: [Create custom catalog](create_custom_catalog_filter.md)
+
+## Categories
+
+Product categories are tags in the `product_categories` [taxonomy](taxonomy.md).
+
+If you're curious, you can find the `product_categories` taxonomy configuration in `vendor/ibexa/product-catalog/src/bundle/Resources/config/prepend.yaml`.
+
+TODO: Something interesting to do using the Taxo API?
+
+Exercise:
+
+- Create a "Mountain Bike" category with two child categories "4 Series" and "5 Series"
+- Categorize the products from previous chapter's exercise into the right series:
+
+- Mountain Bike
+  - 4 Series
+    - Fuji
+    - Matterhorn
+    - Annapurna
+    - Etna
+  - 5 Series
+    - Kilimanjaro
+    - Stádda
+    - Aconcagua
+    - Ventoux
+    - Castor