ASTRA Badge Kit

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.

Badge Kit XML Framework

The Badge Kit consists of the base SWF file, Badge.swf, and two files that define the badge content: config.xml and content.xml.

config.xml

A typical config.xml file may look as follows:

The <contentpath> node defines the location of content.xml. In the example above, content.xml is located in the same folder as the main badge.

The <paths> section allows you to specify shorthands for long paths. In the example above, "SWF" is defined as a shorthand for the folder "resources/swf". In content.xml, you can now use "%SWF%" every time you need to refer to that path (e.g., "%SWF%/components.swf" instead of "resources/swf/components.swf").

The <classpaths> section allows you to specify classpaths for different services and elements, so that you can refer to them just by the class name, rather than by full classpath (for example, "Image" instead of "com.yahoo.astra.badgekit.controls.Image").

Finally, the <animations> section defines different animations that can be used when showing or hiding the components. The animation has an "id" attribute, the "property" attribute with the name of the property that's being modified, a start and end values, as well as the duration of animation in seconds. In the example above, the x-coordinate of the element to which the animation is applied will animate from x=200 to x=108 in 1 second.

content.xml

Content.xml, the primary description file for the badge, consists of three sections: <resources>, <services> and <elements>.

<Resources> section

The <resources> section lists the resource files with components and graphical resources that a particular badge requires. The badge kit accepts SWF files that can encapsulate a variety of content: UI components, services, images, videos, sounds, text, and so on. A typical <resources> section of content.xml may look as follows:

The resources are loaded before the badge is rendered on-screen. [Progress bar for loading resources?]

<Services> section

The <services> section defines all of the data services used by the badge. The services defined in this section must exist as classes among the resources provided by the resource SWFs; if a particular service is not found, a runtime “Service not found.” error is thrown.

Each of the service nodes in this section can be assigned attributes that correspond to specific service properties. For example, consider the following service definition:

<com.yahoo.webapis.flickr.FlickrService id = "flickrService" applicationId = "myappid" maximumResults = "10" userId = "1234567" send = "true" />

In this node, we instantiate the FlickrService that exists as a class in the com.yahoo.webapis.flickr classpath in one of the SWF resources we imported (the classpath can also be included in config.xml, in which case you can simply use “FlickrService” for instantiation). Next, we specify the “id” of the service – this is the name by which other elements of the badge can refer to it to extract parameters. We also set some of the properties owned by FlickrService: applicationId, maximumResults, and userId. Finally, we set the “send” property to true – this special setting triggers the send() method of the service (the order of assignments doesn’t actually matter: send() only triggers after all the parameters are assigned.)

This particular combination of parameters will retrieve URLs for 10 latest photos for a given userId and applicationId. However, given the current configuration, once the data is loaded, nothing will happen. To add a response to the “result” event dispatched by FlickrService, we can set the “result” attribute of the node:

<com.yahoo.webapis.flickr.FlickrService … result = "label.text = 'Photos are loaded'; img1.source = flickrService.thumbnails[0];" />

Note on architecture

In the badge kit framework, the only programmatic construct allowed in response to events is a variable assignment. Though this may seem like a major limitation, we believe that for the purposes of badge development, this construct is sufficient to accomplish the necessary tasks. Badges, by design, are not complex applications, and at a high level, they do not require conditional checks (if statements), loops (for and while statements), or other complex functionality. The job of a badge is to move data and modify properties in response to actions and events. If more complex functionality is desired, it should be implemented at the component level by the Flash developer.

In the example above, the FlickrService dispatches a ‘result’ event when it finishes loading URLs for the photos. In response, we perform two variable assignments: we assign the “text” property of the element with “label” id to a specific value, and we assign the “source” property of “img1” to the first thumbnail URL in the array of thumbnail URLs returned by flickrService. In this manner, we can assign all of the retrieved data to various UI elements that are defined in the section.

<Elements> section

The <elements> section of the badge description file sets up the visible interface of the badge and assigns all of the interactive behavior to the individual components. Consider, for instance, the following sample element definition:

In this sample, the Image component is a bitmap container that dynamically loads an image from an outside source. Notice that we are not including the full classpath (com.yahoo.astra.badgekit.controls.Image), because we presumably imported it in the config.xml, as described in the previous section. The component itself must be located in one of the SWF files we imported under <resources>.

We then set the basic properties of the Image component: its position on the badge, its size, as well as some of the native UIComponent properties (useHandCursor and buttonMode ensure that the Image behaves like a button). The “onShow” property is set to a particular animation, also defined in config.xml. We also initially set the visibility of the Image to false.

Next, we set responses to the events and actions dispatched by the Image. The first event is “complete”, which is dispatched when the Image is loaded. When that happens, we set the Image’s own visibility to true. The “click” event occurs when the user clicks the image with the mouse; at that event, we set the text on a label to “Clicked an image”.