### Client Configuration Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-client/README.md

Example of client configuration, including cache settings.

```js
type ClientConfig = {
	mode?: keyof typeof AppMode | AppMode;
	initiator?: string;
	fetchApi?: WindowOrWorkerGlobalScope['fetch'];
	meta?: RequesterConfig<MetaRequestModel, MetaRequesterPaths>;
	search?: RequesterConfig<SearchRequestModel, SearchRequesterPaths>; // also used by autocomplete, category, and finder
	recommend?: RequesterConfig<RecommendRequestModel, RecommendRequesterPaths>;
	suggest?: RequesterConfig<SuggestRequestModel, SuggestRequesterPaths>; // also used by trending
};

type RequesterConfig<RequestType, PathConfigurationType> = {
	origin?: string;
	headers?: HTTPHeaders;
	cache?: CacheConfig;
	globals?: Partial<RequestType>;
	paths?: Partial<PathConfigurationType>;
};

type CacheConfig = {
	enabled?: boolean;
	ttl?: number;
	maxSize?: number;
	purgeable?: boolean;
	entries?: { [key: string]: Response };
};
```

--------------------------------

### Install Snap Javascript Client

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-client/README.md

Install the Snap Javascript Client using npm.

```bash
npm install --save @athoscommerce/snap-client
```

--------------------------------

### SearchController Configuration Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/README.md

An example demonstrating how to configure a SearchController with specific context, configuration, and targets.

```javascript
const config = {
	controllers: {
		search: [
			{
				context: searchContext,
				config: {
					id: 'search',
				},
				targets: [
					{
						selector: '#athos-content',
						component: () => Content,
						hideTarget: true,
					},
					{
						selector: '#athos-sidebar',
						component: () => Sidebar,
						hideTarget: true,
					},
				],
				services: {}
			}
		]
	}
}
```

--------------------------------

### Install Snap Toolbox

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-toolbox/README.md

Install the Snap Toolbox package using npm.

```bash
npm install --save @athoscommerce/snap-toolbox
```

--------------------------------

### Install Dependencies

Source: https://github.com/athoscommerce/snap/blob/main/packages/snapps/README.md

Run these commands from the main directory to install implementation dependencies. Ensure Snap package versions align with the mono repo.

```bash
npm run clean && npm install
```

--------------------------------

### Install Dependencies

Source: https://github.com/athoscommerce/snap/blob/main/README.md

Installs all project dependencies from the repository root.

```shell
npm install
```

--------------------------------

### Complete Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-toolbox/src/DomTargeter/README.md

Demonstrates the initialization of the DomTargeter with multiple target configurations and an `onTarget` callback for rendering components.

```APIDOC
## Complete Example

```js
import { DomTargeter } from '@athoscommerce/snap-toolbox';
import { render } from 'preact';

const targeter = new DomTargeter(
	[
		{
			selector: '#athos-content',
			component: <SearchResults />,
			hideTarget: true,
			autoRetarget: true,
			clickRetarget: true,
			navigationRetarget: true,
			unsetTargetMinHeight: true
		},
		{
			selector: '#athos-sidebar',
			component: <Filters />,
			inject: {
				action: 'prepend',
				element: (target, originalElem) => {
					const wrapper = document.createElement('div');
					wrapper.className = 'ss-filters-wrapper';
					return wrapper;
				}
			},
			hideTarget: true,
			clickRetarget: '.apply-filters'
		}
	],
	(target, elem, originalElem) => {
		render(target.component, elem);
	}
);

// Later, manually retarget if needed
targeter.retarget();
```
```

--------------------------------

### Install Snap Preact

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/README.md

Install the snap-preact package and its dependencies using npm.

```bash
npm install --save @athoscommerce/snap-preact
```

--------------------------------

### Install Snapfu CLI

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_SETUP.md

Install the Snapfu CLI globally using npm. Ensure you are using Node v24+ and npm v10+.

```sh
npm install -g snapfu
```

--------------------------------

### Full HTML Integration Example

Source: https://github.com/athoscommerce/snap/blob/main/docs/BUILD_DEPLOY_INTEGRATION.md

An example of a complete HTML document structure showing the correct placement of the Athos Commerce Snap script tag within the <head> section.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Snap Integration Example</title>

    <script src="https://snapui.athoscommerce.io/[your_site_id]/bundle.js" id="athos-context">
        // context variables go here
    </script>
</head>
<body>
    <div id="athos-content"><!-- an element that will be injected into --></div>
</body>
</html>
```

--------------------------------

### Complete DomTargeter Initialization Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-toolbox/src/DomTargeter/README.md

An example demonstrating the initialization of DomTargeter with multiple targets, including configurations for click and navigation retargeting, and custom injection logic.

```javascript
import { DomTargeter } from '@athoscommerce/snap-toolbox';
import { render } from 'preact';

