Crafting software

BlogEngine.NET has a widget framework from version 1.4 which are web part like components that can be added and removed, configured and dragged around directly in the page. Simple widgets are very easy to create and plug in to your blog and there are several blog posts explaining how to do that. In this post I'm gonna go through a more advanced example featuring Web services and Ajax.

The Photo Album Widget

Download: PhotoAlbumWidget-0.1.zip
Unzip to ~/widget/ folder. Requires jQuery library.

First we start with some requirements for the widget we're creating.

1. BlogEngine.NET 1.4+ Widget
2. Show thumbnail pictures
3. Get pictures from Picasa web album
4. Ajax style asynchronous loading
5. Configurable number of pictures
6. Clickable pictures to show full size picture
7. Picture repository provider model
8. Flickr repository provider
9. Folder repository provider
10. Configurable picture count
11. Provider specific configuration
12. Configurable choice of provider
13. Full size picture pops up in Lightbox
14. Web 2.0 style controls for scrolling
15. Larger preview on mouse over picture

The list above is a prioritized backlog and the first version should include items 1 - 4.

Widget

We start off with number one, a BlogEngine Widget. To create a widget we add a new folder to the /widget/ folder and we call it PhotoAlbum. Then we create two user controls, one for widget presentation and one for configuration UI. They must be named, by convention, widget.ascx and edit.ascx respectively and should derive from WidgetBase and WidgetEditBase respectively. See more on basic widgetry here by Rtur and here by Mads as well as this, that and whatnot.

That was the easy part.

Picasa web album

With the next requirement we first need to get the pictures from somewhere so we skip to the next requirement. Picasa is Google's web album and it has its own REST API as well as a .NET client library. Conveniently there is also a public feed which contains all public photos uploaded to Picasa. (You can of course use your own Picasa album, see the Data API docs for more information). All we need to do is provide a query tag/tags to limit the search or we'll get an error message. The following code retrieves a couple of photos picturing cats:

[code:c#]
PicasaService service =
    new PicasaService("exampleCo-exampleApp-1");

PhotoQuery query =
    new PhotoQuery("http://picasaweb.google.com/data/feed/api/all");
query.Query = "cat";
query.NumberToRetrieve = 5;
PicasaFeed feed = service.Query(query);

foreach (PicasaEntry entry in feed.Entries) {
    string firstThumbUrl = entry.Media.Thumbnails[0].Attributes["url"] as string;
    writer.Write("",
                 firstThumbUrl, entry.Title.Text);
}
[/code]

If we drop the code above into the widget.ascx.cs we affectivally fullfills both requirements 2 and 3 so lets get on with number 4.

Ajax

Requirement number four implies the Incremental Page Display pattern where the main part of the page is shown quickly and portions of the page that takes longer to load are fetched and displayed asynchronously. To give the user feedback of the loading we place an animated gif image in the widget which is later swapped out when the real pictures arrive. To accomplish this we're using the jQuery JavaScript library which let us get away with very little code for pretty advanced stuff.

First we need to do a little refactoring since the widget needs to do an asynchronous call somewhere to get its content, i.e. the pictures to display. We're gonna go with the simplest possible solution here, just enough to satisfy the requirement. The simplest thing from the widget's point of view is to have the html containing a number of elements returned from the call. Then it's very simple to insert the html into the widget using jQuery. Given that the widget contains a div with the id "photoalbum" this is all it takes:

[code:js]
$("#photoalbum").html(the_html_to_insert);
[/code]

As it is now, the widget codebehind is rendering the requested html and this is not god. We need to move the code to some place which we can make a http request to and get the html in response. This can be done with a regular aspx page. All we need to do is to put a simple Repeater control on a page and bind it to a list of image URLs which we get from Picasa web album. So, we add a new aspx page to the /widgets/Photo Album/ folder and call it PhotoService.aspx. All we want in response is the tags which should be inserted into the widget so we clear the page from html and put a single Repeater on it like this:

[code:html]

   
                    ImageUrl="<%# Container.DataItem.ToString() %>" />
   

[/code]

In the codebehind we insert something like before and makes sure we bind to the Repeater control.

[code:c#]
// Error checking is omitted for clarity
List pictures = new List();
PicasaService service = new PicasaService("exampleCo-testApp-1");

string picasaUri = "http://picasaweb.google.com/data/feed/api/all";
PhotoQuery query = new PhotoQuery(picasaUri);
query.Query = "cat";
query.NumberToRetrieve = 6;
PicasaFeed feed = service.Query(query);

foreach (PicasaEntry entry in feed.Entries) {
    string firstThumbUrl = entry.Media.Thumbnails[0]
                               .Attributes["url"] as string;
    pictures.Add(firstThumbUrl);
}

pictureRepeater.DataSource = pictures;
pictureRepeater.DataBind();
[/code]

To test the service we point a web browser to /widgets/Photo Album/PhotoService.aspx which should show a bunch of cats! Everything looks good and all we need to do to get the pictures into the widget are two things. First we need to register the jQuery JavaScript file, either localy or a referer to the jQuery official site. Last we need to add some custom JavaScript that makes the Ajax call and puts the html at the right place.

JavaScript blocks should allways, if possible, be placed as close to the tag as possible. The reason is that the browser won't continue to load the remainder of the page when it hits a JavaScript block but rather wait until it is fully loaded. This is not a problem if we're dealing with short scripts but the jQuery library is relatively large in this context so we need to put it as far down the page as possible. Our own script that does the actual work depends on jQuery, thus it must be loaded last. The problem is that we need to do this in a User control in the middle of the page. To our help to solve this we have the ClientScriptManager that every aspx page has. With the method RegisterStartupScript we get to insert arbitrary scripts just before the

With this final step done we have our first version of the Photo Album Widget which is ready for demo.

Problems with the solution

Before the second iteration I'd like to summarize a couple of things with version one that are not of production quality.

1. PhotoService mimics the behavior of a Web service (kind of) but is really a simple aspx page
   - We could have done a Generic handler (ashx) instead but then we couldn't have used a Repeater
   - We could have done a custom HttpHandler but that need to go into App_Code and edit web.config which is harder to install
2. The requirements maybe fullfilled but no one cares for a widget that only display cats!
   - We need to be able to configure the feed as well as the query.