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 recipeUrlto link different or multiple recipes on the same page.
Defining widget
Widget builder
The easiest way to add a 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 the container's id attribute.
options parameter is optional and describes how your widget will look and behave. See a 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>
Testing
The widget supports the hidden option so you can test the 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 its 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 the 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:
ATTRIBUTE
TYPE
DESCRIPTION
operation
enum
Clicked button operation. Possible values: viewList, addRecipeToList, addRecipeToBasket.
error - triggered when the widget has failed to load. It can be caused by the recipe not being recognized, network error, etc. No custom data for this event type.
Define widget options
ATTRIBUTE
TYPE
DESCRIPTION
language
enum
Shopping list app language. Possible values: en, de, fr. Default value: automatically defined based on the browser language.
country
enum
Shopping list app country. Possible values: us, gb, de. Default value: automatically defined based on user location.
whiteLabel
string
Shopping list app design customizations. This is a premium feature for our partners.
trackingId
string
Unique identifier for your business (optional). This is a premium feature for our partners. Contact us to get one.
onlineCheckout
onlineCheckout
Object which configures shopping list app online checkout preferences.
styles
styles
Object which changes shopping list app appearance.
utm
utm
Object with tracking params.
recipeUrl
string
Recipe URL to add. The recipe page should be recognized by the recipe validator. Default value: The URL of your current page
hidden
boolean
Hide widget by default. Use whisk-enable=1 query parameter to override this option. Default value: false
scale
number
All ingredient quantities will be multiplied by this number
onlineCheckout object
ATTRIBUTE
TYPE
DESCRIPTION
enabled
boolean
Set it to false if you want to disable online checkout completely. Default value: true.
allowedRetailers
array [enum]
List of available retailers in the shopping list app. [] - is equal to enabled: false. Default value: all available retailers.
defaultRetailer
enum
Default retailer for the shopping list app. You can find a list of available retailers here. Note: you can pass null to unset a default value for new users. Default value: is defined by Whisk API.
autoPick
string
Set it to true to go straight to checkout in addRecipeToBasket and addProductsToBasket methods
styles object
ATTRIBUTE
TYPE
DESCRIPTION
size
enum
Widget size. Possible values: compact, large. Default value: compact.
align
enum
Widget content alignment. Possible values: left, center, right. Default value: center.
button
buttonStyles
Style options for widget buttons.
linkColor
string
Link text color.
button styles object
ATTRIBUTE
TYPE
DESCRIPTION
color
string
Button background color.
textColor
string
Button text color.
borderRadius
string
Button border-radius.
text
string
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 allow-forms"
  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 their own white-label, please, adjust iframe height accordingly.
Also, you can pass options for customizing widget via query string:
Available query params for AMP
ATTRIBUTE
TYPE
DESCRIPTION
recipe-url*
string
Recipe URL to add. The recipe should be recognized by the recipe validator.
white-label
string
Widget and Shopping list app design customizations. This is a premium feature for our partners.
tracking-id
string
Unique identifier for your business (optional). This is a premium feature for our partners. Contact us to get one.
language
string
Default language.
styles-size
enum
Widget size. Possible values: compact, large. Default value: large.
styles-link-color
string
Link color.
styles-button-color
string
Button color.
styles-button-text-color
string
Button text color.
styles-button-border-radius
number
Button border-radius.
styles-button-text
string
Button text. Only valid for 'compact' size.
online-checkout-enabled
boolean
Set it to false if you want to disable online checkout completely. Default value: true.
online-checkout-allowed-retailers
array [enum]
Comma-separated list of available retailers in the shopping list app. Default value: all available retailers.
online-checkout-default-retailer
enum
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-pick
string
Set it to true to go straight to checkout in addRecipeToBasket and addProductsToBasket methods
Do not forget to URL-encode parameters.
Example of a customized AMP widget:
<amp-iframe height="225"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
  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>
Event Listeners
Subscriptions
Last updated 4 months ago
ATTRIBUTE	TYPE	DESCRIPTION
operation	enum	Clicked button operation. Possible values: viewList, addRecipeToList, addRecipeToBasket.