const targeter = new DomTargeter(
	[
		{
			selector: '#athos-content',
			component: <SearchResults />,
			hideTarget: true,
			autoRetarget: true,
			clickRetarget: true,
			navigationRetarget: true,
			unsetTargetMinHeight: true
		},
		{
			selector: '#athos-sidebar',
			component: <Filters />,
			inject: {
				action: 'prepend',
				element: (target, originalElem) => {
					const wrapper = document.createElement('div');
					wrapper.className = 'ss-filters-wrapper';
					return wrapper;
				}
			},
			hideTarget: true,
			clickRetarget: '.apply-filters'
		}
	],
	(target, elem, originalElem) => {
		render(target.component, elem);
	}
);

// Later, manually retarget if needed
targeter.retarget();
```

--------------------------------

### Install Athos Snap Package

Source: https://github.com/athoscommerce/snap/blob/main/docs/REFERENCE_MIGRATION.md

Install the new Athos Snap package. It includes Preact, MobX, and MobX-react-lite as dependencies.

```sh
npm install @athoscommerce/snap-preact
```

--------------------------------

### Cache Configuration Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-client/README.md

Demonstrates cache configuration options including enabled, ttl, maxSize, purgeable, and entries.

```js
const metaResponse = {
    "facets": {
        "brand": {
            "display": "list",
            "label": "Brand",
            "collapsed": false,
            "multiple": "or"
        },
        "collection": {
            "display": "list",
            "label": "Collection",
            "collapsed": false,
            "multiple": "or"
        },
        "color_family": {
            "display": "palette",
            "label": "Color",
            "collapsed": false,
            "multiple": "or"
        }
    },
    "sortOptions": [
        {
            "type": "relevance",
            "field": "relevance",
            "direction": "desc",
            "label": "Best Match"
        },
        {
            "type": "field",
            "field": "sales_rank",
            "direction": "desc",
            "label": "Most Popular"
        }
    ]
};

const metaKey = `/v1/meta{\"siteId\":\"atkzs2\"}`;

const clientConfig = {
  search: {
    cache: {
      entries: {
        [metaKey]: metaResponse
      }
    }
  }
}

const client = new Client(globals, clientConfig);

const response = await client.search({
  search: {
    query: {
      string: 'dress'
    }
  }
});
```

--------------------------------

### Initialize Snap and Get Controller

Source: https://github.com/athoscommerce/snap/blob/main/docs/REFERENCE_CONFIGURATION.md

Demonstrates how to instantiate the Snap class with a configuration object and then retrieve a specific controller, such as the search controller, asynchronously.

```javascript
const snap = new Snap(config);
snap.getController('search').then((search) => {
	// do things with controller
});
```

--------------------------------

### Advanced Snap Configuration Example

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_FOREGROUND_FILTERS.md

Demonstrates how to configure Snap with advanced settings, including custom ignore parameters and state actions for specific filters.

```javascript
const config = {
	client: {
		globals: {
			siteId: 'REPLACE_WITH_YOUR_SITE_ID',
		},
	},
	controllers: {
		search: [
			{
				url: {
					initial: {
						settings: {
							ignoreParameters: ['query', 'tag', 'filter'],
							useDefaultIgnoreParameters: false,
						},
						parameters: {
							filter: {
								useGlobalIgnoreParameters: true,
								action: 'set',
								state: {
									on_sale: ['yes'],
								}
							},
						},
					}
				},
				config: {
					id: 'search',
				},
			},
		],
	},
};

