API Reference for Content Widgets

Onsite Widgets JavaScript API Reference

Inline Tiles API

Events

The following events are available in Waterfall, Carousel, Gallery, Feed, Grid, Masonry, Nightfall, and all future widgets.

$(document).on('widget:ready', function (e, instance) {
    instance
        .on('init', function (e, instance) {
            console.log(e.type, instance);
        })
        .on('load', function (e, listData) {
            console.log(e.type, listData);
        })
        .on('beforeRender', function (e, $appendRoot, listData) {
            console.log(e.type, $appendRoot, listData);
        })
        .on('beforeIterate', function (e, tileData, tileId) {
            console.log(e.type, tileData, tileId);
        })
        .on('beforeAppend', function (e, $tile, tileData, $appendRoot) {
            console.log(e.type, $tile, tileData, $appendRoot);
        })
        .on('iterate', function (e, tileData, tileHtml) {
            console.log(e.type, $tile, tileData, $appendRoot);
        })
        .on('append', function (e, $tile, tileData, $appendRoot) {
            console.log(e.type, $tile, tileData, $appendRoot);
        })
        .on('render', function (e, $appendRoot, listData) {
            console.log(e.type, $appendRoot, listData);
        });
});

Order

Event Name

Description

Arguments

init

Triggered when the widget instance is available.

e (Object)
instance (Object)

load

Triggered when the initial data is loaded.

e (Object)
listData (Array)

beforeRender

Triggered before widget starts to render.

e (Object)
$appendRoot (jQuery)
listData (Array)

beforeIterate

Triggered before a tile data is decorated and a tile HTML is generated.

You can update the tile data. If the widget supports for the Custom Template, you can use your customized data in the template. The Custom Template feature is currently available in the Grid and Masonry widgets.

e (Object)
tileData (Array)
tileId (String)

beforeAppend

Triggered before a tile is appended to the container.

You can modify a tile element before it is being appeneded to the container.

e (Object)
$tile (jQuery)
tileData (Array)
$appendRoot (jQuery)

iterate

Triggered after a tile is decorated and the tile HTML is generated.

e (Object)
$tile (jQuery)
tileData (Array)

append

Triggered after a tile is appended to the container.

e (Object)
$tile (jQuery)
tileData (Array)
$appendRoot (jQuery)

render

Triggered after the widget is rendered.

e (Object)
$appendRoot (jQuery)
listData (Array)

loadMore

Triggered after the widget load more data.

e (Object)
$appendRoot (jQuery)
listData (Array)

Legacy Callbacks

This section is only for Waterfall and Carousel widgets.

Callbacks.prototype.onCompleteJsonToHtml = function ($tile, tileData) {
    return $tile; // required, don't remove
};

Order

Callback Name

Arguments

Must Return

Description

onBeforeRenderIsotope

containerWidth (Number)
maxTileWidth (Number)
margin (Number)
numColumns (Number)
currentTileWidth (Number)

{tileWidth: (Number), numColumns: (Number)}

Invoked before widget rendering and window resizing. Use it when you need to change the widget layout. Note this callback is only available in Vertical Fluid and Waterfall widgets.

onBeforeRenderTiles

addedIds (Array)
addedData (Object)

–

Invoked befored tiles are rendered. Use it when you want to add, remove, or update tiles before rendering.

onCompleteJsonToHtml

$tile (jQuery)
tileData (Object)

$tile (jQuery)

Invoked before each tile is appended to container. Use it when you need to modify the tile HTML structure according to its data.

getTileWidth

$tile (jQuery)
tileWidth (Number)
margin (Number)
numColumns (Number)

tileWidth (Number)

Invoked before each tile dimension is set. Use it when you need to modify tile width.

onCalculateDimensions

$tile (jQuery)

–

Invoked after each tile is appended to container. Use it when you need to resize inside elements according to actual tile dimension.

onCompleteAddingToDom

$tile (jQuery)

–

Invoked after each tile is appended to container.

onCompleteRenderImage

$image (jQuery)

–

Invoked after each tile image is loaded.

onCompleteRenderTiles

$addedTiles (jQuery)
addedData (Object)

–

Invoked after tiles are rendered. Use it when you need to update tiles after they are rendered.

onScrollLoad

$tiles (jQuery)
isLoading (Boolean)

–

Invoked when a widget loads more tiles by user scrolling. Use it when you need to update ‘Loading…’ text.

onScrollEnd

$tiles (jQuery)
isLoading (Boolean)

–

Invoked when a widget doesn’t have any tiles to load after user scrolling. Use it when you need to update ‘There is no more content to be displayed.’ text.

onMessage

type (String)
data (Object)

–

Invoked when a widget receives customised message from parent page.

Translation Strings

You can modify or translate Widget texts by accessing window.Strings global variable. The following strings are only useful on the Waterfall, Grid, Masonry, Quadrant, Feed, and Nightfall widgets.

