README

Snap Preact

Snap Preact is an abstraction layer that provides a config based interface for creating a Searchspring integration quickly.

Installation

To install the snap-preact package and it's dependencies:

npm install --save @searchspring/snap-preact

Instantiation

import { Snap } from '@searchspring/snap-preact';

const snap = new Snap(config);

Configuration

A configuration object provided to Snap will determin the services that will be created.

Full example:

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

config.client

A single client instance will be created and shared across all services using the provided config.

See @searchspring/snap-client documentation for full client config options.

const config = {
    client: {
        globals: {
            siteId: 'xxxxxx'
        }
    }
}

config.instantiators

The instantiators object must be defined if any Recommendation controllers have also been defined via config.controllers.recommendation

const config = {
    instantiators: {
        recommendation: {
            components: {
                Standard: () => Standard
            },
            config: {
                branch: BRANCHNAME,
                batched: true
            },
            selector: '',
            services: {}
        }
    },
    controllers: {
        recommendation: []
    }
}

recommendation.components - required mapping of recommendation components.

recommendation.config.branch - required current git branch name. Defined via webpack during bundle build:

const webpack = require('webpack');
const childProcess = require('child_process');
const branchName = childProcess.execSync('git rev-parse --abbrev-ref HEAD').toString().trim();

module.exports = {
    plugins: [
        new webpack.DefinePlugin({
            BRANCHNAME: `"${branchName}"`,
        }),
    ],
}

recommendation.config.batched - optional boolean (default: true) to batch multiple recommendations into a single network request

recommendation.selector - optional selector to target recommendation instances if using a non-standard installation. Default selector: script[type="searchspring/recommend"]

recommendation.services - optional object of ControllerServices

config.url

The url object contains the config provided to each UrlTranslator created by Snap Preact.

const config = {
    url: {
        parameters: {
            core: {
                query: { name: 'search' },
                page: { name: 'p' }
            },
        },
    },
}

config.controllers

The controllers object contains a list of controllers to create for each controller type.

Available controllers:

const config = {
    controllers: {
        search: [],
        autocomplete: [],
        finder: [],
        recommendation: [],
    }
}

Each array entry contains an object with the following properties:

config - required controller config for the corresponding controller. See Controller specific documentation for all available configuration options.

targets - optional array of Target objects. Targets thats have been found will have the corresponding controller provided to the target component controller prop and the controller's search method invoked.

type ExtendedTarget = {
    selector: string;
    inject?: {
        action: 'before' | 'after' | 'append' | 'prepend' | 'replace';
        element: Element | ((target: Target, element: Element) => Element);
    };
    hideTarget?: boolean;
    emptyTarget?: boolean;
    name?: string;
    component?: () => Promise<RootComponent> | RootComponent;
    props?: unknown;  // additional props to pass to the component
    onTarget?: OnTarget;  // additional scripts to execute when target is found
    prefetch?: boolean;  // run controller search before finding targets
}

services - optional object of ControllerServices to be used for this controller in place of the default services

url - optional UrlTranslator config object to be used with the UrlManager for this controller

An example creating a SearchController:

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

The controller config id will be the name of the controller that you will then interface from the return of creating the new Snap() instance via the controllers object.

For example, if using the config example above:

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

properties

After instantiating an instance of Snap, the following properties can be accessed.

config

A reference to the config that was provided.

logger

A reference to the shared @searchspring/snap-logger instance used by each controller.

client

A reference to the shared @searchspring/snap-client instance used by each controller.

tracker

A reference to the shared @searchspring/snap-tracker instance used by each controller.

controllers

An object containing all controllers that have been created.

recommendations

A reference to RecommendationInstantiator instance if creating recommendation instances.

polyfills

Snap Preact provides various polyfills to ensure legacy browser support.

import { polyfills } from '@searchspring/snap-preact';

polyfills.then(() => {
    import('./index');
})

Usage no npm install needed!