Overview

In this article, we'll learn how to embed Flash applications in the Widget engine using the following tools:

• Badge Kit (deprecated) - an XML-based framework for rapid development of small interactive Flash applications.
• ASTRA Components - a collection of well-documented, skinnable components that can be used in Actionscript 3 applications.

We will use the Badge Kit to build a Slideshow Widget that uses the Flickr API to retrieve and display images. After that, we will use the ASTRA Components to create an Aquarium Widget.

How to Create Widgets with Flash Applications

We will begin by learning how to create a Yahoo! Widget from a Flash application. We will look at the files and directory structure of a Widget. Then, we will break down the files necessary to construct your Widget. When constructing a Widget, you will need to create the following directory structure within your Widget's folder.

Widget Directory Structure

At the root level of your directory, there is a folder named Contents. It contains a .kon file, a Widget.xml file and a Resources folder. At a minimum, your resources folder will contain your Flash file. If there are any additional assets, they will also go in the Resources folder. You may choose to create subdirectories for your convenience. (e.g. Resources -> Images -> My Images)

The .kon file

The .kon file is the main file of a Widget. Below is an example.

<?xml version="1.0" encoding="UTF-8"?> <widget minimumVersion="4.5" debug="off"> <action trigger="onLoad"> var user = preferences.userId.value; var delay = preferences.delay.value; var placardColor1 = preferences.placardColor1.value; var placardColor2 = preferences.placardColor2.value; var flickrUrl = "http://www.flickr.com/photos/" + user; flashView.flashvars = "userId=" + user + "&delay=" + delay + "&flickrUrl=" + flickrUrl + "&placardColor1=" + placardColor1 + "&placardColor2=" + placardColor2 ; flashView.bgcolor = preferences.background.value; </action> <action trigger="onPreferencesChanged"> var user = preferences.userId.value; var delay = preferences.delay.value; var placardColor1 = preferences.placardColor1.value; var placardColor2 = preferences.placardColor2.value; var flickrUrl = "http://www.flickr.com/photos/" + user; flashView.flashvars = "userId=" + user + "&delay=" + delay + "&flickrUrl=" + flickrUrl + "&placardColor1=" + placardColor1 + "&placardColor2=" + placardColor2 ; flashView.bgcolor = preferences.background.value; reloadWidget(); </action> <window name="mainWindow" width="200" height="230" onMouseExit="titleImage.visible=false; titleText.visible = false;" onMouseEnter="titleImage.visible=true; titleText.visible = true;" > <title>ASTRA Flash Badge</title> <visible>true</visible> <image src="Resources/flickr_slideshow/titleHandle.png"> <name>titleImage</name> <hOffset>0</hOffset> <vOffset>0</vOffset> </image> <text name="titleText"> <data>ASTRA Flash Badge</data> <color>#ffffff</color> <hOffset>30</hOffset> <vOffset>18</vOffset> <size>14</size> </text> <flash name="flashView" width="300" height="500" allowNetworking = "all" hOffset="-50" vOffset="24" > <src>Resources/flickr_slideshow/badge/Badge.swf</src> </flash> </window> <preference name="userId"> <title>Flickr userId</title> <type>text</type> <defaultValue>33677944@N00</defaultValue> </preference> <preference name="delay"> <title>delay</title> <type>text</type> <defaultValue>2000</defaultValue> </preference> <preference name="placardColor1" group="Placard"> <title>placard color 1</title> <type>text</type> <defaultValue>#ff0000</defaultValue> </preference> <preference name="placardColor2" group="Placard"> <title>placard color 2</title> <type>text</type> <defaultValue>#000000</defaultValue> </preference> <preference name="background"> <title>background color</title> <type>text</type> <defaultValue>#808080</defaultValue> </preference> <about-box> <image>Resources/flickr_slideshow/About.png</image> <about-version> <font>Arial</font> <size>11</size> <hOffset>111</hOffset> <vOffset>175</vOffset> <color>#ffffff</color> <shadow> <color>#000000</color> <hOffset>1</hOffset> <vOffset>1</vOffset> </shadow> </about-version> </about-box> </widget>

