Merge pull request #1085 from searchspring/develop

Release 0.57.0

docs/INTEGRATION_CONTEXT.md

@@ -10,16 +10,17 @@ There are a few core context variables utilized by Snap, `shopper`, `merchandisi
 |---|---|:---:|---|
 | shopper.id | logged in user unique identifier | all | required for personalization functionallity |
 | shopper.cart | array of cart objects, each object in the array can contain `sku` and/or `childSku` | all | current cart contents, required if checkout process does not contain a dedicated cart page (ie. slideout cart) |
+| currency.code | currency code string, ie. 'EUR' (ISO 4217) | all | currency code of the shopper's cart contents or order confirmation. Used for beacon events containing pricing data |
 | merchandising.segments | array of strings used for merchandising | any | segmented merchandising allows for custom control over products returned on search requests and must also be setup within the Searchspring Management Console (SMC) |
 | config | object containing Snap configurations | any | advanced usage of Snap (not recommended for standard integrations) |
 
 ## Examples
 
-The custom variable example below shows a custom context being added for 'region'. The value would typically be assigned server side using template logic. This would be used to possibly toggle the siteId utilized by the client (to fetch different catalog data) or to modify text or currency displays.
+The custom variable example below shows a custom context being added for 'page'. The value would typically be assigned server side using template logic. This would be used to possibly toggle the siteId utilized by the client (to fetch different catalog data) or to modify text or currency displays.
 
 ```html
 <script src="https://snapui.searchspring.io/[your_site_id]/bundle.js">
-	region = "US";
+	page = "404";
 </script>
 ```
 
@@ -36,6 +37,9 @@ When used, shopper context should always include at least an `id`; the `cart` co
 			}
 		]
 	};
+	currency = {
+		code: 'EUR'
+	};
 </script>
 ```
 
@@ -53,12 +57,15 @@ Example using multiple context variables together.
 
 ```html
 <script src="https://snapui.searchspring.io/[your_site_id]/bundle.js">
-	region = "CAD";
+	page = "404";
 	shopper = {
 		id: '[email protected]'
 	};
 	merchandising = {
 		segments: ['country:canada']
 	};
+	currency = {
+		code: 'EUR'
+	};
 </script>
 ```

docs/INTEGRATION_RECOMMENDATIONS.md

@@ -22,7 +22,7 @@ Context variables may be applied to individual recommendation profiles similar t
 | options.brands | array of brand strings | all | optional brand identifiers used in brand trending recommendation profiles |
 | options.branch | template branch overwrite | all | optional branch overwrite for recommendations template (advanced usage) |
 | options.filters | array of filters | all | optional recommendation filters |
-| options.realtime | boolean | all | optional update recommendations if cart contents change (requires [cart attribute tracking](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION.md)) |
+| options.realtime | boolean | all | optional update recommendations if cart contents change (requires [cart attribute tracking](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_TRACKING.md)) |
 | options.blockedItems | array of strings | all | SKU values to identify which products to exclude from the response |
 | options.batched | boolean (default: `true`)| all | only applies to recommendation context, optional disable profile from being batched in a single request, can also be set globally [via config](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Recommendation) | 
 | options.order | number | all | optional order number for recommendation params to be added to the batched request. Profiles that do not specify an order will be placed at the end, in the occurrence they appear in the DOM.

docs/INTEGRATION_TRACKING.md

@@ -93,7 +93,9 @@ Tracks order transaction. Should be invoked from an order confirmation page. Exp
 
 `order.id` - (optional) order id
 
-`order.otal` - (optional) sub total of all items
+`order.total` - (optional) transaction total of all items after tax and shipping
+
+`order.transactionTotal` - (optional) transaction total of all items before tax and shipping
 
 `order.city` - (optional) city name
 
