From MojiPage Wiki

Jump to: navigation, search

Tutorial: Creating Your First Widget

In this tutorial, we will show you how to write a custom widget for I Can Has Cheez Burger using the simple yet powerful MojiPage Widget API. We will load the RSS feed from the ICanHasCheezBurger site, and then display the first entry found.

Contents


MojiPage Widgets Are Simply XHTML Files

The term "widget" really sounds more complicated than it is. A widget is simply a self-contained XHTML file, which optionally contains embedded CSS for styling and Javascript for interactivity.

Let's start with a simple widget: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:widget="http://www.netvibes.com/ns/">
  <head>
    <title>ICanHasCheezBurger Widget</title>
  </head>
  <body>
    <div>My First MojiPage Widget</div>
  </body>
</html>

As you can tell, this is nothing more than a static XHTML file. The only requirement that MojiPage imposes is that the XML has to be well-formed, so it is a good idea to make sure that you have no unmatched open tags, improper nesting, etc.


Adding Your Widget to MojiPage

Now that you have the skeleton widget, we are ready to add it to MojiPage to get some instant gratification! MojiPage does not currently provide files hosting, so you will a publicly accessible web site that you can upload your widget to. The quickest way to get started is using Google Page Creator which allows you to upload HTML files.

  1. Save the HTML above into a file ending with .html (e.g. tutorial1.html)
  2. Upload it to your web site
  3. View it on your browser and note the URL (e.g. http://dready.googlepages.com/tutorial1.html)
  4. Go to MojiPage and log in
  5. Click on the "Add Content" link, scroll down to the bottom of the page and click "Add by URL"
  6. Type the URL to your widget and click "Add"
  7. MojiPage should download widget off your web site and display it!


Describing Your Widget

In order to make this a full-fledged widget with interactive content, we need to add some properties to tell MojiPage how to work with it: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:widget="http://www.netvibes.com/ns/">
  <head>
    <title>ICanHasCheezBurger Widget</title>

    <meta name="author" content="Great Widget Hacker" />
    <meta name="description" content="Shows the latest ICanHasCheezBurger image" />
    <meta name="version" content="1.0" />
    <meta name="apiVersion" content="1.0" />
    <meta name="debugMode" content="true" />

  </head>
  <body>
    <div>My First MojiPage Widget</div>
  </body>
</html>

We have added 5 <meta> tags to the <head> element of the XHTML, most of which are self-explanatory. There are, however, a few points to note.

  • author, and description and version are properties determined by you, and are used in the widget directory when your widget is listed.
  • Until we release a new API that significantly differs from the current version, the apiVersion should always be 1.0.
  • debugMode will allow you to log messages while the widget is being executed, and view them on MojiPage to aid debugging.


Loading Remote Content

We are now ready to add some interactivity to the widget. Here's the complete widget code, which we will explain the following text: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:widget="http://www.netvibes.com/ns/">
  <head>
    <title>ICanHasCheezBurger Widget</title>
    <meta name="author" content="Great Widget Hacker" />
    <meta name="description" content="Shows the latest ICanHasCheezBurger image" />
    <meta name="version" content="1.0" />
    <meta name="apiVersion" content="1.0" />
    <meta name="debugMode" content="true" />

    <script type="text/javascript" src="http://www.mojipage.com/js/mwa.js"></script>
    <script type="text/javascript">
    <![CDATA[
      // define a handler to run when the feed is fully loaded
      widget.onFeed = function(feed) {
        // get the first item
        var item = feed.items[0];

        var el = widget.createElement('div');
        el.innerHTML = item.content.replace(/<script.*?>|<\/script>/i, '');
        widget.setBody(el);
      }

      // the widget.onLoad function is called when the widget is first executed.
      widget.onLoad = function() {
        var feed = "http://feeds.feedburner.com/ICanHasCheezburger";
        UWA.Data.getFeed(feed, this.onFeed);
      }
    ]]>
    </script>
  </head>
  <body>
    <div>My First MojiPage Widget</div>
  </body>
</html>

Include the MojiPage Widget API

First of all, we need to include the MWA (MojiPage Widget API) javascript, which provides much of the API functionality. We do this by adding a <script> element to the <head> element: 

    <script type="text/javascript" src="http://www.mojipage.com/js/mwa.js"></script>

This tag should appear before any other Javascript that uses MWA.


Implementing the onLoad handler

Next, we add another <script> element that will contain our widget code. The first step in writing any widget is to implement the widget.onLoad function (second definition in the block.)

When MojiPage executes a widget, it runs this function, which kicks off everything. Let's look at it closely: 

      widget.onLoad = function() {
        var feed = "http://feeds.feedburner.com/ICanHasCheezburger";
        UWA.Data.getFeed(feed, this.onFeed);
      }
  1. The first line defines an anonymous function and assign it to the widget.onLoad property.
  2. The second line assigns the RSS feed URL for ICanHasCheezBurger to a variable named feed.
  3. The third line uses the UWA feed loader API function UWA.Data.getFeed() to fetch the content of the feed. The second argument specifies the function that handles the feed data when it is fully loaded.


The Feed Handler 

      widget.onFeed = function(feed) {
        // get the first item
        var item = feed.items[0];

        var el = widget.createElement('div');
        el.innerHTML = item.content.replace(/<script.*?>|<\/script>/i, '');
        widget.setBody(el);
      }

When the feed has been successfully fetched, the function that you passed to the UWA.Data.getFeed() function will be called, with the feed object as its first argument.

  1. For convenience, we assign the first item in the feed to a variable called item.
  2. Create a <div> element for the feed content.
  3. Use the innerHTML property to place the content of the item into the element that we created above.
  4. Replace the contents in the widget body with our <div> (the existing <div> in the body will be removed)

For more information about the UWA.Data.getFeed(), please see [UPDATE ME]

If you haven't done so already, modify your widget code and upload it onto your web site, then refresh the page in MojiPage.


That's it! You now have a widget that displays the first item from ICanHasCheezBurger!


Languages:   English  • 日本語

Retrieved from "http://wiki.mojipage.com/Tutorial:_Creating_Your_First_Widget"
Personal tools