Behavior, Content, Money – 3 Things you should never give away for free!!!

BCmoney MobileTV

How to build widgets following the W3C Widget specification

Posted by bcmoney on June 29, 2014 in Mobile, Web Services with No Comments


No Gravatar
English: an incon to indicate that there is a ...

Icon to indicate a widget. (Photo credit: Wikipedia)

This post will be a quick & dirty step-by-step guide to building a Widget following the cross-platform W3C Widget specification. For starters I’ll list out the 7 primary W3C specifications on Widgets and 4 specs on their use with Mobile devices (roughly in order of significance):

Now unless you are supporting an instance of one of the legacy widget platforms/portals for your organization, or, have recently been put in charge of building a new “widget type platform” for your company, then I wouldn’t suggest you waste too much time going through all those specs. I’m intending to give you a quick overview here that will save you that pain and give you a sufficient familiarity to be functional with Widgets right away.

What is a Widget?

Whether you call it a widget, gadget, badge, module, capsule, snippet, framed window, representation, implementation, micro, mini, page flake or anything else; a Widget is a small web, mobile, or desktop application that brings information directly to you, so you don’t have to go somewhere else look for the information yourself.

Some widgets are helpful self-contained resources like clocks, calculators, or calendars. Some widgets are static and just display specific information that rarely if ever changes, like a “list of useful links” or some reminder text. Some widgets are more dynamic and let you write desktop post-it notes, convert media files, or see weather forecasts. Dynamic/Interactive widgets really do let you accomplish some incredible stuff, like let you automatically feed Dilbert comics in color straight to your Facebook wall or Instagram followers (or even just to your blog, personal web page, or even your desktop). Widgets can of course also pull data from external sources. Regardless of their type, all widgets are designed to be shared. You can easily send your favorite widgets to friends and co-workers with a single click and email, and anyone who sees a widget on your personal pages can download a version to customize for themselves. The following image from the original Widget 1.0 spec shows how this simplicity works behind the scenes, based on web standards:

This figure shows the various specifications and file formats that typically make up a client-side Web application.
From the above, we can define a Widget as a small functional component of a larger application or service. Since widgets are typically used to summarize data or remotely access information from another source located outside of an application’s original hosting/deployment environment, thereby extending the original application’s capabilities, we know that for many dynamic/interactive widgets, AJAX will be used to pull in external data. For that reason, we know we’ll need a Server-side Proxy and/or CORS in place to get the external data.

What kind of data?
Mashups are likely the initial inspiration for widgets. A mashup is taking data from one source via web scraping or SOA and displaying it yourself. Ever since the earliest examples of data integration between two or more services to accomplish new results, there has been this “widget” metaphor to describe the external “mashed up source” that’s being integrated outside its original use cases. The easiest to understand example, and probably one of the oldest API mashup examples, is the one between Craig’s List housing/apartment listings and Google Maps street lookups, known as HousingMaps. Another early example is displaying Google Search results within your own webpage/website/webapp (going forward I’ll just call whatever you’re building “your stuff“). If you think about the most commonly sought-after third party APIs on the web that developers and businesses tend to want to integrate into “their stuff”, these 3 probably come to mind: YouTube videos, Flickr photos, Twitter status tweets. However, it truly could be anything and doesn’t even necessarily need to have a Web Service or API to integrate it. For simplicity let’s call whatever is being integrated “other people’s stuff“.

