API Reference for Blank Canvas

JavaScript API for Blank Canvas Widget

You are reading the Classic Widget Documentation

Classic widgets are a previous widget version for onsite widgets created before September 23rd.

From September 23rd 2025, all new widgets created will be NextGen.

Please check your widget version on the Widget List page to see if it is Classic or NextGen widget.

You can read the Nextgen widget documentation here.

Setting Object (Read-only)

In our Blank Canvas Widget, you can access the widget setting configuration by checking the window.Stackla.widgetOptions global variable. The following table lists useful properties.

Property Name

Type

Description

custom_css

{String}

Compiled Custom CSS for Inline Tile

custom_js

{String}

Source Custom JavaScript for Inline Tile

custom_tile

{String}

Custom Template in Mustache syntax for Inline Tile

filter_id

{String}

ID of selected filter

guid

{String}

A hash code representing unique Widget ID (Widget ID replacement)

{String}

Widget ID

lightbox_custom_css

{String}

Compiled Custom CSS for Expanded Tile

lightbox_source_css

{String}

Source Custom CSS in LESS syntax for Expanded Tile

slug

{String}

Widget Domain

source_css

{String}

Source Custom CSS in LESS syntax for Inline Tile

stack_id

{Number}

Stack ID

short_name

{String}

Short name of current Stack

style.name

{String}

Name of your Widget

Methods

To ease the pain of building a widget from scratch, we've provided some methods for you.

Method Name

Arguments

Return Value

Description

Stackla.loadTilesByFilter

options {Object} (optional)
- list_url: '/api/widget'
- pin_url: '/api/pins'
- page: 1
- limit: 30
- filter_id: widgetOptions.filter_id
- polling: 10000
- ttl: 30
- tags: '56983,56782'
- tags_grouped_as: 'AND'
- tile_id: '5828c80b2f1f77812ecbbe68'
- search: 'justinbieber'
callback {Funciton} (optional)
- data

$.Deferred

data

Loads tiles data from the selected filter in Widget edit page (Settings > Select Filter)

list_url: Tiles API URL.
pin_url: Pinned tiles API URL.
page: Page number for Tiles API URL.
limit: Page size for Tiles API URL.
filter_id: Nosto's UGC Filter ID.
polling: Polling interval in millionseconds.
ttl: Tile to live in seconds. It's for cache purpose.
tags: Comma-separated Tag IDs.
tags_grouped_as: Tags grouping rule. The value can be 'and' or 'or'.
tile_id: Comma-separad Tile IDs.
search: Search keyword.

Stackla.render

data {Object} (required)
options {Object} (optional)
- $container: $(document.body)
- auto_resize: true
- template: $('#tpl-layout').html()
- setting: Stackla.widgetOptions
- renderer
  - data
  - options
  - templates
callback {Funciton} (optional)
- html
- data
- options

$.Deferred

data
options
templates

Renders the layout template by provided data and outputs it on page.

The following lists the details for the optional options object.

$container: The container which the html being prepended to. The default value is $('document.body').
auto_resize: Indicates if the it adjusts the iframe dimension automatically. The default value is true.
template: The layout template in Mustache. The default value is $('#tpl-layout').html()
setting: The widget configuration. The default value is Stackla.widgetOptions.
renderer: You can customize the rendering.
- data: The tiles data.
- options: This options object.
- templates: The Mustache templates in array.

Stackla.expandTile

tileData {Object} (required)
expandType {String} (optional)

void

Displays the Expanded Tile by providing the tile data. You can specify portrait or landscape as expand type. Also other options to control what to show, show_products show_shopspots and show_caption

Sample Usage

Using Callback

You can use old school callback.

Stackla.loadTilesByFilter(function (tiles, dataFilter) {
    Stackla.render({tiles: tiles});
});

Using jQuery Deferred

Or use the modern Promise-style way.

Stackla.loadTilesByFilter()
.then(function (tiles, dataFilter) {
    Stackla.render({tiles: tiles});
});

Adjusting Options

You can adjust the request parameters by providing options object.

 // Using jQuery Deferred
Stackla.loadTilesByFilter({filter_id: 1234, page: 2})
.then(function (tiles) {
    Stackla.render({tiles: tiles});
});

// Or using tranditional callback
Stackla.loadTilesByFilter({filter_id: 1234, page: 2}, function (tiles) {
    Stackla.render({tiles: tiles});
});

