Visual UGC Docs
Search
K

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. 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. 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: Visual 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. 1.
    data {Object} (required)
  2. 2.
    options {Object} (optional)
    • $container: $(document.body)
    • auto_resize: true
    • template: $('#tpl-layout').html()
    • setting: Stackla.widgetOptions
    • renderer
      • data
      • options
      • templates
  3. 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. 1.
    tileData {Object} (required)
  2. 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 Visual UGC'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 Visual 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