Widget JavaScript API Reference

​Inline Tiles API​
​Events​
​Legacy Callbacks​
​Translation Strings​
​Global Widget Events API​
​Events​
​Methods​
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
#1
init
Triggered when the widget instance is available.
1.e (Object)
2.instance (Object)
#2
load
Triggered when the initial data is loaded.
1.e (Object)
2.listData (Array)
#3
beforeRender
Triggered before widget starts to render.
1.e (Object)
2.$appendRoot (jQuery)
3.listData (Array)
#4
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.
1.e (Object)
2.tileData (Array)
3.tileId (String)
#5
beforeAppend
Triggered before a tile is appended to the container.
You can modify a tile element before it is being appeneded to the container.
1.e (Object)
2.$tile (jQuery)
3.tileData (Array)
4.$appendRoot (jQuery)
#6
iterate
Triggered after a tile is decorated and the tile HTML is generated.
1.e (Object)
2.$tile (jQuery)
3.tileData (Array)
#7
append
Triggered after a tile is appended to the container.
1.e (Object)
2.$tile (jQuery)
3.tileData (Array)
4.$appendRoot (jQuery)
#8
render
Triggered after the widget is rendered.
1.e (Object)
2.$appendRoot (jQuery)
3.listData (Array)
#9
loadMore
Triggered after the widget load more data.
1.e (Object)
2.$appendRoot (jQuery)
3.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
#1
onBeforeRenderIsotope
1.containerWidth (Number)
2.maxTileWidth (Number)
3.margin (Number)
4.numColumns (Number)
5.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.
#2
onBeforeRenderTiles
1.addedIds (Array)
2.addedData (Object)
–
Invoked befored tiles are rendered. Use it when you want to add, remove, or update tiles before rendering.
#3
onCompleteJsonToHtml
1.$tile (jQuery)
2.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.
#4
getTileWidth
1.$tile (jQuery)
2.tileWidth (Number)
3.margin (Number)
4.numColumns (Number)
tileWidth (Number)
Invoked before each tile dimension is set. Use it when you need to modify tile width.
#5
onCalculateDimensions
1.$tile (jQuery)
–
Invoked after each tile is appended to container. Use it when you need to resize inside elements according to actual tile dimension.
#6
onCompleteAddingToDom
1.$tile (jQuery)
–
Invoked after each tile is appended to container.
#7
onCompleteRenderImage
1.$image (jQuery)
–
Invoked after each tile image is loaded.
#8
onCompleteRenderTiles
1.$addedTiles (jQuery)
2.addedData (Object)
–
Invoked after tiles are rendered. Use it when you need to update tiles after they are rendered.
​
onScrollLoad
1.$tiles (jQuery)
2.isLoading (Boolean)
–
Invoked when a widget loads more tiles by user scrolling. Use it when you need to update ‘Loading…’ text.
​
onScrollEnd
1.$tiles (jQuery)
2.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
1.type (String)
2.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.';
Global Widget Events API
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 Visual UGC 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 Visual UGC 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.
​
search
Trigger to update content by searching a keyword.
Note that you will need to make a request to
Visual UGC 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.

Order	Event Name	Description	Arguments
#1	init	Triggered when the widget instance is available.	1. e (Object) 2. instance (Object)
#2	load	Triggered when the initial data is loaded.	1. e (Object) 2. listData (Array)
#3	beforeRender	Triggered before widget starts to render.	1. e (Object) 2. $appendRoot (jQuery) 3. listData (Array)
#4	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.	1. e (Object) 2. tileData (Array) 3. tileId (String)
#5	beforeAppend	Triggered before a tile is appended to the container. You can modify a tile element before it is being appeneded to the container.	1. e (Object) 2. $tile (jQuery) 3. tileData (Array) 4. $appendRoot (jQuery)
#6	iterate	Triggered after a tile is decorated and the tile HTML is generated.	1. e (Object) 2. $tile (jQuery) 3. tileData (Array)
#7	append	Triggered after a tile is appended to the container.	1. e (Object) 2. $tile (jQuery) 3. tileData (Array) 4. $appendRoot (jQuery)
#8	render	Triggered after the widget is rendered.	1. e (Object) 2. $appendRoot (jQuery) 3. listData (Array)
#9	loadMore	Triggered after the widget load more data.	1. e (Object) 2. $appendRoot (jQuery) 3. listData (Array)

Order	Callback Name	Arguments	Must Return	Description
#1	onBeforeRenderIsotope	1. containerWidth (Number) 2. maxTileWidth (Number) 3. margin (Number) 4. numColumns (Number) 5. 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.
#2	onBeforeRenderTiles	1. addedIds (Array) 2. addedData (Object)	–	Invoked befored tiles are rendered. Use it when you want to add, remove, or update tiles before rendering.
#3	onCompleteJsonToHtml	1. $tile (jQuery) 2. 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.
#4	getTileWidth	1. $tile (jQuery) 2. tileWidth (Number) 3. margin (Number) 4. numColumns (Number)	tileWidth (Number)	Invoked before each tile dimension is set. Use it when you need to modify tile width.
#5	onCalculateDimensions	1. $tile (jQuery)	–	Invoked after each tile is appended to container. Use it when you need to resize inside elements according to actual tile dimension.
#6	onCompleteAddingToDom	1. $tile (jQuery)	–	Invoked after each tile is appended to container.
#7	onCompleteRenderImage	1. $image (jQuery)	–	Invoked after each tile image is loaded.
#8	onCompleteRenderTiles	1. $addedTiles (jQuery) 2. addedData (Object)	–	Invoked after tiles are rendered. Use it when you need to update tiles after they are rendered.
	onScrollLoad	1. $tiles (jQuery) 2. isLoading (Boolean)	–	Invoked when a widget loads more tiles by user scrolling. Use it when you need to update ‘Loading…’ text.
	onScrollEnd	1. $tiles (jQuery) 2. 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	1. type (String) 2. data (Object)	–	Invoked when a widget receives customised message from parent page.

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

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.
search	Trigger to update content by searching a keyword. Note that you will need to make a request to Visual UGC 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)

Widgets API Reference

JavaScript API for Blank Canvas Widget

Last modified 14d ago