There are many top level nodes in the basic hierarchy of the .kon file. You will see the following sections:

• action - defines when and how a Widget executes code that is triggered automatically rather than by a user.
• window - defines the main window of the Widget. It describes the size and position and contains all visual elements including our Flash node.
• preference - defines preference setting and associated attributes.
• about-box - allows us to define images for an about box.

For embedding Flash, we need the window section.

<flash name="flashView" width="300" height="500" allowNetworking = "all" hOffset="-50" vOffset="26" > <src>Resources/MyFlashWidget.swf</src> </flash>

The extensive list of attributes and functions can be found in the Konfabulator Reference but we will examine the ones that are used in our examples. The size of a swf is determined by width and height parameters. The coordinates of a swf are defined by hOffset and vOffset attributes in conjunction with hAlign and vAlign attributes.

By default, the hOffset and vOffset represent the x and y coordinates respectively. If hAlign is right, then the hOffset would be used to right align the object and if vAlign is set to bottom then the vOffset would be used to bottom align the object. The positioning attributes below:

• hAlign - defines whether the Flash object is left or right aligned. The default alignment is left.
• vAlign - defines whether the Flash object is top or bottom aligned. The default value is top.
• hOffset - defines the horizontal position of the Flash object dependent on the hAlign value.
• vOffset - defines the vertical position of the Flash object dependent on the vAlign value.

The path of the Flash file is placed in the src node. If the application shares data with other domains, the allowNetworking attribute must be included. Additionally, the Widget.xml file will need to contain a security node specifying the allowed domains.

The Widget.xml file

The Widget.xml file contains the metadata and security settings for a Widget project. If you want to include external data in your application, you must include this file with a security node. The security node contains the following elements:

• filesystem - restricts file system access
• http - restricts http requests
• command - restricts system commands
• hotkey - restricts global hotkey settings
• com/Applescript - restricts com requests and Applescript execution

Below is a security node that allows for access to any domain:

<security> <http name="all">all</http> <filesystem>none</filesystem> <applescript>false</applescript> <command>false</command> <hotkey>false</hotkey> </security>

Once an application is built, the Widget Converter is used to convert it to a Widget file. The Widget Converter can be downloaded from the Widget Downloads page. After you have downloaded and opened the Widget, you can then drag your folder to the Widget, set its menu to convert to flat file and click the "convert" button.

Using the Badge Kit: Flickr Slideshow

Now that we know how to set up our files to create Widgets, let's create one. In this exercise, we are going to use the Badge Kit to create a Flash application and integrate it as a Widget. The Badge Kit is an an XML-based framework for rapid development of small interactive Flash applications. You can learn how to use the Badge Kit very quickly, and most of the usage scenarios require no knowledge of Flash. If you need a primer on using the Badge Kit, go here.

Creating the Badge

In this example, we are using a flickr service to retrieve photos. Once the photos are retrieved, they are assigned to a Slideshow component that we have created. Below is the content.xml for this badge.

<?xml version="1.0" encoding="utf-8" ?> <badge id="flickrbadge"> <resources> <swf filename="%SWF%/base_components.swf" /> <swf filename="%SWF%/slideshow_component.swf" /> </resources> <services> <FlickrService id="flickrService" applicationId="59d06d27cd631c209db10a15572b8ae4" maximumResults="10" userId="flashvars.userId" result="slideshow.addSlides = flickrService.thumbnails[0]; slideshow.addSlides = flickrService.thumbnails[1]; . . . slideshow.slideDelay = flashvars.delay;" send="true" /> </services> <elements> <Image id="background" source="%IMG%/background.png" width="200" height="200" color="#0f0f00" x="0" y="0" onShow="fadeIn" visible="false" complete="background.visible = true"/> <Label id="imgTitle" width="130" height="50" x="35" y="8" wordWrap="true" text="My Latest Photos" onShow="textFadeIn" onHide="textFadeOut" fontFamily="Arial" fontSize="14" fontWeight="bold" color="0xdddddd" /> . . . <SlideshowItem id="slideshow" width="140" height="140" x="40" y="45" startText="fetching images from Flickr..." onShow="fadeIn" /> </elements> </badge>

