What is Blueprint

Blueprint is the name of Yahoo! Mobile’s new platform and the new descriptive mark-up language created to make your mobile development experience as easy as possible. Blueprint has been released alongside the beta launch of Yahoo! Go 3 (beta), the latest version of Yahoo!’s popular mobile software.

The apps you create with this new framework are called widgets. Blueprint makes it easy to create consistently great-looking, well-behaved widgets, so you can concentrate on the content and features of your app.

Within the Blueprint framework, you can also write smaller applications called snippets. Think of snippets as very simple widgets with specific functionality. The differences between widgets and snippets are explained in the specifications available as a PDF here.

Blueprint is a declarative mark-up language: think of it as XHTML. In this 1.0 release, you cannot program loops or conditional statements (this functionality is planned for later), but you can use your preferred server-side programming language (php, python, j2ee, .net, …) and your output will be in Blueprint. Blueprint lets you specify the elements you want rendered on the mobile screen and how they will interact with the user. Because Blueprint is based on the XForms standard, you can easily work with forms, and include a great number of predefined elements with complex user interfaces. If you want to render a map or add some pagination to your application, it’s as easy as saying “add map here.”

You can write Blueprint code once and run it in any device - it’s that simple. The Yahoo! Go 3 (beta) client is a J2ME application supported by almost every device. In fact, some native versions actually improve performance in popular operating systems. Your application will work everywhere the Go 3 client works on. As you create your application, the platform automatically creates a web version, so you can point any mobile browser to your app, and it will work. The platform is intelligent enough to know your device and browser and will optimize the appearance of your app for the handset.

Parts of a widget

A widget consists of two parts. The first is a compressed zip file that includes the following elements:

• A config.xml file including:
  • meta information about the widget.
  • Where the widget is hosted.
  • Icons and other static resources used within the widget.
• A gallery.xml file (optional) in which you specify how the widget will be presented in the Yahoo! Widgets gallery. (Include title, description, icon)
• A “resources” folder containing static elements like icons or other images.

This first part is hosted on Yahoo! servers and is uploaded using an simple web form.

The second and most important part is the widget code. You can host your widget anywhere,, as long as it’s publicly accessible. You can use whatever technology you want to write it. Your output will be the Blueprint language. One condition: You must be able to generate a specific content-type via some HTTP header. We'll get back to this a little later.

SDK for developers

You can download the SDK (Software Development Kit) at http://mobile.yahoo.com/developers/download. Here’s what you’ll find:

• Templates for creating widgets and snippets. (Snippets are smaller applications that can also be created with this new framework, sort of like mini-widgets). There’s a config.xml, a gallery.xml, and some icons. To see your first widgets up and running, change a couple of values in those XML files and substitute the icons with your own artwork.
• A Blueprint.php file with a PHP 5 class that can be useful to generate your Blueprint. This file is optional, as you can generate Blueprint using the programming language you prefer.
• XML-Schemas for validating the config.xml and gallery.xml files and the Blueprint itself.
• The Blueprint specification guide (Extensive documentation.)
• A readme file with a short overview of the platform and the steps to create, test, and publish a widget. This file also contains some tips on handling HTTP headers and setting them up in your server.
• The Release Notes of the current version. Interesting stuff if you have been playing around with the beta version. There are some changes.
• Some widget examples.

An example is worth one thousand words

Let’s take a simple example--displaying the content from the RSS feed for the YDN blog. Note: There’s an RSS snippet that already does this, but since most widgets need to parse some kind of XML, , this is a good example to start with.

First,create the XML file that describes your application, config.xml, and pack the images that we are using as icons. Instead of starting from scratch, go to the Blueprint 1.0 SDK you downloaded and copy the whole folder under Samples/Hello World/submission. Edit the config.xml and make the obvious changes to the name of the application and the author. Now, focusing on the important stuff, make the widget element look like this:

<widget base="http://_YOUR_SERVER_/_YOUR_PATH">
  <preview>
    <icon>ybang</icon>
    <label>YDN blog</label>
  </preview>
  <shortcuts>
    <item default="true">
      <label>YDN blog</label>
      <href>index.php</href>
    </item>
  </shortcuts>
