Widget 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
#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

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 Stackla 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 Stackla 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
Stackla 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)

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
.