Skip to content

Commit

Permalink
docs(variant-controller-settings): adding docs for controller config …
Browse files Browse the repository at this point in the history
…variant settings
  • Loading branch information
chrisFrazier77 committed Jun 4, 2024
1 parent 5562d50 commit 2f82d14
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 3 deletions.
44 changes: 43 additions & 1 deletion packages/snap-controller/src/Autocomplete/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ The `AutocompleteController` is used when making queries to the API `autocomplet
| settings.history.showResults | if history limit is set and there is no input, the first term results will be displayed | false | |
| settings.redirects.merchandising | boolean to disable merchandising redirects when ac form is submitted | true | |
| settings.redirects.singleResult | enable redirect to product detail page if search yields 1 result count | false | |
| settings.variants.field | setting to set the field in which to grab the variant data from || |
| settings.variants.realtime.enabled | setting to enable real time variant updates || |
| settings.variants.realtime.filters | setting to allow filtering which results get the realtime updates || |
| settings.variants.options | object keyed by individual option field values for configuration of any option settings || |

<br>

Expand Down Expand Up @@ -120,4 +124,42 @@ autocompleteController.search();

### beforeSubmit
- Called with `eventData` = { controller, input }
- Invoked prior to submission of autocomplete search
- Invoked prior to submission of autocomplete search

## Variants

### Variant Options Configuration
The `settings.variants.options` is an object keyed by individual option field values for configuration of any option settings.

| option | description | default value | required |
|---|---|:---:|:---:|
| label | setting to change the label for the option - (color -> colour) || |
| preSelected | array of option values to preselect - ['red','blue'] || |
| thumbnailBackgroundImages | boolean setting to set the option background image as the variant thumbnail image || |
| mappings | object keyed by individual optionValues for mapping value attribute overrides || |
| mappings[optionValue].label | setting to override the value label || |
| mappings[optionValue].background | setting to override the value background || |
| mappings[optionValue].backgroundImageUrl | setting to override the value backgroundImageUrl || |


### Realtime Variants

#### Variant Option Attributes:
When `realtime` is enabled the attributes `ss-variant-option` and `ss-variant-option-selected` are queried for and used to determine current variant selection and to also attach click events to know when to adjust variant selections in the selection stores. These attributes are needed in order for realtime variants to work properly.

The attributes are to be added on each variant option in the platform product page main option buttons. The `ss-variant-option` attribute also expects a value of the option feild and option value seperated by a `:`.

```jsx
<div>
<a href="/products/tee--red" ss-variant-option="Color:red" ss-variant-option-selected>Red</a>
<a href="/products/tee--blue" ss-variant-option="Color:Blue">Blue</a>
<a href="/products/tee--green" ss-variant-option="Color:Green">Green</a>
<a href="/products/tee--yellow" ss-variant-option="Color:Yellow">Yellow</a>
</div>
```

### Variant Option filters:
When `realtime` is enabled, by default the realtime updates will apply to all results in the store that have matching options available. However if this is not desired behaviour you may pass an array of filters to `settings.variants.realtime.filters`.

Available filters include `first` and `unaltered`. The `first` filter will only update the first result in the store. The `unaltered` filter will update any result that has not yet been altered by the user.

46 changes: 44 additions & 2 deletions packages/snap-controller/src/Recommendation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,10 @@ The `RecommendationController` is used when making queries to the API `recommend
| batched | batch multiple recommendations into a single network request | true | |
| limit | maximum number of results to display, can also be set globally via globals | 20 | |
| globals | keys defined here will be passed to the [API request](https://snapi.kube.searchspring.io/api/v1/) (can overwrite global config)|| |

| settings.variants.field | setting to set the field in which to grab the variant data from || |
| settings.variants.realtime.enabled | setting to enable real time variant updates || |
| settings.variants.realtime.filters | setting to allow filtering which results get the realtime updates || |
| settings.variants.options | object keyed by option individual option field values for configuration of any option settings || |
<br>

```typescript
Expand Down Expand Up @@ -102,4 +105,43 @@ recommendationController.init();

### track.render
- Called with `eventData` = { controller, trackEvent }
- Always invoked after `track.render()` method has been invoked
- Always invoked after `track.render()` method has been invoked


## Variants

### Variant Options Configuration
The `settings.variants.options` is an object keyed by individual option field values for configuration of any option settings.

| option | description | default value | required |
|---|---|:---:|:---:|
| label | setting to change the label for the option - (color -> colour) || |
| preSelected | array of option values to preselect - ['red','blue'] || |
| thumbnailBackgroundImages | boolean setting to set the option background image as the variant thumbnail image || |
| mappings | object keyed by individual optionValues for mapping value attribute overrides || |
| mappings[optionValue].label | setting to override the value label || |
| mappings[optionValue].background | setting to override the value background || |
| mappings[optionValue].backgroundImageUrl | setting to override the value backgroundImageUrl || |


### Realtime Variants

#### Variant Option Attributes:
When `realtime` is enabled the attributes `ss-variant-option` and `ss-variant-option-selected` are queried for and used to determine current variant selection and to also attach click events to know when to adjust variant selections in the selection stores. These attributes are needed in order for realtime variants to work properly.

The attributes are to be added on each variant option in the platform product page main option buttons. The `ss-variant-option` attribute also expects a value of the option feild and option value seperated by a `:`.

```jsx
<div>
<a href="/products/tee--red" ss-variant-option="Color:red" ss-variant-option-selected>Red</a>
<a href="/products/tee--blue" ss-variant-option="Color:Blue">Blue</a>
<a href="/products/tee--green" ss-variant-option="Color:Green">Green</a>
<a href="/products/tee--yellow" ss-variant-option="Color:Yellow">Yellow</a>
</div>
```

### Variant Option filters:
When `realtime` is enabled, by default the realtime updates will apply to all results in the store that have matching options available. However if this is not desired behaviour you may pass an array of filters to `settings.variants.realtime.filters`.

Available filters include `first` and `unaltered`. The `first` filter will only update the first result in the store. The `unaltered` filter will update any result that has not yet been altered by the user.

44 changes: 44 additions & 0 deletions packages/snap-controller/src/Search/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,15 @@ The `SearchController` is used when making queries to the API `search` endpoint.
| settings.history.max | how many search terms should be kept in the history store | 25 | |
| settings.history.url | allows for adjust the root URL for history store terms (default is relative URLs) || |
| settings.pagination.pageSizeOptions | setting to change the page size options available || |
| settings.variants.field | setting to set the field in which to grab the variant data from || |
| settings.variants.realtime.enabled | setting to enable real time variant updates || |
| settings.variants.realtime.filters | setting to allow filtering which results get the realtime updates || |
| settings.variants.options | object keyed by option individual option field values for configuration of any option settings || |
| settings.infinite | enable infinite scrolling by setting to empty object || |
| settings.infinite.backfill | number of pages allowed for backfill || |
| settings.restorePosition.enabled | boolean to enable/disable using `restorePosition` event middleware to restore the window scroll position when navigating back to previous page (when using infinite this is automatically set to true) | false | |
| settings.restorePosition.onPageShow | boolean to enable/disable having restorePosition occur on the 'pageshow' window event (requires `restorePosition.enable`) | false | |

<br>

```typescript
Expand Down Expand Up @@ -250,3 +255,42 @@ export class Content extends Component {
- Called with `eventData` = { controller, event, result, trackEvent }
- Always invoked after `track.product.click()` method has been invoked
- Allows for adding custom product click events (ie. Google Analytics)


## Variants

### Variant Options Configuration
The `settings.variants.options` is an object keyed by individual option field values for configuration of any option settings.

| option | description | default value | required |
|---|---|:---:|:---:|
| label | setting to change the label for the option - (color -> colour) || |
| preSelected | array of option values to preselect - ['red','blue'] || |
| thumbnailBackgroundImages | boolean setting to set the option background image as the variant thumbnail image || |
| mappings | object keyed by individual optionValues for mapping value attribute overrides || |
| mappings[optionValue].label | setting to override the value label || |
| mappings[optionValue].background | setting to override the value background || |
| mappings[optionValue].backgroundImageUrl | setting to override the value backgroundImageUrl || |


### Realtime Variants

#### Variant Option Attributes:
When `realtime` is enabled the attributes `ss-variant-option` and `ss-variant-option-selected` are queried for and used to determine current variant selection and to also attach click events to know when to adjust variant selections in the selection stores. These attributes are needed in order for realtime variants to work properly.

The attributes are to be added on each variant option in the platform product page main option buttons. The `ss-variant-option` attribute also expects a value of the option feild and option value seperated by a `:`.

```jsx
<div>
<a href="/products/tee--red" ss-variant-option="Color:red" ss-variant-option-selected>Red</a>
<a href="/products/tee--blue" ss-variant-option="Color:Blue">Blue</a>
<a href="/products/tee--green" ss-variant-option="Color:Green">Green</a>
<a href="/products/tee--yellow" ss-variant-option="Color:Yellow">Yellow</a>
</div>
```

### Variant Option filters:
When `realtime` is enabled, by default the realtime updates will apply to all results in the store that have matching options available. However if this is not desired behaviour you may pass an array of filters to `settings.variants.realtime.filters`.

Available filters include `first` and `unaltered`. The `first` filter will only update the first result in the store. The `unaltered` filter will update any result that has not yet been altered by the user.

0 comments on commit 2f82d14

Please sign in to comment.