</widget>

A note on images

One of the challenges of developing mobile applications is to have them look good on any device. Image size is always a challenge. See that <icon> element in the code above? Now take a look at the resources/images folder. See the naming convention on the icons? Those icons are named after the identifier used in the <icon> element, as well as their width and height. Based on screen size, the platform will try to get the size that is the best match. You can include up to five different sizes. The optimal relationship between image size and screen type is detailed in the Blueprint specification manual included in the SDK.

If you want custom images for your widget, add them to the resources/images folder following this naming convention and change the value of the <icon> element in the config.xml file.

Generating the Blueprint code

We are going to develop our example application on PHP. Well, actually, we are going to use XSLT. I’ve developed about ten widgets so far, all with XSLT. When it comes to XML transformations, XSLT is your friend. With a simple XSL template, it’s a piece of cake to get an RSS or API response, (usually XML), and transform it to Blueprint. PHP helps us set the HTTP headers and put together the XML files with the XSLT sheets.
The two first lines in our code set the content-type of our output and the cache control. This last is very important for the Java client to work properly.

The rest is pretty obvious. We take the feed, the XSLT, and we put them together:

<?php
  header( "Content-Type: application/x-ywidget+xml" );
  header( "Cache-Control: no-cache" );

  $xsl = "ydn.xsl";

  $xml = "http://developer.yahoo.com/blog/index.xml";

  $xslt = new XSLTProcessor();

  $xslt->importStyleSheet(DOMDocument::load($xsl));

  echo($xslt->transformToXML(DOMDocument::load($xml)));

?>

And this is how the XSLT looks:

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="XML" encoding="utf-8" 
              doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
              doctype-system=http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd
              indent="yes"/>

    <xsl:template match='//channel'>

      <page>

        <content>

          <module>

            <header layout="simple">

              <layout-items>

                <block class="title">YDN Widget</block>

              </layout-items>

            </header>

          </module>

          <xsl:apply-templates select="item" />

        </content>

      </page>

    </xsl:template>

    <xsl:template match="item">

      <placard layout="card" class="link">

        <layout-items>

          <image resource="ybang"/>

          <block class="title"><xsl:value-of select="title"/></block>

          <block class="description"><xsl:value-of select="pubDate"/></block>

          <block class="subtext"><xsl:value-of select="category"/></block>

        </layout-items>

        <load resource="{link}" event="activate"/>

      </placard>

    </xsl:template>

</xsl:stylesheet>;

As you can see, there is no rocket science here. Take a look at the Blueprint spec to understand each element and its variations. Looking at the code above you can see some nested containers (page, content, section, placard…), some automatic layout managers, blocks of text, images, and actions (load).

Test it

Go to http://mobile.yahoo.com/developers/test and click the yellow “Test Widget” button in the upper right. You’ll be presented with a form to upload a file. Put your config.xml file, your resources directory and, optionally, your gallery.xml into a folder and compress that folder in a zip file. Upload this zip file.

You will need a valid Yahoo! ID. Only this Yahoo ID will have access to the widget until you publish it on the gallery.

Now, go to http://beta.m.yahoo.com. At the top right corner, you’ll find three icons. The one in the middle, with the gears, takes you to the widget zone. Scroll down to the bottom to find your brand new widget.

From your mobile device, you can do the same using your browser. If you downloaded the Yahoo! Go v3 client, you will see your recently created widget in the carousel.

Distribution comes for free

Well, that’s pretty much it. Take another look at the spec, learn some more about the possibilities Blueprints offers, and play around.

Oh, I almost forgot - you probably want people to use your application, right? Here’s the deal: make sure you created your gallery.xml file when you packaged your application. Go to http://mobile.yahoo.com/developers/submit, follow the “Submit Widget” button, accept the terms of service, and upload your zip file again, this time to the public gallery. Once it’s approved, your widget will be listed on our public gallery, where it can be reached by millions of Yahoo! users.

Jose Palazon , Mobile Software Engineer Yahoo! London