const snap = new Snap(config);
```

--------------------------------

### Install Peer Dependencies

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/README.md

Install the required peer dependencies for Snap Preact: preact and mobx. Mobx-react-lite is optional.

```bash
npm install --save preact mobx
```

--------------------------------

### Full Snap Preact Configuration Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/README.md

A comprehensive configuration object for Snap Preact, defining context, client, controllers, and targets.

```javascript
const config = {
	context: globalContext,
	url: {
		parameters: {
			core: {
				query: { name: 'search' },
			},
		},
	},
	client: {
		globals: {
			siteId: 'REPLACE_WITH-YOUR_SITE_ID',
		},
	},
	controllers: {
		search: [
			{
				config: {
					id: 'search',
					settings: {
						redirects: {
							merchandising: false,
						},
					},
				},
			targets: [
				{
					selector: '#athos-content',
					component: () => Content,
					hideTarget: true,
				},
				{
					selector: '#athos-sidebar',
					component: () => Sidebar,
					hideTarget: true,
				},
			],
			},
		],
		autocomplete: [
			{
				config: {
					id: 'autocomplete',
					selector: 'input.athos-ac',
					settings: {
						trending: {
							limit: 5,
						},
					},
				},
			targets: [
				{
					selector: 'input.athos-ac',
					component: () => Autocomplete,
					hideTarget: true,
				},
			],
			},
		],
	},
};
```

--------------------------------

### Initialize New Snap Project

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_SETUP.md

Initialize a new Snap project using the Snapfu CLI. This command creates a project directory, installs dependencies, and prompts for your Site ID and secret key.

```sh
snapfu init [projectname]
cd [projectname] && npm install
```

--------------------------------

### Product Attributes Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-store-mobx/src/Search/README.md

An example of the 'attributes' object for a product, showcasing various indexed and enabled properties such as intellisuggest data, pricing, keywords, color, description, and category hierarchy.

```json
"attributes": {
	"intellisuggestData": "eJwrTs4tNM9jYGBw1nV00Q031DW0MLMMYDAEQmMDBhMTMwOG9KLMFACyXAiS",
	"intellisuggestSignature": "25f3b12a880fa4342274c97a9c105f0736c026e71b12ca0a7b297e357b099b7d",
	"ss_insights_quadrant": "Best Performer",
	"gross_margin": "70",
	"ss_product_type": "Dress",
	"keywords": [
		"off the shoulder",
		"striped",
		"stripes",
		"stripe",
		"open shoulder",
		"open back",
		"preppy",
		"seersucker",
		"white",
		"white dress",
		"white",
		"summer",
		"spring"
	],
	"color": [
		"White",
		"Navy",
		"Cream"
	],
	"dress_length_name": "Mini",
	"multi_colors": "yes",
	"pattern": "Stripe",
	"description": "Are you Stripe Out of ideas for what to wear this weekend on that trip you've got coming up with your friends? Afraid you'll be the odd one out and everyone else will be all cute and trendy and there you'll be ... not trendy and wearing the same old things you've been wearing on this annual getaway for years? Lucky for you, here's the dress you've been searching for. Doesn't matter what else you pack (it does, you'll want to continue to shop with us, we were just being nice) this is the piece that will set you apart from everyone else (that is absolutely true, you will be a Goddess among women). Take that, bad fashion moments of the past! Striped dress features 3/4 sleeve bell sleeves with a partially elastic/open back. Model is wearing a small. • 97% Cotton 3% Spandex • Machine Wash Cold • Lined • Made in the USA",
	"title": "Stripe Out White Off-The-Shoulder Dress",
	"ss_clicks": "4141",
	"saturation": "low",
	"color_family": [
		"White"
	],
	"sales_rank": "4461",
	"ss_sale_price": "48",
	"season": "Summer",
	"ss_category_hierarchy": [
		"Shop By Trend",
		"All Dresses",
		"All Dresses&gt;Casual Dresses",
		"Shop By Trend&gt;Spring Preview",
		"All Dresses&gt;Shop by Color",
		"All Dresses&gt;Print Dresses",
		"Gifts for Her",
		"Shop By Trend&gt;Off The Shoulder Trend",
		"Gifts for Her&gt;Gifts Under $50",
		"All Dresses&gt;Shop by Color&gt;White Dresses"
	],
	"on_sale": "No",
	"condition": "New",
	"product_type": [
		"All Dresses &gt; Shop by Color &gt; White Dresses",
		"All Dresses &gt; Shop by Color",
		"All Dresses &gt; Print Dresses",
		"Shop By Trend &gt; Off The Shoulder Trend",
		"Shop By Trend &gt; Spring Preview",
		"All Dresses &gt; Casual Dresses",
		"Gifts for Her",
		"Gifts for Her &gt; Gifts Under $50"
	],
	"brightness": "high",
	"size": [
		"Small",
		"Medium",
		"Large"
	],
	"material": "Cotton",
	"days_since_published": "8",
	"dress_length": "34",
	"size_dress": [
		"Small",
		"Medium",
		"Large"
	],
	"quantity_available": "13",
	"popularity": "4461",
	"product_type_unigram": "dress",
	"id": "7790a0f692035da40c8504e8b7a9f31d"
}
```

--------------------------------

### Core Product Mappings Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-store-mobx/src/Search/README.md

Illustrates the structure of the 'core' mappings for product results, including essential attributes like UID, price, and image URLs.

```json
"mappings": {
	"core": {
		"uid": "182146",
		"price": 48,
		"msrp": 50,
		"url": "/product/C-AD-W1-1869P",
		"thumbnailImageUrl": "https://searchspring-demo-content.s3.amazonaws.com/demo/fashion/product_images_thumb_med/4468_copyright_reddressboutique_2017__thumb_med.jpg",
		"imageUrl": "https://searchspring-demo-content.s3.amazonaws.com/demo/fashion/product_images_large/4468_copyright_reddressboutique_2017__large.jpg",
		"name": "Stripe Out White Off-The-Shoulder Dress",
		"sku": "C-AD-W1-1869P",
		"brand": "Adrienne"
	}
},
```

--------------------------------

### SearchController Middleware Example: Customizing Facet Descriptions

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-store-mobx/src/Search/README.md

Example of using a SearchController middleware to add custom descriptions to all facets.

```javascript
cntrlr.on('afterStore', async ({ controller }, next) => {
	controller.store.facets.forEach(facet => {
		facet.custom = { description: `Choose a ${facet.label}...`}
	})
	await next();
});

