Widget JavaScript API

From KickApps API Reference

Jump to: navigation, search

Contents

Overview

Using the widget Javascript API you can do some powerful and creative things with widgets like having multiple widgets on a page interact with each other and the page itself. This is done via adding a couple of variables to the swf's embed code flashVars and calling the swf's internal functions directly from Javascript.

Invoking JavaScript functions from widgets

Widgets issue a number of events. These events are wrapped in callbacks which can be used to trigger JavaScript functions on the page. To access these callbacks, pass the name of the JavaScript function you want to invoke to the variable that represents the event you want to trigger it in the flashVars of your widget embed code.

  • If you're adding one of these callbacks to the compatible version of widget embed code, you'll need to update the flashVars in both the <object> and <embed> tags. Also make sure to prepend &amp; (all spelled out) to each callback, like this: &amp;clickJSCallback=widgetClicked
  • If you're using the JavaScript version of widget embed code, you only need to update the flashvars variable in the main <script> tag.

Available callbacks

loadedJSCallback

loadedJSCallback=yourJSFunctionName

yourJSFunctionName will be called when the widget has finished loading all of its internal components. It will pass the object id of the swf.

clickJSCallback

clickJSCallback=yourJSFunctionName

yourJSFunctionName will be called every time the widget is clicked. It will be passed the object id of the clicked swf and name of the component clicked.

eventCallbackFunc

eventCallbackFunc=yourJSFunctionName

yourJSFunctionName will be called every time an event occurs in the widget. It will be passed the name of the component on which the event occurs and an Object that looks like this: 

{type: /* event type */, target: /* component name */, data: /* data associated with event */}

Currently (8/17/09) only propertyChange events for selectedItem trigger this callback. This event is triggered when a new piece of media is loaded or selected in a component. We we will be expanding this to cover many more events and event types in the near future.

Invoking widget functions from JavaScript

The second part of the API involves calling functions in the .swf directly from JavaScript. In order to make your widget accessible to JavaScript,

  1. Ensure the embed code has allowScriptAccess="always"
  2. Append &amp;js=1 to both sets of flashVars in the embed code. If you've already included one of the above callbacks in the flashVars you don't have to include the &amp;js=1.

Once this is in place you can now call these functions directly on the swf object. Please Note: the widget may need to be fully loaded before some of these commands can be called.

Available widget functions

getComponentProperty

getComponentProperty(componentName:String, propertyName:String, propertyIsOnSelectedMedia:Boolean)

Call to retrieve a property value from a component.

