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)
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 Name Arguments Return Value Description
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’
  2. 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: Stackla 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)
  2. options {Object} (optional)

    • $container: $(document.body)
    • auto_resize: true
    • template: $(‘#tpl-layout’).html()
    • setting: Stackla.widgetOptions
    • renderer

      • data
      • options
      • templates
  3. 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.

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]
    });
});

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 Stackla’s 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 Stackla
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_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
video_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