@@ -107,7 +109,8 @@ Tracks order transaction. Should be invoked from an order confirmation page. Exp
 <script type="searchspring/track/order/transaction">
 	order = {
 		id: '123456',
-		total: '31.97',
+		total: '34.29',
+		transactionTotal: '31.97',
 		city: 'Los Angeles',
 		state: 'CA',
 		country: 'US',
@@ -135,7 +138,8 @@ Alternatively, this can also be integrated using the `searchspring.tracker.track
 searchspring.tracker.track.order.transaction({
 	order: {
 		id: '123456',
-		total: '31.97',
+		total: '34.29',
+		transactionTotal: '31.97',
 		city: 'Los Angeles',
 		state: 'CA',
 		country: 'US',

packages/snap-controller/src/Autocomplete/README.md

@@ -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 | used to set the field in which to grab the variant data from | ➖ |   | 
+| settings.variants.realtime.enabled | enable real time variant updates | ➖ |   | 
+| settings.variants.realtime.filters | specify which filters to use to determine which results are updated | ➖ |   | 
+| settings.variants.options | object keyed by individual option field values for configuration of any option settings  | ➖ |   | 
 
 <br>
 
@@ -120,4 +124,66 @@ 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 name for configuration of any option settings.
+
+| option | description | default value | required | 
+|---|---|:---:|:---:|
+| label | allows for changing the label of the option - (color -> colour) | ➖ |   | 
+| preSelected | array of option values to preselect - ['red','blue'] | ➖ |   | 
+| thumbnailBackgroundImages | boolean used for setting 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  | ➖ |   | 
+
+```jsx
+const config = {
+	settings:  {
+		variants: {
+			field: "ss__variants",
+			options: {
+				color: {
+					label: "Colour",
+					preSelected: ['transparent'],
+					mappings: {
+						red: {
+							label: 'Cherry',
+							backroundImageUrl: '/images/cherry.png'
+						},
+						blue: {
+							label: "Sky",
+							background: "teal",
+						}
+					}
+				}
+			}
+		}
+	}	
+}
+```
+### 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. 
+

packages/snap-controller/src/Recommendation/README.md

@@ -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 | used to set the field in which to grab the variant data from | ➖ |   | 
+| settings.variants.realtime.enabled | enable real time variant updates | ➖ |   | 
+| settings.variants.realtime.filters | specify which filters to use to determine which results are updated | ➖ |   | 
+| settings.variants.options | object keyed by option individual option field values for configuration of any option settings  | ➖ |   | 
 <br>
 
 ```typescript
@@ -102,4 +105,68 @@ 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 name for configuration of any option settings.
+
+| option | description | default value | required | 
+|---|---|:---:|:---:|
+| label | allows for changing the label of the option - (color -> colour) | ➖ |   | 
+| preSelected | array of option values to preselect - ['red','blue'] | ➖ |   | 
+| thumbnailBackgroundImages | boolean used for setting 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  | ➖ |   | 
+
+```jsx
+const config = {
+	settings:  {
+		variants: {
+			field: "ss__variants",
+			options: {
+				color: {
+					label: "Colour",
+					preSelected: ['transparent'],
+					mappings: {
+						red: {
+							label: 'Cherry',
+							backroundImageUrl: '/images/cherry.png'
+						},
+						blue: {
+							label: "Sky",
+							background: "teal",
+						}
+					}
+				}
+			}
+		}
+	}	
+}
+```
+
+### 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. 
+

packages/snap-controller/src/Search/README.md

@@ -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 | used to set the field in which to grab the variant data from | ➖ |   | 
+| settings.variants.realtime.enabled | enable real time variant updates | ➖ |   | 
+| settings.variants.realtime.filters | specify which filters to use to determine which results are updated | ➖ |   | 
+| 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
@@ -250,3 +255,67 @@ 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 name for configuration of any option settings.
+
+| option | description | default value | required | 
+|---|---|:---:|:---:|
+| label | allows for changing the label of the option - (color -> colour) | ➖ |   | 
+| preSelected | array of option values to preselect - ['red','blue'] | ➖ |   | 
+| thumbnailBackgroundImages | boolean used for setting 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  | ➖ |   | 
+
+```jsx
+const config = {
+	settings:  {
+		variants: {
+			field: "ss__variants",
+			options: {
+				color: {
+					label: "Colour",
+					preSelected: ['transparent'],
+					mappings: {
+						red: {
+							label: 'Cherry',
+							backroundImageUrl: '/images/cherry.png'
+						},
+						blue: {
+							label: "Sky",
+							background: "teal",
+						}
+					}
+				}
+			}
+		}
+	}	
+}
+```
+
+### 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. 
+

packages/snap-platforms/bigcommerce/README.md

@@ -21,7 +21,7 @@ export const AddToCart = (props) => {
 ```
 
 ## AddToCart
-The `addToCart` function will automatically add products to the cart and then redirect to the cart page (`/cart.php`). The function is async, and takes an array of products (Result Store References) to add, and an optional config. The optional config can take two optional properties, `redirect` and `idFieldName`. 
+The `addToCart` function will automatically add products to the cart and then redirect to the cart page (`/cart.php`). The function is async, and takes an array of products (Result Store References) to add, and an optional config. The optional config can take two optional properties, `redirect` and `idFieldName`. Snap variants must be enabled for full functionality.
 
 The `redirect` property can be set to `false` or supplied with an alternate redirect URL instead of the default (`/cart.php`). 
 

packages/snap-platforms/magento2/README.md

@@ -21,7 +21,7 @@ export const AddToCart = (props) => {
 ```
 
 ## AddToCart
-The `addToCart` function will automatically add products to the cart and then redirect to the cart page (`/checkout/cart/`). The function is async, and takes an array of products (Result Store References) to add, and an optional config. The optional config can take several optional properties, `redirect`, `idFieldName`, `formKey`, and `uenc`.
+The `addToCart` function will automatically add products to the cart and then redirect to the cart page (`/checkout/cart/`). The function is async, and takes an array of products (Result Store References) to add, and an optional config. The optional config can take several optional properties, `redirect`, `idFieldName`, `formKey`, and `uenc`. Snap variants must be enabled for full functionality.
 
 The `redirect` property can be set to `false` or supplied with an alternate redirect URL instead of the default (`/checkout/cart/`). 
 

packages/snap-platforms/shopify/README.md

@@ -21,7 +21,7 @@ export const AddToCart = (props) => {
 ```
 
 ## AddToCart
-The `addToCart` function will automatically add products to the cart and then redirect to the cart page (`/cart`). The function is async, and takes an array of products (Result Store References) to add, and an optional config. The optional config can take two optional properties, `redirect` and `idFieldName`. 
+The `addToCart` function will automatically add products to the cart and then redirect to the cart page (`/cart`). The function is async, and takes an array of products (Result Store References) to add, and an optional config. The optional config can take two optional properties, `redirect` and `idFieldName`. Snap variants must be enabled for full functionality.
 
 The `redirect` property can be set to `false` or supplied with an alternate redirect URL instead of the default (`/cart`).