Our resources node includes the base_components.swf, the default resource swf for badges, and a slideshow_component.swf that contains our custom slideshow component. In our services node, we have our flickr service. Once our photos are retrieved with this service, our slides are assigned to our Slideshow component through its addSlides method. The principle child nodes in our elements node are a background image, a title label and our slideshow component. We have broken down the xml used to create the flickr badge. All that is left is to turn it into a Yahoo! Widget.

Creating the Widget

As discussed earlier, our flickr_slideshow directory contains a directory named Contents which contain the following:

• flickr_slideshow.kon file
• Widget.xml file
• Resources directory

Our resources directory contains 3 pngs and a Badge directory. The pngs are used as images for a background, a handle and an about screen. The Badge directory contains all the files from our flickr_slideshow badge.

Our application needs to load data from flickr so we have to set the necessary permissions in our Widget.xml file. The security node has a child node for each security setting. To allow for http requests, we will set the security to all in the http node.

<?xml version="1.0" encoding="utf-8"?> <metadata> <platform minVersion="4.5" /> <security> <http name="all">all</http> <filesystem>none</filesystem> <applescript>false</applescript> <command>false</command> <hotkey>false</hotkey> </security> </metadata>

The widget node is the root node of our flickr_slideShow.kon file. It contains a window node, an about-box node and multiple preference and action nodes. Our window node contains all of our visual elements.

• image node with a name of titleImage. This node loads the image that is used for the draggable handle of our Widget.
• text node with a name of titleText. This node loads the text field for the draggable handle of our Widget.
• flash node with a name of flashView. This node loads our Flash movie. Notice how we have added the allowNetworking="all" to allow for our flickr communications.

Items placed in our preference nodes will be available to the Widget user for customization. We have preference nodes for userId, background and delay. Each node has the following child nodes:

• title tells the konfabulator what to display to the user
• type tells the konfabulator what user control to display to the user. (e.g. A type of text will generate a text field and a type of color will generate a color picker)
• defaultvalue will set the default value for the item.

The scripts that tie the preferences to the elements are located in the action nodes. In this case, the action node is used to pass flashVars to the flash embed. Our first node, has a trigger attribute value of onLoad. This script will execute every time the Widget loads. See the node below.

<action trigger="onLoad"> var user = preferences.userId.value; var delay = preferences.delay.value; var flickrUrl = "http://www.flickr.com/photos/" + user; flashView.flashvars = "userId=" + user + "&delay=" + delay + "&flickrUrl=" + flickrUrl ; flashView.bgcolor = preferences.background.value; </action>

If we look at the code above, we see that the values of the preferences nodes are used to customize the Widget. The value of the userId is used to build a flickrUrl and passed as the flashVar value of userId. The flickUrl variable is passed as the flashVar value of flickUrl. The value of the delay node is passed as the delay flashVar. The value of the background node is set as the background color of the Flash movie.