cntrlr.on('afterStore', async ({ controller }, next) => {
	const colorFacet = controller?.store?.facets.filter((facet) => facet.field == 'color_family').pop();
	colorFacet?.values.forEach((value) => {
		value.custom = {
			colorImage: `www.storfront.com/images/swatches/${value.value}.png`,
		};
	});

	await next();
});
```

--------------------------------

### Import Swatches Component

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/components/src/components/Molecules/Swatches/readme.md

Import the Swatches component from the library. This is a required setup step before using the component.

```tsx
import { Swatches } from '@athoscommerce/snap-preact/components';
```

--------------------------------

### Basic Layout Options Setup

Source: https://github.com/athoscommerce/snap/blob/main/docs/TEMPLATES_HOW_TO.md

Configure predefined result grid layouts with options for users to switch at runtime. Ensure the 'layoutSelector' widget is in a toolbar for overrides to apply.

```tsx
new SnapTemplates({
	...
	theme: {
		extends: 'pike',
		overrides: {
			default: {
				search: {
					layoutOptions: [
						{
							value: 1,
							label: '4 Wide',
							icon: 'layout-grid-4',
							default: true,
							overrides: {
								components: {
									'search results': {
										columns: 4,
									},
								},
							},
						},
						{
							value: 2,
							label: '3 Wide',
							icon: 'layout-grid-3',
							overrides: {
								components: {
									'search results': {
										columns: 3,
									},
								},
							},
						},
						{
							value: 3,
							label: '2 Wide',
							icon: 'layout-grid-2',
							overrides: {
								components: {
									'search results': {
										columns: 2,
									},
								},
							},
						},
					],
				},

				// Place the layoutSelector widget in the top toolbar
				'search toolbar.top': {
					layout: [
						['banner.header'],
						['searchHeader', '_', 'perPage', 'sortBy', 'layoutSelector'],
					],
				},

				// Optional: configure the selector appearance
				'search layoutSelector': {
					type: 'list',
					hideLabel: true,
					hideOptionLabels: true,
				},
			},
		},
	},
	...
});
```

--------------------------------

### Product Data Structure Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact-demo/public/snap/email.html

Illustrates the structure of product data used within the Snap email context, including core mappings and attributes.

```javascript
const results = [
  {
    id: "52079507984164",
    mappings: {
      core: {
        uid: "52079507984164",
        sku: "VW1982-AQZ-BL",
        available: true,
        name: "CoreMotion Quarter-Zip",
        url: "/products/coremotion-quarter-zip?variant=52079507984164",
        parentId: "14725170823534",
        parentImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Men_s_Apparel_CoreMotion_Quarter-Zip_-_Black_50309846-9427-409b-b945-eb4db81c0c19.png?v=1747685222",
        price: 45,
        imageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Men_s_Apparel_CoreMotion_Quarter-Zip_-_Black_50309846-9427-409b-b945-eb4db81c0c19_600x600.png?v=1747685222",
        secureImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Men_s_Apparel_CoreMotion_Quarter-Zip_-_Black_50309846-9427-409b-b945-eb4db81c0c19.png?v=1747685222",
        thumbnailImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Men_s_Apparel_CoreMotion_Quarter-Zip_-_Black_50309846-9427-409b-b945-eb4db81c0c19_600x600.png?v=1747685222",
        brand: "VersaWearCo",
        caption: "Captions!"
      },
      attributes: {
        collection_handle: [ "his", "theirs", "workout", "tops", "sweaters", "best-sellers", "all" ],
        color: [ "Black" ],
        product_type_unigram: "quarterzip",
        ss_image: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Men_s_Apparel_CoreMotion_Quarter-Zip_-_Black_50309846-9427-409b-b945-eb4db81c0c19_600x600.png?v=1747685222",
        title: "CoreMotion Quarter-Zip"
      },
      custom: {},
      quantity: 1
    }
  },
  {
    id: "52079545057646",
    mappings: {
      core: {
        uid: "52079545057646",
        sku: "VW1982-AQZ-AS",
        available: true,
        name: "Align Quarter-Zip",
        url: "/products/align-quarter-zip?variant=52079545057646",
        parentId: "14725170823534",
        parentImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Quarter-Zip_-_Ash_Grey_6d644d3e-7956-417f-90a3-5290b2764e78.png?v=1747685144",
        price: 45,
        imageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Quarter-Zip_-_Ash_Grey_6d644d3e-7956-417f-90a3-5290b2764e78_600x600.png?v=1747685144",
        secureImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Quarter-Zip_-_Ash_Grey_6d644d3e-7956-417f-90a3-5290b2764e78.png?v=1747685144",
        thumbnailImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Quarter-Zip_-_Ash_Grey_6d644d3e-7956-417f-90a3-5290b2764e78_600x600.png?v=1747685144",
        brand: "VersaWearCo",
        caption: "Captions!"
      },
      attributes: {
        collection_handle: [ "hers", "theirs", "winter-warmth", "tops", "sweaters", "best-sellers", "all" ],
        color: [ "Ash Grey" ],
        product_type_unigram: "quarterzip",
        ss_image: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Quarter-Zip_-_Ash_Grey_6d644d3e-7956-417f-90a3-5290b2764e78_600x600.png?v=1747685144",
        title: "Align Quarter-Zip"
      },
      custom: {},
      quantity: 1
    }
  },
  {
    id: "52079573696878",
    mappings: {
      core: {
        uid: "52079573696878",
        sku: "VW1982-ULE-CH",
        available: true,
        name: "Studio Legging",
        url: "/products/studio-legging?variant=52079573696878",
        parentId: "14725184192878",
        parentImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Studio_Legging_-_Charcoal_86731d52-9ef2-4663-802a-8935249c5a7c.png?v=1747685734",
        price: 46,
        imageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Studio_Legging_-_Charcoal_86731d52-9ef2-4663-802a-8935249c5a7c_600x600.png?v=1747685734",
        secureImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Studio_Legging_-_Charcoal_86731d52-9ef2-4663-802a-8935249c5a7c.png?v=1747685734",
        thumbnailImageUrl: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Studio_Legging_-_Charcoal_86731d52-9ef2-4663-802a-8935249c5a7c_600x600.png?v=1747685734",
        brand: "VersaWearCo",
        caption: "Captions!"
      },
      attributes: {
        collection_handle: [ "hers", "winter-warmth", "studio", "yoga", "pants-bottoms", "leggings", "all" ],
        color: [ "Charcoal" ],
        product_type_unigram: "legging",
        ss_image: "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Studio_Legging_-_Charcoal_86731d52-9ef2-4663-802a-8935249c5a7c_600x600.png?v=1747685734",
        title: "Studio Legging"
      },
      custom: {},
      quantity: 1
    }
  }
];
```

--------------------------------

### Custom Properties Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-toolbox/src/DomTargeter/README.md

Demonstrates passing custom properties like components and data to the targeter, which can be accessed in callbacks.

```javascript
{
	selector: '#content',
	component: <MyComponent />,
	customData: { theme: 'dark' },
	componentId: 'main-content'
}
```

--------------------------------

### Multiple Site IDs Configuration in package.json

Source: https://github.com/athoscommerce/snap/blob/main/docs/BUILD_DEPLOY.md

Example of configuring multiple site IDs within the 'athos' section of the package.json file.

```json
{
    ...
    "athos": {
        "siteId": {
            "abc123": {
                "name": "site1.com"
            },
            "def456": {
                "name": "site1.com.au"
            }
        },
    }
}
```

--------------------------------

### Install Athos Script for Search and Collections

Source: https://github.com/athoscommerce/snap/blob/main/docs/BUILD_DEPLOY_INTEGRATION_SHOPIFY.md

This snippet integrates both search and collections functionality. It includes shopper, collection, tags, template, and money format configurations.

```liquid
{%- if settings.athos_branch_name != blank -%}
	{% capture athos_branch_name %}/{{ settings.athos_branch_name }}{% endcapture %}
{%- endif -%}

