yourminis :: developers :: RSS Widget Tutorial

Developers > Learning Center > RSS Widget Tutorail

The RSS tutorial will display some of the more advanced features of the wAPI. In this lesson, you will have a fully functioning RSS widget with additional tracking and user preferences.

Requirements

Adobe Flash CSE
wAPI .mxp (If you don't have this installed yet, follow the steps found here)
Download the source code for this example here: Samples.

Steps

1. Create a new Document

The first step in this tutorial is to open Adobe Flash CSE. This is where you will do all of your widget development. While it's still possible to develop widgets using third party tools, it's probably easiest to use the Flash IDE until you are completely comfortable with the widget creation process. Once the Flash IDE is open, create a new "Flash File (AS3)".

2. Initialize an instance of the API and add a TextField

In the Actions panel, (if it's not already open press F9) add the following lines of code to the first frame:

3. Request an RSS Feed

Inside the onWidgetLoaded event, create a new RSSLoader instance using the widget.newRSS() class factory. After creating the instance, add a listener to the Event.COMPLETE event and call rss.load(...)

4. Add the RSS Response Event

Once the RSS Feed is returned, the Event.COMPLETE Event is fired on the RSSLoader Instance.

This example uses E4X to enumerate and display the results

The resulting code should look like this:

var widget; //Widget
var rss;
var textfield:TextField;

addEventListener("widget-loaded",onWidgetLoaded);

function onWidgetLoaded(evt:Event)
{
    //your widget has started and is ready for display
    widget.initWidget(300,400,0xffffff);

//add the textfield to the form
    textfield = new TextField();
    textfield.x = 5;
    textfield.y = 5;
    textfield.width = 280;
    textfield.height = 380;
    textfield.multiline = true;
    textfield.wordWrap = true;

addChild(textfield);

rss = widget.newRSS();
    rss.addEventListener(Event.COMPLETE,onRSSLoaded);
    rss.load(new URLRequest("http://feeds.feedburner.com/yourminis"));
}

function onRSSLoaded(evt:Event)
{
    var loader:URLLoader = URLLoader(evt.target);
    var rssxml:XML = XML(loader.data);

var str = "";
 for each (var item:XML in rssxml..item)
 {
 str+="<a href='" + item.link + "' target='_blank'>" + 
		 item.title + "</a> " + 
		 item.description + " ";
 }
 textfield.htmlText = str;
}

When you are ready to test, simply click the button "Test this widget!" in the Widget Panel to test out your widget locally before uploading to the yourminis widget platform. You can sign in now to test your widget on our Online Test Console.

5. Let's test it out before moving on:

Hit "Test this widget!" in the wAPI Widget Panel. Your widget should look like this:

6. Enable Resizing

By enabling resizing, users can tailor the widget dimensions, along with the other settings, in the yourminis sandbox before copying it to another destination.

Add the Resize Event Handler:

function onWidgetResize( evt:Event ):void 
{ 
	textfield.width = widget.width -20;
	textfield.height = widget.height -20;
}

In the onWidgetLoaded Event Handler, add a Listener for the widget.WIDGET_RESIZED event.

widget.addEventListener(widget.WIDGET_RESIZED,onWidgetResize);

Your widget should now be resizable in the Test Panel.

7. Add URL Click Tracking:

Add a link handler function for the TextEvent:

function linkHandler(evt:TextEvent)
{
	widget.reporting.trackURL(evt.text);
}

Add a TextEvent Listener anywhere before the RSS Request is made

Prefix the url in the onRSSLoaded Event with, "event:" when building the HTML string:

str+="<b><a href='event:" + item.link + "' target='_blank'><u>" 
            + item.title + "</u></a></b><br/>" 
            + item.description + "<br/><br/>";

Now, this widget will track all URL Clicks from this widget for future reporting. As well, if the widget is ever copied to someone's myspace page, the links, which are typically disabled on myspace, will now allow the user to click out to external URLs.

8. Add Dropdown Items

Each wAPI widget has the ability to customize the options within a dropdown located on the top/right-hand corner of the widget.

Add a dropdown handler function for the widget.DROPDOWN_LOADED Event:

function onDropDownLoaded( evt:Event):void
{
    widget.chrome.addDropDownItem("yourminis","http://feeds.feedburner.com/yourminis",loadFeed);
    widget.chrome.addDropDownItem("digg","http://digg.com/rss/index.xml",loadFeed);
    widget.chrome.addDropDownItem("flickr","http://api.flickr.com/services/
                                        feeds/photos_public.gne?format=rss2",loadFeed);
}

Add an event Listener after the call to initWidget

widget.addEventListener(widget.DROPDOWN_LOADED,onDropDownLoaded);

Implement the dropdown callback specified in the addDropDownItem call:

function loadFeed(feed)
{
    rss = widget.newRSS();
    rss.addEventListener(Event.COMPLETE,onRSSLoaded);
    rss.load(new URLRequest(feed));
}

9. Almost done... Get and Set user preferences.

User preferences will follow the widget whereever it is copied. As well, it will integrate with all the startpage and desktop environments so that the widget state can be saved across interactions.

Add a call to widget.setSetting in the dropdown handler:

function loadFeed(feed)
{
    widget.setSetting("feedurl",feed);

    rss = widget.newRSS();
    rss.addEventListener(Event.COMPLETE,onRSSLoaded);
    rss.load(new URLRequest(feed));
}

Now use widget.getSetting in the onWidgetLoaded event when calling rss.load():

rss.load(new URLRequest(widget.getSetting("feedurl","http://feeds.feedburner.com/yourminis")));

The code should now look like this:

var widget; //Widget
var rss;
var textfield:TextField;

addEventListener("widget-loaded",onWidgetLoaded);

function onWidgetResize( evt:Event ):void 
{ 
	textfield.width = widget.width -20;
	textfield.height = widget.height -20;
}

function onDropDownLoaded( evt:Event):void
{
	widget.chrome.addDropDownItem("yourminis","http://feeds.feedburner.com/yourminis",loadFeed);
	widget.chrome.addDropDownItem("digg","http://digg.com/rss/index.xml",loadFeed);
	widget.chrome.addDropDownItem("flickr","http://api.flickr.com/services/feeds/photos_public.gne?format=rss2",loadFeed);
}

function onWidgetLoaded(evt:Event)
{
	//your widget has started and is ready for display
	widget.initWidget(300,400,0xffffff);
	widget.addEventListener(widget.WIDGET_RESIZED,onWidgetResize);
	widget.addEventListener(widget.DROPDOWN_LOADED,onDropDownLoaded);
	
    //add the textfield to the form
    textfield = new TextField();
    textfield.x = 5;
    textfield.y = 5;
	textfield.width = 280;
	textfield.height = 380;
	textfield.multiline = true;
	textfield.wordWrap = true;
            
	addChild(textfield);
	
	rss = widget.newRSS();
	rss.addEventListener(Event.COMPLETE,onRSSLoaded);
	rss.load(new URLRequest(widget.getSetting("feedurl","http://feeds.feedburner.com/yourminis")));

addEventListener(TextEvent.LINK, linkHandler);
}

function loadFeed(feed)
{
	widget.setSetting("feedurl",feed);
	
	rss = widget.newRSS();
	rss.addEventListener(Event.COMPLETE,onRSSLoaded);
	rss.load(new URLRequest(feed));
}

function linkHandler(evt:TextEvent)
{
	widget.reporting.trackURL(evt.text);
}

function onRSSLoaded(evt:Event)
{
	var loader:URLLoader = URLLoader(evt.target);
	var rssxml:XML = XML(loader.data);
	
	var str = "";
	for each (var item:XML in rssxml..item)
	{
		str+="<a href='event:" + item.link + "' target='_blank'>" + 
					item.title + "</a> " + 
					item.description + " ";
	}
	textfield.htmlText = str;
}

You can sign in now to test your widget on our Online Test Console.

10. Test!

Hit "Test this widget!" in the wAPI Widget Panel. Click on the dropdown in the top/right corner and click "flickr". Your widget should look like this:

Conclusion

Congratulations! You've created a fully functional RSS widget using the wAPI.

Next Steps

Go build some cool widgets!