Our second action node is almost identical to the first one. There are two differences. The trigger attribute is set to onPreferencesChanged which means that this script will execute when the user changes the preferences of the Widget. Since the flashVars have changed, we reload the Widget for the changes to take effect (Theoretically, flashView.reload() would be preferred but due to a known issue, this command doesn't reload the flash file properly).

reloadWidget();

Download the Yahoo! Flickr Slideshow Widget here.

We have seen how the Konfabulator works, how to build a Flash desktop application with the Badge Kit and the Konfabulator. In our next section, we will explore other options for building a Flash desktop application with the Konfabulator.

ASTRA Components: Aquarium

The Aquarium Widget shows how you can leverage our ASTRA Flash Components to create applications that can then be embedded into a Widget.

Astra Components

ASTRA, the ActionScript Toolkit for Rich Applications, is a collection of Flash and Flex components, code libraries, toolkits and utilties developed by Yahoo! for ActionScript developers. The ASTRA Components use the existing component architecture and compliment the set provided in Adobe Flash CS3.

• Tree - a UI component that offers a convenient representation of hierarchical information (file folders, product catalogs, nested categories, etc.).
• Menu - a UI component that displays a hierarchical menu structure that can be used to provide convenient access to various application functionality, sorted by categories.
• TabBar - a UI component used for switching between different application states. Implemented as a dynamically resizing row of Tab buttons, whose labels are controlled by a DataProvider.
• Autocomplete - a specialized text entry field that provides a list of suggestions from a supplied data set based on the characters entered by the user.
• Charts (BarChart, ColumnChart, LineChart, and PieChart) - a set of visualization components that show tabular data in various graphical representations.
• MenuBar - a UI component that renders hierarchical data as a row of buttons with nested menus that can be used to provide convenient access to various application functionality.
• AlertManager - a UI component that creates and manages the queuing of alert windows in a Flash Application.
• AudioPlayback - a UI component that creates a set of controls for audio playback.

The Aquarium

In this example, we will take our Aquarium application and create a Widget. The Aquarium is a fun application that uses the Tree, Menu, TabBar, AutoComplete and Charts components. As such it shows how to integrate these components in a real application and how to customize these components for special use.

Since we do not need to specify any security settings for this application, we do not need a Widget.xml file. Below is the kon file for the aquarium Widget.

<?xml version="1.0" encoding="UTF-8"?> <widget minimumVersion="4.5" debug="off"> <action trigger="onLoad"> flashView.bgcolor = preferences.background.value; </action> <action trigger="onPreferencesChanged"> flashView.bgcolor = preferences.background.value; </action> <window name="mainWindow" width="288" height="252" onMouseExit="titleImage.visible=false; titleText.visible = false;" onMouseEnter="titleImage.visible=true; titleText.visible = true;" > <title>ASTRA Aquarium</title> <visible>true</visible> <image src="Resources/titleHandle.png"> <name>titleImage</name> </image> <text name="titleText"> <data>ASTRA Aquarium</data> <color>#ffffff</color><hOffset>15</hOffset> <hOffset>15</hOffset> <vOffset>18</vOffset><size>14</size> </text> <flash name="flashView" width="288" height="226" vOffset="26" > <src>Resources/aquarium.swf</src> </flash> </window> <preference name="background"> <title>background color</title> <type>text</type> <defaultValue>#ffffff</defaultValue> </preference> <about-box> <image>Resources/About.png</image> <about-version> <font>Arial</font> <size>11</size> <hOffset>111</hOffset> <vOffset>175</vOffset> <color>#ffffff</color> <shadow> <color>#000000</color> <hOffset>1</hOffset> <vOffset>1</vOffset> </shadow> </about-version> </about-box> </widget>

We have a flash node, a single preference for background color and two action nodes that set the background color of the swf when it loads and when the user changes the preference setting.

Download the Yahoo! Aquarium Widget here.

Next Steps

In this article, we have explored two approaches to rapid development of Flash Applications, The Badge Kit and the ASTRA Flash Component set. We have also learned how to leverage the Yahoo! Widget engine to turn our Flash movie into a desktop application. This should provide you with all the tools you need to start creating Flash Widgets of your own. If you would like to get more in depth with any of the topics, check out the links below:

• Badge Kit
• ASTRA Flash Components
• Yahoo! Widgets

Additionally, there is always a wealth of knowledge to be found at our Flash Developer Center. So, if you have not done so already, download the Badge Kit, ASTRA Components and Konfabulator so you can start building your own Flash Widgets today.

If you have any additional questions, join the Yahoo! Flash Developer Group and be heard!