API Reference for Blank Canvas

JavaScript API for Blank Canvas Widget

PreviousAPI Reference for Content Widgets NextAPI Reference for Map Widget

Last updated 1 year ago

Was this helpful?

API Reference for Blank Canvas

JavaScript API for Blank Canvas Widget

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

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

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