Strings.load_more = 'Load more content';
Strings.loading = 'Loading...';
Strings.scroll_end = 'There is no more content to be displayed.'; // Waterfall widget only
Strings.voting_message = 'A vote has already been registered from this IP address.';

The following Inline Tiles API are only available in Waterfall, Carousel, and Gallery widgets

You can access all the following events and methods via the window.Stackla.WidgetManager global variable.

Events

You can track user interactions by subscribing to Widget events.

Example Usage (for both Event and Methods)

Stackla.WidgetManager.on('tileExpand', function (e, data) {
    // Maybe you need to filter when you have multiple widgets on the same page.
    if (data.widgetId === 9999) {
        // do something...
    }
});

Note: To avoid manually checking the existence of the Stackla.WidgetManager global variable we recommend you use the Expanded Tile Code Editor in our Nosto Admin Portal.

Available Events

beforeExpandedTileClose Triggered before the Expanded Tile closes

e
data.el
data.tileData
data.widgetId

Event Name

Description

Callback Arguments

load

Triggered after the widget has been loaded

e
data.filterId
data.hashId
data.styleName
data.uniqueId
data.widgetId
data.widgetType

tileExpand

Triggered after the Tile opens

e
data.expandType
- ‘expand’: Lightbox
- ‘stack’: Full Stack
- ’tile’: Expanded Tile in Full Stack
- ‘original’: Original Source
- ‘custom’: Original Source
data.tileData
data.widgetId

beforeExpandedTileOpen _(preventable)_

Triggered before the Expanded Tile opens

e
data.el
data.tileData
data.widgetId

expandedTileOpen

Triggered after the Expanded Tile opens

e
data.el
data.tileData
data.widgetId

expandedTileImageLoad

Triggered after the Expanded Tile image has been laoded

e
data.el
data.tileEl
data.tileData
data.widgetId

beforeExpandedTileImageResize _(preventable)_

Triggered before the Expanded Tile image resizes

e
data.sizes
data.el
data.tileEl
data.tileData
data.widgetId

expandedTileImageResize

Triggered after the Expanded Tile image resizes

e
data.sizes
data.el
data.tileEl
data.tileData
data.widgetId

expandedTileClose

Triggered after the Expanded Tile closes

e
data.el
data.tileData
data.widgetId

shareClick

Triggered after the click of sharing buttons

e
data.shareNetwork
data.tileData
date.widgetId

userClick

Triggered after the click of the user links

e
data.tileData
date.widgetId

moreLoad

Triggered after the more tiles have been loaded

e
data.page
date.widgetId

shopspotActionClick

Triggered after the Shopspot CTA button has been clicked

e
data.productTag
data.tileData
data.widgetId

shopspotFlyoutExpand

Triggered after the Shopspot Flyout opens

e
data.productTag
data.tileData
data.widgetId

productActionClick

Triggered after the Product CTA button has been clicked

e
data.productTag
data.tileData
data.widgetId

Methods

You can update Widget content by invoking the following methods.

Example Usage

Stackla.WidgetManager.search(widgetId, keyword)

Note: To avoid manually checking the existence of the Stackla.WidgetManager global variable we recommend you use the Expanded Tile Code Editor in our Nosto Admin Portal.

Available Methods

Method Name

Description

Arguments

changeFilter

Trigger to update content by switching to another filter

widgetId
filterId
tags (optional)
group (optional)

destroy

Trigger to **destroy all** the widgets on the current page. You can even remove the embed codes when you specify the first argument to `true`.

isIncludeEmbedCode (optional)

loadMore

Trigger to load more data programmatically.

widgetId

rebuild

Trigger to **rebuild all** the widgets on the current page with the current `data-*` attributes.

Trigger to update content by searching a keyword.

Note that you will need to make a request to Nosto Support to make this method available to work properly. ‘Text Search’ by default is not made available.

widgetId
keyword

searchFilter

This is an alias for `search`. **It will be deprecated in the future.**

widgetId
keyword

postMessage

Post customized message to widget iframe(s).

type
data
widgetId (optional)

executeOnProductChange

When a product is changed on widgets with Shopspots, this method will be invoked.

method (method to be executed)

injectHTML

Inject HTML into all expanded tiles at the given location

target_element (element to inject into)
content (injectable content)
location (before/after)

._waitForElement

Wait for an element to render before performing functions. Requires promise usage.

element (element to wait on)

More Details

Take a look at our How to use “Filter and search” in a Widget article for more examples.

Looking for some help with CSS widget customisations? Check out our CSS guides for styling the Waterfall Widget, Carousel Widget, as well as the Widget Expanded Tile.

PreviousIntroduction NextAPI Reference for Blank Canvas

Inline Tiles API

Events

Legacy Callbacks

Translation Strings

Global Widget Events API

Events

Example Usage (for both Event and Methods)

Available Events

Methods

Example Usage

Available Methods

More Details