Widget

Widgets allow you to easily embed shopping list tools on your recipe site. Widgets provide options to add recipes to shopping list or basket and to view the shopping list.

Widgets are tied to a specific recipe. In order for widget to appear your current page url must be a recipe. Or you can specify recipeUrl to link different or multiple recipes on the same page.

Defining widget

Widget builder

Easiest way to add widget is to use our widget builder. It automatically generates code and allows you to configure various options.

Manually define widget

Use whisk.shoppingList.defineWidget(id, options) function to define widget.

  • id is a string that must be unique for every widget on a single page and must match container's id attribute.
  • options parameter is optional and describes how your widget will look and behave. See list of supported options below.
whisk.queue.push(function() { whisk.shoppingList.defineWidget('widget-id', { recipeUrl: 'optional recipe url', styles: { size: 'large', type: 'modal', }, }); });

The next step is to display your previously defined widget on the page. Use display method like so:

<div id="widget-id"> <script> whisk.queue.push(function() { whisk.display('widget-id'); }); </script> </div>

Result should look like this:


Testing

Widget supports hidden option so you can test integration before making it publicly available. Add hidden: true to options and widget will be hidden by default. To see widget add whisk-enable=1 query parameter to url (i.e. https://example.com/my-recipe-url?whisk-enable=1).

Multiple recipes

In order to show multiple recipes and widgets on the same page:

  • Each recipe must have it's own url that must be recognized by the recipe validator.
  • Use the same code as above for every recipe on page with recipeUrl option.
  • Make sure IDs are unique for every widget.

Widget not appearing

In case your widget is not appearing:

  • Make sure your recipe url is recognized by the recipe validator.
  • If you use hidden: true make sure whisk-enable=1 query parameter is set.

Subscriptions

Read general information about subscriptions here. Widgets support following event types:

  • view - widget appeared in the viewport. Triggered once. No custom data for this event type.
  • click - widget button has been clicked. data has the following structure:
    ATTRIBUTETYPEDESCRIPTION
    operationenum

    Clicked button operation.

    Possible values: viewList, addRecipeToList, addRecipeToBasket.
  • error - triggered when widget has failed to load. Can be caused by recipe not being recognized, network error, etc. No custom data for this event type.

Define widget options

ATTRIBUTETYPEDESCRIPTION
languageenum

Shopping list app language.

Possible values: en, de, fr.
Default value: automatically defined based on browser language.
whiteLabelstring

Shopping list app design customisations. This is a premium feature for our partners.

trackingIdstring

Unique identifier for your business (optional). This is a premium feature for our partners. Contact us to get one.

onlineCheckoutonlineCheckout

Object which configures shopping list app online checkout preferences.

stylesstyles

Object which changes shopping list app appearance.

utmutm

Object with tracking params.

recipeUrlstring

Recipe URL to add. Recipe should be recognized by the recipe validator.

Default value: Current URL
hiddenboolean

Hide widget by default. Use whisk-enable=1 query parameter to override this option.

Default value: false
onlineCheckout object
ATTRIBUTETYPEDESCRIPTION
enabledboolean

Set it to false if you want to disable online checkout completely.

Default value: true.
allowedRetailersarray [enum]

List of available retailers in the shopping list app. [] - is equal to enabled: false.

Default value: all available retailers.
defaultRetailerenum

Default retailer for the shopping list app. You can find list of available retailers here.

Default value: is defined by Whisk API.
autoPickstring

Set it to true to go straight to checkout in addRecipeToBasket and addProductsToBasket methods

styles object
ATTRIBUTETYPEDESCRIPTION
typeenum

Define how shopping list or basket appears on page.

Possible values: modal, slideout.
Default value: modal.
sizeenum

Widget size.

Possible values: compact, large.
Default value: compact.
alignenum

Widget content alignment.

Possible values: left, center, right.
Default value: center.
buttonbuttonStyles

Style options for widget buttons.

linkColorstring

Link text colour.

button styles object
ATTRIBUTETYPEDESCRIPTION
colorstring

Button background colour.

textColorstring

Button text colour.

borderRadiusstring

Button border radius.

textstring

Button text. Only valid for 'compact' size.

AMP integration

Adding widget to your AMP pages is done via amp-iframe technology. In order to integrate Whisk on your page follow the instructions below.

Add amp-iframe script inside the <head> of your page:

<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>

Add the following code where you want the widget to appear on your page. Please note that there are some amp-iframe positioning limitations: learn more. Replace recipe-url with your actual recipe url. You should use canonical url (a.k.a. non-amp url of your recipe page).

<amp-iframe height="225" sandbox="allow-scripts allow-same-origin allow-popups" frameborder="0" src="https://cdn.whisk.com/sdk/amp.html?recipe-url=https://whisk.com/demo/sponsored-ingredient"> </amp-iframe>

Open this page on your mobile phone to see how it works.

Styling notes

  • In order to add margins to the widget add margin property to the iframe (for example: style="margin: 0 10px").
  • If you are one of our partners who have own whitelabel, please, adjust iframe height accordingly.
  • Also, you can pass options for customizing widget via query string:
  • Available query params for AMP

    ATTRIBUTETYPEDESCRIPTION
    languagestring

    Default language.

    owner-idstring

    Unique identifier for your business (optional). This is a premium feature for our partners. Contact us to get one.

    styles-typeenum

    Define how shopping list or basket appears on page.

    Possible values: modal, slideout.
    Default value: modal.
    styles-sizeenum

    Widget size.

    Possible values: compact, large.
    Default value: large.
    styles-link-colorstring

    Link colour.

    styles-button-colorstring

    Button colour.

    styles-button-text-colorstring

    Button text colour.

    styles-button-border-radiusnumber

    Button border radius.

    styles-button-textstring

    Button text. Only valid for 'compact' size.

    online-checkout-enabledboolean

    Set it to false if you want to disable online checkout completely.

    Default value: true.
    online-checkout-allowed-retailersarray [enum]

    Comma-separated list of available retailers in the shopping list app.

    Default value: all available retailers.
    online-checkout-default-retailerenum

    Default retailer for the shopping list app. You can find list of available retailers here.

    Default value: is defined by Whisk API.
    online-checkout-auto-pickstring

    Set it to true to go straight to checkout in addRecipeToBasket and addProductsToBasket methods

    Do not forget to URL-encode parameters.

    Example of customized AMP widget:

    <amp-iframe height="225" sandbox="allow-scripts allow-same-origin allow-popups" frameborder="0" src="https://cdn.whisk.com/sdk/amp.html?recipe-url=https://whisk.com/demo/sponsored-ingredient&styles-link-color=%23339999&styles-button-border-radius=18&styles-button-color=%23339999&online-checkout-allowed-retailers=US%3AWalmart%2CUS%3AInstacart"> </amp-iframe>