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 NameTypeDescription

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)

id

{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 NameArgumentsReturn ValueDescription

Stackla.loadTilesByFilter

  1. 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'

  1. 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

  1. data {Object} (required)

  1. options {Object} (optional)

    • $container: $(document.body)

    • auto_resize: true

    • template: $('#tpl-layout').html()

    • setting: Stackla.widgetOptions

    • renderer

      • data

      • options

      • templates

  1. 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

  1. tileData {Object} (required)

  2. 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 NameTypeDescription

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)

id

{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

tags

{Array}

Tag ID array

tags_extended

{Array}

Extended tag data

term_meta

{Array}

Aggregation terms meta

terms

{String}

Aggregation terms list which is separated by comma

time_phrase

{String}

Time format 1. ex. "10 Dec"

timephrase

{String}

Time format 2. ex. "2 weeks ago"

title

{String}

Tile title

updated_at

{Number}

Last updated timestamp

ups

{Array}

Up list of like/dislike

user

{String}

User handle

user_link

{String}

User URL of source website

vd

{Boolean}

Visible on Desktop

ve

{Boolean}

Visible on Eventscreen

via_source

{String}

Same with source

mp4_url

{String}

Video URL

vm

{Boolean}

Visible on mobile

vote_id

{String}

Vote ID

voted_competition

{Boolean}

Indicates if current user has voted for competition.

votes

{Array}

Vote list

vw

{Boolean}

Visible on Widget

width_ratio

{Number}

Width ratio

PreviousAPI Reference for Content WidgetsNextAPI Reference for Map Widget

Last updated