Customized Rendering

You can render the widget according to your needs.

Stackla.loadTilesByFilter().then(function (tiles) {
    Stackla.render({tiles: tiles}, {
        auto_resize: false, // Handle the iframe resizing by yourself
        renderer: function (data, options, templates) {
            // Render the HTML
            var html = Mustache.render(options.template, data, templates);
            console.log(options.template, data, templates);

            // Create a wrapper instead of appending to body directly.
            $wrapper = $('<div class="wrapper"/>');
            $wrapper.html(html);
            $(document.body).prepend($wrapper);

            // Adjust the viewport height manually since I set auto_resize to false.
            Stackla.postMessage('resize', {height: $('body').height()});

            return html;
        }
    });
});

Fetching Extra Data

You can load your own data.

$.when(
    Stackla.loadTilesByFilter(),
    yourExtraDataRequest()
).then(function (tilesResponse, extraDataResponse) {
    Stackla.render({
        tiles: tilesResponse[0],
        extra: extraDataResponse[0]
    });
});

Config Expanded Tile

You can customize what to show on expanded tile.

Stackla.expandTile(data.tiles[$(this).attr("tileInnerID")],{
        layout: 'landscape',
        show_shopspots: true,
        show_products: true,
        show_caption: true
}

Tile Properties

You can use all of the following properties in both your JavaScript and Tile Template.

Property Name

Type

Description

anonymous

{Boolean}

true if this tile doesn't display both user avatar and name. Only Custom Tile would set this property to true

avatar

{String}

Avatar URL

avatars

{Object}

Different avatar sizes including L, M, S, XL, and XS

caption

{String}

Parsed message

claimed

{Boolean}

true if this tile is being claimed

class_names

{String}

Default CSS class names which should be added to tile wrapper element

comments

{Array}

Comment list

competitions

{Array}

Competition list

content_only

{Boolean}

true if this tile doesn't display anything except content. Only Custom Tile would set this property to true

created_at

{Number}

The timestamp of Nosto's UGC ingestion

downs

{Array}

Dislike list

emoji

{Function}

The lambda for converting Emoji unicode to images, which is useful in Mustache.

has_avatar

{Boolean}

Indicates if this tile has an user avatar

has_image

{Boolean}

Indicates if this tile has an image

has_image_dimension

{Boolean}

Indicates if the tile image has dimension saved in Nosto's UGC

has_title

{Boolean}

Indicates if the tile has a title

has_video

{Boolean}

Indicates if the tile has a video

height_ratio

{Number}

The ratio of image height

html

{String}

Tile message in HTML (not always available)

{String}

Tile ID

image

{String}

Image URL

image_thumbnail_url

{String}

A smaller (400px) and optimised version of image URL

image_alt_text

{String}

Image alternative text

image_max

{String}

Large image URL

image_max_height

{Number}

Large image height

image_max_width

{Number}

Large image width

is_ecal

{Boolean}

Indicates if it's an ECal tile

is_firefox

{Boolean}

Indicates if user's browser is Firefox

is_gif_video

{Boolean}

Indicates if it's a GIF video tile

is_ie8

{Boolean}

Indicate if user's browser is IE8

is_pin

{Boolean}

indicate if it's an pinned tile

is_stackla_feed

{Boolean}

Indicate if it's a stackla feed

is_video

{Boolean}

Indicate if it's a video

is_winner

{Boolean}

Indicate if it's a winner tile for competition

lang

{String}

Detected language code

media

{String}

Media type. The value could be image, video, or text

message

{String}

Tile message

numComments

{Number}

The amount of comments

numDowns

{Number}

The amount of down (dislike/vote)

numQueuedComments

{Number}

The amount of queued comments

numUps

{Number}

The amount of up (like/vote)

numVotes

{Number}

The amount of vote

original_link

{String}

The URL of original post

original_url

{String}

The URL of original post

replies

{Array}

Comment replies list

score

{Number}

Like/Dislike Score

source

{String}

Source media name such as rss, sta_feed, twtiter and so on

source_created_at

{Number}

Creation timestamp of original post

source_user_id

{String}

Creation User ID in source website

stackla_sentiment_score

{Number}

Sentimental score

tag_class_names

{String}

CSS class names which should be added to tile wrapper element

tag_id_list

{String}

Tag ID list which is separated by comma

tag_name_list

{String}

Tag name list which is separated by comma