{%- if customer -%}
	{% capture athos_shopper_config %} 
		shopper = { id: "{{ customer.id }}" };
	{% endcapture %}
{%- endif -%}

{% assign atho_defer_config = ' defer' %}
{%- if collection.handle and template contains 'collection' -%}
	{% assign atho_defer_config = '' %}
	{%- if collection.handle != settings.athos_collection_handle -%}
		{% capture athos_collection_config %} 
			collection = { id: "{{ collection.id }}", name: "{{ collection.title | replace: '"', '&quot;' }}", handle: "{{ collection.handle }}" };
		{% endcapture %}
	{%- endif -%}	
{%- endif -%}

{%- if current_tags -%}
	{% capture athos_tags_config %}
		tags = {{ current_tags | json }};
	{% endcapture %}
{%- endif -%}

{%- if template -%}
	{% capture athos_template_config %}
		template = "{{ template }}";
	{% endcapture -%}
{%- endif -%}

{% capture athos_money_config %}
	format = "{{ shop.money_format }}";
{% endcapture %}

{% comment %}Athos Script{% endcomment %}
<script src="https://snapui.athoscommerce.io/{{ settings.athos_site_id }}{{ athos_branch_name }}/bundle.js" id="athos-context"{{ atho_defer_config }}>
	{{ athos_shopper_config }}{{ athos_collection_config }}{{ athos_tags_config }}{{ athos_template_config }}{{ athos_money_config }}
</script>
```

--------------------------------

### Legacy Block Integration Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/src/Instantiators/README.md

Illustrates the legacy block integration style using individual script tags, each with a 'profile' attribute. Each script tag creates a separate recommendation controller.

```html
<script type="athos/recommend" profile="trending"></script>
<script type="athos/recommend" profile="similar">
	product = 'SKU-123';
</script>
```

--------------------------------

### Client Initialization with Globals

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-client/README.md

Demonstrates how to initialize the Snap Client with global configuration, including the required siteId and optional background filters.

```APIDOC
## Client Initialization with Globals

### Description
Initializes the Snap Client with global configuration parameters that apply to all subsequent requests. This includes the mandatory `siteId` and can also incorporate global filters, sorting, or merchandising segments.

### Usage
```js
const globals = {
  siteId: 'a1b2c3',
  filters: [
    {
      field: 'stock_status',
      value: 'yes',
      type: 'value',
      background: true
    }
  ]
};

const client = new Client(globals, clientConfig);
```

### Parameters
#### Globals
- **siteId** (string) - Required - The identifier for the site.
- **filters** (Array<Object>) - Optional - Global filters to apply to all requests.
```

--------------------------------

### Example Bundle Component Implementation

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_RECOMMENDATIONS.md

Implement a custom Bundle component using the RecommendationBundle from snap-preact/components. This component handles displaying bundled products and includes logic for adding items to the cart.

```jsx
// components/Recommendations/Bundled.jsx

import { h } from 'preact';
import { useEffect } from 'preact/hooks';
import { observer } from 'mobx-react-lite';
import { RecommendationBundle } from '@athoscommerce/snap-preact/components';

import './Bundled.scss';

const addToCart = (data) => {
	// handle adding products to the cart
};

export const Bundled = observer((props) => {
	const controller = props.controller;
	const store = controller?.store;

	useEffect(() => {
		if (!controller.store.loaded && !controller.store.loading) {
			controller.search();
		}
	}, []);

	const parameters = store?.profile?.display?.templateParameters;

	return store.results.length > 0 && <RecommendationBundle controller={controller} onAddToCart={(e, data) => addToCart(data)} title={parameters?.title} />;
});
```

--------------------------------

### Install Athos Script for Search Only

Source: https://github.com/athoscommerce/snap/blob/main/docs/BUILD_DEPLOY_INTEGRATION_SHOPIFY.md

Use this snippet if you are only integrating Search page functionality. It configures the Athos script with basic shopper and template information.

```liquid
{%- if settings.athos_branch_name != blank -%}
	{% capture athos_branch_name %}/{{ settings.athos_branch_name }}{% endcapture %}
{%- endif -%}

{%- if customer -%}
	{% capture athos_shopper_config %} 
		shopper = { id: "{{ customer.id }}" };
	{% endcapture %}
{%- endif -%}

{% assign atho_defer_config = ' defer' %}
{%- if collection.handle and template contains 'collection' and collection.handle == settings.athos_collection_handle -%}
	{% assign atho_defer_config = '' %}
{%- endif -%}

{%- if template -%}
	{% capture athos_template_config %}
		template = "{{ template }}";
	{% endcapture -%}
{%- endif -%}

{% capture athos_money_config %}
	format = "{{ shop.money_format }}";
{% endcapture %}

{% comment %}Athos Script{% endcomment %}
<script src="https://snapui.athoscommerce.io/{{ settings.athos_site_id }}{{ athos_branch_name }}/bundle.js" id="athos-context"{{ atho_defer_config }}>
	{{ athos_shopper_config }}{{ athos_template_config }}{{ athos_money_config }}
</script>
```

--------------------------------

### Placing a Profile in its Own Batch

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_RECOMMENDATIONS_LEGACY.md

Configure a recommendation profile to be in its own batch by setting 'batched: false'. This example isolates the 'quick-cart' profile.

```html
<script type="athos/personalized-recommendations" profile="bundle">
	products = ['product123'];
</script>

<script type="athos/personalized-recommendations" profile="quick-cart">
	products = ['product123'];
	options = {
		batched: false
	};
</script>
```

--------------------------------

### Initialize and Update RecommendationStore

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-store-mobx/src/Recommendation/README.md

Demonstrates how to initialize the RecommendationStore with configuration and a URL manager, and then update it with data. Ensure necessary imports are included.

```javascript
import { RecommendationStore } from '@athoscommerce/snap-store-mobx'
import { UrlManager, UrlTranslator } from '@athoscommerce/snap-url-manager';

const recommendationConfig = {
	id: 'recommendation',
	tag: 'also-bought'
};

const recommendationUrlManager = new UrlManager(new UrlTranslator()).detach(0);
const store = new RecommendationStore(recommendationConfig, { urlManager: recommendationUrlManager });

store.update(data);

console.log(store.toJSON());
```

--------------------------------

### Snap Logger Usage Examples

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-logger/README.md

Demonstrates various logging methods available through `controller.log`, including image, error, warn, imageText, debug, and formatted dev logs.

```javascript
controller.log.image({
	url: 'https://searchspring.com/wp-content/uploads/2020/01/SearchSpring-Primary-FullColor-800-1-1-640x208.png',
	width: '90px',
	height: '30px'
});

controller.log.error('error');

controller.log.warn('warn');

controller.log.imageText({
	url: 'https://searchspring.com/wp-content/themes/SearchSpring-Theme/dist/images/favicons/favicon.svg',
}, 'imageText');

controller.log.debug('debug');

controller.log.dev(`%c ${controller.log.emoji.vortex} %c${controller.log.prefix}%c${'magical text'}`, 
`color: ${controller.log.colors.blue}; font-weight: bold; font-size: 10px; line-height: 12px;`,
`color: ${controller.log.colors.bluegreen}; font-weight: normal;`,
`color: ${controller.log.colors.bluegreen}; font-weight: bold;`);
```

--------------------------------

### Merchandising Campaigns Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-store-mobx/src/Search/README.md

An example of the structure for merchandising campaign objects returned by the Search API.

```javascript
[
	{
		id: "144744",
		title: "Global Campaign (In stock, new, season, best selling)",
		type: "global"
	},
	{
		id: "119988",
		title: "DND: Location and Inline: United States - Free Shipping ",
		type: "location"
	}
]
```

--------------------------------

### Custom Plugin Configuration Example

Source: https://github.com/athoscommerce/snap/blob/main/docs/TEMPLATES_PLUGINS.md

Demonstrates how to define and configure custom plugins for logging and analytics. Custom plugins require a 'function' property to hook into controller events and can accept additional arguments via 'args'.

```tsx
import { SnapTemplates } from '@athoscommerce/snap-preact';
import type { SnapTemplatesConfigUnlocked } from '@athoscommerce/snap-preact';

const config: SnapTemplatesConfigUnlocked = {
	unlocked: true,
	config: {
		siteId: '8uyt2m',
		platform: 'other',
	},
	plugins: {
		custom: {
			myLoggingPlugin: {
				function: (controller) => {
					controller.on('afterStore', async ({ controller }: { controller: SearchController }, next) => {
						console.log('Search completed:', controller.store.results);
						await next();
					});
				},
			},
			myAnalyticsPlugin: {
				function: (controller) => {
					controller.on('afterSearch', async ({ controller }: { controller: AutocompleteController }, next) => {
						// Send analytics event
						analytics.track('search', { query: controller.store.search?.query?.string });
						await next();
					});
				},
			},
		},
	},
	theme: {
		extends: 'pike',
	},
	// ...
};

new SnapTemplates(config);
```

--------------------------------

### Middleware Execution Order Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-event-manager/README.md

Demonstrates the execution flow of multiple middleware functions attached to the same event. Control passes sequentially through 'next()' calls and returns in reverse order.

```javascript
controller.eventManager.on('interestingEvent', async (data, next) => {
	console.log('first middleware start');
	await next();
	console.log('first middleware end');
});

controller.eventManager.on('interestingEvent', async (data, next) => {
	console.log('second middleware start');
	await next();
	console.log('second middleware end');
});

controller.eventManager.on('interestingEvent', async (data, next) => {
	console.log('third middleware start');
	await next();
	console.log('third middleware end');
});

controller.eventManager.fire('interestingEvent', { data: { some: 'string' } } );
```

--------------------------------

### Start Profiler Timer

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-profiler/README.md

Start the profiler timer for an existing profile instance. This marks the beginning of the measured time interval.

```javascript
searchProfile.start();
```

--------------------------------

### Instantiate Snap and Access Controllers

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/README.md

Demonstrates how to instantiate the Snap class with a configuration and access the created controllers.

```javascript
const snap = new Snap(config);
const { search } = snap.controllers;
```

--------------------------------

### Filtering Recommendations by Value and Range

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_RECOMMENDATIONS_LEGACY.md

Apply filters to recommendation results. This example filters by 'color' (blue, red) and a 'price' range (0-20) for the 'customers-also-bought' profile.

```html
<script type="athos/personalized-recommendations" profile="customers-also-bought">
	options = {
		filters: [
			{
				type: 'value',
				field: 'color',
				value: 'blue'
			},
			{
				type: 'value',
				field: 'color',
				value: 'red'
			},
			{
				type: 'range',
				field: 'price',
				value: { low: 0, high: 20 }
			}
		]
	}
</script>
```

--------------------------------

### Grouped Block Integration Example

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/src/Instantiators/README.md

Demonstrates the grouped block integration style using a single script tag with a 'profiles' array to define multiple recommendation controllers. Each profile targets a specific DOM element and specifies the recommendation profile to load.

```html
<div class="ss__recs__trending"></div>
<div class="ss__recs__similar"></div>

<script type="athos/recommendations">
	globals = {
		products: ["SKU-123"],
		shopper: { id: "user_abc" },
	};
	profiles = [
		{
			tag: 'trending',
			selector: '.ss__recs__trending',
			options: {
				limit: 5,
			},
		},
		{
			tag: 'similar',
			selector: '.ss__recs__similar',
		},
	];
</script>
```

--------------------------------

### Initialize FinderStore

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-store-mobx/src/Finder/README.md

Demonstrates how to initialize the FinderStore with configuration and a URL manager. The store is then updated with data and its JSON representation is logged.

```javascript
import { FinderStore, FinderStoreConfig } from '@athoscommerce/snap-store-mobx'
import { UrlManager, UrlTranslator } from '@athoscommerce/snap-url-manager';

const finderConfig: FinderStoreConfig = {
	id: 'finder',
	url: '/search',
	fields: [
		{
			field: 'ss_tire',
			label: 'Wheel Finder',
			levels: ['Year', 'Make', 'Model', 'Wheel Size']
		},
	]
};

const finderUrlManager = new UrlManager(new UrlTranslator()).detach(0);
const store = new FinderStore(finderConfig, { urlManager: finderUrlManager });

store.update(data);

console.log(store.toJSON());
```

--------------------------------

### Initialize SnapHybrid with Templates and Snap Configuration

Source: https://github.com/athoscommerce/snap/blob/main/docs/TEMPLATES_ABOUT.md

This snippet demonstrates the basic initialization of SnapHybrid using both templates configuration and standard Snap configuration. It includes setting up site details, theme variables, translations, custom components, and controller targets.

```tsx
import { SnapHybrid } from '@athoscommerce/snap-preact';
import type { SnapTemplatesConfig } from '@athoscommerce/snap-preact';
import { Content, Sidebar } from './components';
import { globalStyles } from './styles';

// Your existing templates configuration
const templatesConfig: SnapTemplatesConfig = {
	config: {
		siteId: 'atkzs2',
		language: 'en',
		currency: 'usd',
		platform: 'shopify',
	},
	theme: {
		extends: 'pike',
		variables: {
			colors: {
				primary: '#202223',
				secondary: '#6d7175',
			},
		},
		overrides: {
			default: {
				results: {
					columns: 4,
				},
			},
			mobile: {
				results: {
					columns: 2,
				},
			},
		},
	},
	translations: {
		en: {
			searchHeader: {
				titleText: {
					value: 'Search Results',
				},
			},
		},
	},
	components: {
		result: {
			CustomResult: async () => (await import('./components/Result')).CustomResult,
		},
	},
};

// Standard Snap configuration for full control
const snapConfig = {
	client: {
		globals: {
			siteId: 'atkzs2',
		},
	},
	controllers: {
		search: [
			{
				config: {
					id: 'search',
					plugins: [],
					settings: {
						redirects: {
							merchandising: false,
						},
					},
				},
			targets: [
				{
					selector: '#athos-content',
					component: () => Content,
					hideTarget: true,
				},
				{
					selector: '#athos-sidebar',
					component: () => Sidebar,
					hideTarget: true,
				},
			],
			},
		],
	},
};

// Create the hybrid instance
const snap = new SnapHybrid({
	templatesConfig,
	snapConfig,
});

```

--------------------------------

### Access Profile Status

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-profiler/README.md

Retrieve the current status of the profile. The status changes from 'pending' to 'started' upon starting and to 'finished' upon stopping.

```javascript
console.log(`context: ${searchProfile.status}`);
```

--------------------------------

### Configure Similar Products Recommendations

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_RECOMMENDATIONS_INTEGRATION.md

Set up a 'similar' profile to display products related to the current product. Assumes 'similar' profile is set up and 'bundle.js' is configured.

```html
<script type="athos/recommendations">
	globals = {
		products: ['product123']
	};
	profiles = [
		{
			tag: 'customers-also-viewed',
			selector: '.ss__recs__similar'
		}
	];
</script>
```

--------------------------------

### Define Search Controller with Two Targeters

Source: https://github.com/athoscommerce/snap/blob/main/docs/REFERENCE_CONFIGURATION_TARGETERS.md

This example demonstrates setting up a single search controller with two targeters. The `<Content>` component is rendered into `#athos-content` and the `<Sidebar>` component into `#athos-sidebar`, both sharing the same controller.

```javascript
// src/index.js

const snap = new Snap({
    client: {
		globals: {
			siteId: 'REPLACE_WITH_YOUR_SITE_ID',
		},
	},
    controllers: {
        search: [
            {
                config: {
                    id: 'search',
                },
                targeters: [
                    {
                        selector: '#athos-content',
                        component: async () => {
                            return (await import('./components/Content/Content')).Content;
                        },
                    },
                    {
                        selector: '#athos-sidebar',
                        component: async () => {
                            return (await import('./components/Sidebar/Sidebar')).Sidebar;
                        },
                    },
                ],
            },
        ],
    },
});
```

--------------------------------

### Setting Initial Sidebar State to Closed

Source: https://github.com/athoscommerce/snap/blob/main/packages/snap-preact/components/src/components/Templates/Search/readme.md

Configures the sidebar toggle to start in a closed state using the toggleSidebarStartClosed prop. Set to true to start closed.

```tsx
<Search controller={controller} toggleSidebarStartClosed={true} />
```

--------------------------------

### Providing Cart Contents for 'Also Bought'

Source: https://github.com/athoscommerce/snap/blob/main/docs/SNAP_RECOMMENDATIONS_LEGACY.md

If tracking scripts are absent, provide cart contents directly for 'also bought' profiles. This example uses 'sku456' as the cart item.

```html
<script type="athos/personalized-recommendations" profile="view-cart">
	cart = ['sku456'];
</script>
```

--------------------------------

### Custom Location Definition Example

Source: https://github.com/athoscommerce/snap/blob/main/docs/REFERENCE_CUSTOM_BADGE_TEMPLATES.md

Example of a locations.json file defining custom locations for badge templates. Custom locations use tags to restrict badge template usage.

```json
{
	"left": [
		{
			"tag": "left",
			"name": "Top Left"
		},
		{
			"tag": "left-bottom",
			"name": "Bottom Left"
		}
	]
}
```