In a world without widgets, every single time you want to integrate other people’ s stuff into your own stuff, you need to lookup their API and/or Developer documentation, hope they have an SDK and if they do download it, or, copy/paste some possibly outdated example client code from their docs/blog/tutorials (those will only cover particular programming languages so hope you know one of the supported languages or are bright enough to port to your own programming language), then start writing your integration code pieces to make their stuff work with your stuff. Developers perform this often painful process over and over, ad nauseam. What if you don’t know the language their examples are written in or SDK supports? More time wasted just getting a basic level of understanding required to get the demos running. Great they are running in their own dev sandbox, now your boss insists you get that stuff integrated and working with your existing stuff. How about versioning of APIs/WebServices and then having an popular feature of your app that depends entirely on other people’s stuff? Stuff that constantly keeps changing? Good luck keeping that shit working! In the best case it’ll become your recurring nightmare making little updates to support the latest versions of their stuff and to build complex fallback defensive coding just in case their stuff goes down, to prevent it from crashing your stuff or making your stuff look/perform bad. In the worst case you’ll get transferred to another project or organization and the stuff you had built breaks forever or becomes some other poor schmuck’s problem. If developers at popular web services would just make their stuff available as Widgets, we would always have self-contained examples of the functionality. If YouTube’s API were down or changed, our canned example always works no matter what, and by pinging the update API we can decide before rendering the Widget, whether or not everything it needs is available and accessible from the location in which it is being run. At a certain point, all this integration work becomes Enterprise Application Integration and requires an Enterprise grade budget. So what’s the alternative? Companies build a widget representation of their services, and you start to follow “widgetization” patterns by making your own code modular and robust enough to be used in more than just your own website or app.

How?

The rest talks about the how of widgets, but the recipe is simple:

  • XML config file to describe widget capabilities
  • Follow coherent directory structure
  • Avoid plugin-dependencies (i.e. Flash, Silverlight, JavaFX/Applets, Unity, etc) where possible
  • At least provide a more basic “fallback experience” when plugins are not available (i.e. an interactive stock chart could just display a table of data if a depended-upon plugin aren’t available)
  • Design & Develop with integration in mind (CSS should be specific not generic rules, JS should be namespaced to avoid conflicts, no “frame-busting” techniques)

As you can see its not really a demanding list of criteria so much as generally helpful and sound set of advice for ensuring your application is built well enough to reach the largest possible audience. In fact, if everyone followed the simple steps above when building their applications, I’d go so far as to say the world would be a better place!

Project Template

Since a number of the earlier “widget-like” platforms such as Google Gadgets spec used XML to define its configuration, it only made sense for W3C Widgets spec to do so as well. So, the first thing you need is an XML file which summarizes your project its widget capabilities.

<widget>

</widget>

Next, you’ll need to ensure you have a directory structure that follows the basic formula:
[IMAGE OF DIRECTORY STRUCTURE]

You can rename your “styles” folder to “css”, and “scripts” to “js” if you really want to (alot of devs have just gotten used to those naming conventions so I really don’t see that as a big deal). The point is that this is the basic formula for how to structure the self-contained Widget application’s directory, and ensure that all dependencies (JS, CSS, Fonts, etc) are contained inside the package, not referenced externally, since versions can change and links can go dead. The name of the game with Widgets is supposed to be better posterity, longer lasting code and simplicity of understanding/integrating.

Lastly, you just need to make sure you zip up the directory and rename it to “.wgt”

i.e. HelloWorld.wgt

With that info and the following Widget example project, you’ll be set to start building a widget to expose your awesome stuff, and, you’ll also be set to integrate someone else’s stuff if they’ve already made it available as a widget. If they haven’t and you think they should, why not build the example based on their API/dev docs and send it to them, and potentially save countless dev hours of other people reinventing the wheel by rolling their own integrations.

 

 



-or-
 

 

 

Conclusion

The W3C Widget spec is an awesome and welcomed addition to the developer’s toolbox, and one that deserves a little more attention. I’ve been developing and delivering all my consulting clients’ work following these specs since 2009, when I had first heard about them and actually contributed some code to the Apache Wookie project back in 2010. In my next post, I’ll talk about what the Java-based Apache Wookie widget container is and how you can either use it to build your own Widget container and start integrating “all the stuff“, or, how to put together a really basic version of a widget portal in PHP just for testing integration of widgets, like I’ve done for my portfolio.


References