componentName 
the name of the component, found in the layers panel of the the App Studio (this auto-generated name can be edited by double clicking the row).
propertyName
the camel-cased name of the property you want to set, or a chain of properties (see example below). Currently the best way to see what is available for a particular component is to open the "Actions" panel of the Widget Studio and check out the "Update Property" action for a given component. It will list all properties available.
For an example of a property chain, see selectedItem.authors.0.name in the function below: 
function slideshowEventCallbackFunc(id, evt){
       if (evt.type=="propertyChange" && evt.data=="selectedItem"){
               var slideshow = navigator.appName.indexOf("Microsoft") != -1 ? window['kickWidget_18929_141281'] : document['kickWidget_18929_141281'];
               var authorName = slideshow.getComponentProperty("Slide Show Component 1", "selectedItem.authors.0.name");
       }
}
propertyIsOnSelectedMedia (optional) 
true or false (without quotes). If the component has selected/loaded media (like a list component with a cell that is highlighted) you can grab the media details properties from the selected media item instead of a property on the component itself by setting this to true (it's false by default). With propertyIsOnSelectedMedia set to true, you can retrieve values for any of the following items by passing in their names for the propertyName parameter in this function:
title
description
thumbnails 
array of {url:, width:, height:} objects for all images parsed out of the source
kickAppsModuleData 
an object containing all kickapps module properties for this media item which includes: 
  gadtype, mediaType, keywords, views, votes, rating, uploadedByUrl, uploadedByThumbnail, userDisabled, country, state, city, zip, numOfComments, gadChannel gadPublisher, gadhost, favorites, id, category, points, level
date
url 
the link associated to this media item
enclosure 
the actual source url of the media item
enclosuretype
authors

setComponentProperty

setComponentProperty(componentName:String, propertyName:String, value)

Call this function to set a property on a component inside of a widget.

componentName 
the name of the component, found in the layers panel of the the App Studio (this auto-generated name can be edited by double clicking the row).
propertyName
the camel-cased name of the property you want to set, or a chain of properties (see example below). Currently the best way to see what is available for a particular component is to open the "Actions" panel of the Widget Studio and check out the "Update Property" action for a given component. It will list all properties available.
For an example of a property chain, see selectedItem.authors.0.name in the function below: 
function slideshowEventCallbackFunc(id, evt){
       if (evt.type=="propertyChange" && evt.data=="selectedItem"){
               var slideshow = navigator.appName.indexOf("Microsoft") != -1 ? window['kickWidget_18929_141281'] : document['kickWidget_18929_141281'];
               var authorName = slideshow.setComponentProperty("Slide Show Component 1", "Background Color", "#eeeeee");
       }
}

getEmbedCode

getEmbedCode(variables:Object=null)

Grabs a copy of the widget's embed code. Optionally you can pass an object containing flashVars you want appended to the returned embed code like so: 

var embedCode:String = widget.getEmbedCode({mediaURL:"my custom media url", autoPlay:false});

setEmbedCode

setEmbedCode(newEmbedCode:String)

Temporarily replaces the code that appears in the widget syndication panel. Note: Facebook syndication will not be affected as it does not use embed code.

showShareMenu

showShareMenu()

Forces the widget's syndication menu to pop open.

runCommand

runCommand(commandParams:Array)

Calls one of our preset "commands" in the widget. There are four currently exposed with many more on the way.

togglePlay

Toggles audio/video playback. 

runCommand(["Video Player 1", "togglePlay", false, STATE]);

Replace STATE with 'on', 'off', or 'toggle'.

moveSelection

Make a list component that's being used as a playlist change its selected item to the item after its currently selected item by moving the selection forward, or to the item before its currently selected item by moving the selection backward. 

runCommand(["Slide Show Component 1", "moveSelection", false, FORWARD]);

Replace FORWARD with true to move forward or false to move backward. Note: For list components you must have the list's "Selection Enabled" property enabled to use this command.

pageItems

Change the visible "page" in a list component. 

runCommand(['List 1', 'pageItems', false, MOVE_BACKWARDS, PAGE_BY_ONE]);

Replace MOVE_BACKWARDS with true to page backwards, or false to page forward. Replace PAGE_BY_ONE with true to page one item at a time, otherwise it will page by the number of rows or columns depending on the scrollbar direction.

scroll

Scroll a list component by a certain number of pixels. 

runCommand(['List 1', 'scroll', false, SCROLL_BACKWARDS, PIXELS]);

Replace MOVE_BACKWARDS with true to scroll backwards, or false to scroll forward. Replace PIXELS with the number of pixels you want to scroll. You can also pass a negative number to scroll in the opposite direction.

Demos

Demo with regular embed code

Demo with .swf object embed code The demo link above shows some cool things you can do with the JavaScript API. It has 2 separate embedded widgets, a list and video player, and a fake ad banner. Clicking on one of the items in the list will load the selected video into the player widget and rotate the fake banner via clickJSCallback. The last loaded video is also bookmarked via the address bar. Reload the page and loadedJSCallback will pre-load the bookmarked video back into the player. There are also 3 html buttons at the bottom of the page displaying the use of the "togglePlay" command. There is also a slideshow widget at the bottom of the page. This widget uses the eventCallback JS hook to trigger a JS function whenever a new slide loads. This function cycles the fake ad and loads the description associated with the loaded media. Two buttons beneath the slideshow load new slides via the "moveSelection" action.

Retrieved from "http://www.kickdeveloper.com/api/index.php/Widget_JavaScript_API"