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 tosxpr.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 tosxpr.shopping()
which references a search input whose value is the search query - Pass a
shoppingUrlTemplate
string tosxpr()
andsxpr.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)
Property | Description | Type |
---|---|---|
shoppingUrlTemplate | Free accounts only Template for shopping tab link URLs. These links will appear in widgets and navigate users to your shopping tab. This template should be passed to both It is strongly recommended that you provide this setting, unless you are using a Example: |
|
handleShoppingClick | Free accounts only Click handler for the internal shopping tab links in widgets. Used where new shopping results are loaded dynamically (using JavaScript) rather than via traditional page navigation, meaning that |
|
Settings for sxpr.shopping()
(shopping tab)
Property | Description | Type |
---|---|---|
shoppingUrlTemplate | Free accounts only Template for shopping tab link URLs. These links will appear in widgets and navigate users to your shopping tab. This template should be passed to both It is strongly recommended that you provide this setting, unless you are using a Example: |
|
shoppingAutoScroll | Free accounts only Whether to automatically scroll the viewport to the top of the shopping tab widget after product thumbnails have been loaded. Default |
|
enableEcoProducts | Free accounts only Whether to add a carousel of eco-friendly product thumbs across the top of the shopping tab widget. (Default |
|