JavaScript API for Blank Canvas Widget

Setting Object
Methods
- Sample Usage
- Tile Properties

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

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