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 |
|
$.Deferred
|
Loads tiles data from the selected filter in Widget edit page (Settings > Select Filter)
|
Stackla.render |
|
$.Deferred
|
Renders the layout template by provided data and outputs it on page.
The following lists the details for the optional
|
Stackla.expandTile |
|
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 |
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 |