Shopping Tab

This page is only relevant for free accounts.

This page assumes that:

• You have a free account
• You have set up a search engine
• Your search engine has Show shopping tab enabled
• You have followed the guide to integrating Search Expander's standard widgets

Integrating the Search Expander shopping tab results is similar to integrating the standard widgets.

The shopping widget is expected to be rendered on a separate page or route from your web search results. On this shopping page, you will need to do the following:

• Add some markup to your shopping results page
• Load the Search Expander JavaScript library on the page
• Call the global sxpr.shopping() JavaScript function

Markup

You must provide an HTML container on your shopping page with the attribute data-sxpr-shopping. This container will have the following elements rendered inside it:

• Mainline product links
• A carousel of featured product links above the mainline products
• An optional carousel of eco-friendly product links above the mainline products
• Inputs for filtering and sorting the products
• A tree of product categories
• Pagination buttons for the mainline products

The shopping widget is mobile-friendly, but its container should be placed in a layout context which allows for a fairly large amount of content (e.g. a sidebar would be inappropriate).

Load the Search Expander library

You can include the Search Expander JavaScript library using:

<script src="https://api.searchexpander.com/js/sxpr.js"></script>

Call sxpr.shopping()

To run Search Expander, call sxpr.shopping() after the script has loaded:

sxpr.shopping({
    se: 'your-id', // Replace 'your-id' with your search engine's ID
    // ... other settings here
});

Search query

Search Expander needs to know your user's search query in order to provide relevant shopping results. You can provide the search query in one of these ways:

• Pass a q value to sxpr.shopping() (this is the most direct method)
• Add the data-sxpr-input attribute to a search input whose value is the search query
• Pass a searchInput value to sxpr.shopping() which references a search input whose value is the search query
• Pass a shoppingUrlTemplate string to sxpr() and sxpr.shopping() (see below)

JavaScript example

sxpr.shopping({
    se: 'your-id',
    q: 'lorem ipsum',
    // Or alternatively:
    searchInput: document.getElementById('my-search-input'),
});

HTML example

<input name="q" value="lorem ipsum" data-sxpr-input>

Empty search queries

Unlike the other Search Expander widgets, the shopping widget will be functional even without a user search query. If no search query is provided and cannot be derived from the page's search inputs or URL, the widget will render without any product links but will provide a tree of product categories in a sidebar. Users can click on these categories in order to initiate product searches.

Linking to your shopping tab

The standard Search Expander widgets for web search results will sometimes contain links to your shopping tab. In order that these links are pointing to the right place, Search Expander needs to know how to construct their URLs. To allow this, you must provide a shoppingUrlTemplate setting when calling sxpr() on your web (non-shopping) search results page.

For example, let's say your shopping page lives under the URL:

https://example.com/shopping

In this case, you should set shoppingUrlTemplate to:

https://example.com/shopping?q={searchTerms}.

(Note that the URL parameter name q in the above example can be anything you like.)

Relative URLs with absolute paths are allowed, for example:

/shopping?q={searchTerms}

// Run on your web results page:
sxpr({
    se: 'your-id',
    shoppingUrlTemplate: 'https://example.com/shopping?q={searchTerms}',
    // ... other settings here
});

The {searchTerms} tag will be automatically replaced with the user search query, which will be sent to the Search Expander API to obtain relevant products.

(Passing shoppingUrlTemplate to sxpr.shopping() in addition to the above is not strictly necessary but can help Search Expander figure out the user search query if q is not set.)

Dynamic control of shopping tab links

If the switch to a shopping tab route on your site is initiated by JavaScript code rather than standard page navigation (e.g. in a SPA), you may need to use JavaScript to handle the clicks on shopping tab links, rather than relying on normal links. You can do this by setting a handleShoppingClick function on the sxpr() settings object. This function can take care of updating the page so that the user is taken to the shopping tab.

Note that handleShoppingClick will need to be passed to sxpr() on your web results page/route, rather than to sxpr.shopping() on the shopping page.

If you provide a handleShoppingClick function, then when a widget shopping tab link is clicked, the link's default behaviour will be overridden and the function will be left to handle the shopping results request.

handleShoppingClick is passed an object with the following interface:

{
    q: string;                  // The shopping search query
    origQ: string;              // The original user query (which may not be the same as q)
    link: HTMLElement;          // The clicked link or alert button
    event: MouseEvent;          // The link's click event
    url: string | undefined;    // The shopping tab URL (only set if shoppingUrlTemplate is set)
}

You will usually only need to use the q value in this object.

Shopping tab alert button

In order to alert users to the shopping tab when they carry out an ad-friendly web search, you can add an alert button to your web results page. This can just be a div or span element with the attribute data-sxpr-shop-alert. For example:

<span data-sxpr-shop-alert>Shopping</span>

Clicking on this button will take the user to the shopping tab, in accordance with the shoppingUrlTemplate setting. If handleShoppingClick is set, this function will be called in place of direct navigation.

Styling and behaviour will be taken care of by the Search Expander library, but of course you can tweak its appearance using CSS.

If you want the alert button hidden until shopping tab results are ready, add the following CSS to your page:

[data-sxpr-shop-alert] {
    display: none;
}

…and Search Expander will reveal it at the appropriate time.

Eco-friendly products

In addition to the Featured Products carousel, you have the option of adding another carousel containing a selection of eco-friendly products, where these are available. In order to enable this carousel, you must set enableEcoProducts to true on the object passed to sxpr.shopping(). For example:

// Run on your web results page:
sxpr.shopping({
    se: 'your-id',
    q: 'lorem ipsum',
    
    // Add this setting to get a carousel of eco-friendly products:
    enableEcoProducts: true,

    // ... other settings here
});

Shopping-related settings reference

Settings for sxpr() (web search tab)

string

(data: {
  q: string;
  origQ: string;
  link: HTMLElement;
  event: MouseEvent;
  url: string | undefined;
}) => void

Settings for sxpr.shopping() (shopping tab)

string

'small' | 'large' |
'always' | 'never'

boolean

» Styling the Widgets