Skip to content

Commit

Permalink
documentation review
Browse files Browse the repository at this point in the history
  • Loading branch information
@marschmidt89
marschmidt89 committed Mar 9, 2021
1 parent 59c2c56 commit d2c40cd
Showing 1 changed file with 29 additions and 30 deletions.
59 changes: 29 additions & 30 deletions docs/guides/product-context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,28 +11,28 @@ Product Contexts were introduced in PWA version [0.27](https://github.com/inters

## What is a Product Context?

Product Contexts provide an easy access to all data related to a single product.
The context itself stores the `sku` and (optional) `quantity` of the product and delegates all other information from the [State Management][state-management] in a simplified fashion.
Product contexts provide easy access to all data related to a single product.
The context itself stores the `sku` and (optional) the `quantity` of the product and delegates all other information from the [State Management][state-management] in a simplified fashion.

The following screenshots provide examples where product contexts are used on some pages:

<div style="text-align: center;">
<a target="_blank" href="product-context-recommendations.png"><img src="product-context-recommendations.png" alt="drawing" width="23%"/></a>
<a target="_blank" href="product-context-listing.png"><img src="product-context-listing.png" alt="drawing" width="23%"/></a>
<a target="_blank" href="product-context-bundle.png"><img src="product-context-bundle.png" alt="drawing" width="23%"/></a>
<a target="_blank" href="product-context-wishlists.png"><img src="product-context-wishlists.png" alt="drawing" width="23%"/></a>
<a target="_blank" href="product-context-recommendations.png"><img src="product-context-recommendations.png" alt="Product contexts used for recommendations" width="23%"/></a>
<a target="_blank" href="product-context-listing.png"><img src="product-context-listing.png" alt="Product contexts used for product listings" width="23%"/></a>
<a target="_blank" href="product-context-bundle.png"><img src="product-context-bundle.png" alt="Product contexts used for product bundles" width="23%"/></a>
<a target="_blank" href="product-context-wishlists.png"><img src="product-context-wishlists.png" alt="Product contexts used for wish lists" width="23%"/></a>
</div>

For product pages, there is always one context, that spans all the content of the product page.
Nevertheless additional contexts for recommended products or bundled products can exist on the page.
For product pages, there is always one context that spans the entire content of the product page.
However, additional contexts for recommended products or bundled products may exist on the page.
For listings of any kind, individual contexts exist on the page for each product.
Product Contexts can also be linked to their parent contexts.

## How to introduce Product Context?
## How to Introduce Product Context?

Other than normal facades, which are globally available and only one instance is available at runtime, context facades are provided using [`ElementInjector`](https://angular.io/guide/hierarchical-dependency-injection#elementinjector) and are therefore only available for elements enclosed in the document subtree, for which element introduced the context.
Unlike regular facades, which are available globally and have only one instance available at runtime, context facades are provided using [`ElementInjector`](https://angular.io/guide/hierarchical-dependency-injection#elementinjector) and are therefore only available for elements enclosed in the document subtree for which the element introduced the context.

### by using [`ProductContextDirective`][src-product-context-directive]
### By Using [`ProductContextDirective`][src-product-context-directive]

The easiest way to start a product context is by using the [`ProductContextDirective`][src-product-context-directive] on templates:

Expand All @@ -46,21 +46,20 @@ The easiest way to start a product context is by using the [`ProductContextDirec

What happens here?

- For each individual `item` from `lineItems$`, a product context is provided for embedded elements.
- For each individual `item` from `lineItems$`, a product context for embedded elements is provided.
- Each individual context is associated with `item.sku` which also triggers fetching the product if it is not already available in the store.
- The `ish-product-name` component will render the product name.

This also portrays one of the main advantages of using this concept: No bubbling of product related data is necessary anymore.
The `ish-product-name` component is injecting the provided context and decides which data is used for rendering.
The `ish-product-name` component injects the provided context and decides which data is used for rendering.

Have a look at [`ProductDetailComponent`](../../src/app/pages/product/product-detail/product-detail.component.html), which now only does layout and styling, whereas the context is provided by the outer [`ProductPageComponent`][src-product-page-component-ts].
Note: [`ProductDetailComponent`](../../src/app/pages/product/product-detail/product-detail.component.html) is only used for layout and styling, whereas the context is provided by the outer [`ProductPageComponent`][src-product-page-component-ts].

### by providing [`ProductContextFacade`][src-product-context-facade]
### By Providing [`ProductContextFacade`][src-product-context-facade]

There are cases, where it is not possible to use the directive.
For example, if the parent component does not have access to all required information, or the component has to introduce another context by itself.
There are cases for which it is not possible to use the directive: For example, when the parent component does not have access to all required information or when the component has to introduce another context by itself.
In this case the [`ProductContextFacade`][src-product-context-facade] has to be added to the `providers` array of the [`@Component`](https://angular.io/api/core/Component) decorator.
Afterwards, the sku for the context has to be initialized:
Afterwards, the SKU for the context has to be initialized:

```typescript
@Component({
Expand All @@ -78,18 +77,18 @@ export class MyComponent implements OnInit {
}
```

### by providing [`SelectedProductContextFacade`][src-selected-product-context-facade]
### By Providing [`SelectedProductContextFacade`][src-selected-product-context-facade]

For pages, that are using the `:sku` route parameter, the Product Context can be introduced on the page level by using [`SelectedProductContextFacade`][src-selected-product-context-facade].
For pages that use the `:sku` route parameter, the product context can be introduced on page level by using [`SelectedProductContextFacade`][src-selected-product-context-facade].

Have a look at [`ProductPageComponent`][src-product-page-component-ts] for an example.

## Retrieving Data from the Product Context

### inject [`ProductContextFacade`][src-product-context-facade]
### Inject [`ProductContextFacade`][src-product-context-facade]

The easiest way to interact with the context is by doing the same you would do with facades.
Inject the [`ProductContextFacade`][src-product-context-facade] into your components and relay data for the template into Observables and use the [async pipe](https://angular.io/guide/observables-in-angular#async-pipe) there:
The easiest way to interact with the context is to do the same as you would do with facades.
Inject the [`ProductContextFacade`][src-product-context-facade] into your components and relay data for the template into observables and use the [async pipe](https://angular.io/guide/observables-in-angular#async-pipe) there:

```typescript
@Component({ ... })
Expand All @@ -112,9 +111,9 @@ export class MyComponent implements OnInit {
<ng-container *ngIf="available$ | async">...</ng-container>
```

### use [`ProductContextAccessDirective`][src-product-context-access-directive]
### Use [`ProductContextAccessDirective`][src-product-context-access-directive]

If access to the context is required on the template without injecting it into the component (i.e. when the component has multiple embedded contexts), the [`ProductContextAccessDirective`][src-product-context-access-directive] can be used:
If access to the context is required in the template without injecting it into the component (i.e. if the component has multiple embedded contexts), the [`ProductContextAccessDirective`][src-product-context-access-directive] can be used:

```html
<ng-container *ngFor="let item of lineItems$ | async">
Expand All @@ -133,19 +132,19 @@ This feature should only be used for edge cases, as it is very verbose and most

## Linking Embedded Contexts

There are cases where Product Contexts are used as meta contexts for handling add-to-cart functionality and validations thereof.
For [product retail sets](https://intershoppwa.azurewebsites.net/skuM4548736000919) the surrounding product context is used as a meta context with two add-to-cart buttons (one on the detail on top, one at the button after the listing for contained items).
There are cases where product contexts are used as meta contexts for handling add-to-cart functionality and validations thereof.
For [product retail sets](https://intershoppwa.azurewebsites.net/skuM4548736000919) the surrounding product context is used as a meta context with two add-to-cart buttons (one at the detail on top, one at the button after the listing for contained items).
If those buttons are pressed, the correct amount for quantities is used to perform the add-to-cart action.
Those buttons also disable themselves if the quantity of one individual retail set part is going over the maximum allowed order quantity.
Those buttons also disable themselves if the quantity of one individual retail set part exceeds the maximum allowed order quantity.

All of this is also handled in the [`ProductContextFacade`][src-product-context-facade] if the embedded contexts are initialized using [`ProductContextDirective`][src-product-context-directive] and properly mapped `propagateIndex`.

Currently this feature is only used for enabling or disabling add-to-cart functionality, though.

## Customizing Display Properties

Product Context also contain all logic for deciding if specific functionality is available for each individual product.
Each component handling items of this configuration check if they are active themselves.
Product contexts also contain all logic for deciding if specific functionality is available for each individual product.
Each component that handles items of this configuration checks if they are active themselves.

This functionality can be customized by changing the [`defaultDisplayProperties`][src-product-context-facade].

Expand Down

1 comment on commit d2c40cd

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Azure Demo Servers are available:

Please sign in to comment.