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 |