Creating a Flake that Calls a Web Service

Next we’ll create another example flake. This flake will retrieve the value of weather for a region and display it in the flake. To create this flake, we'll need to add code to call a remote web service, then add a callback function that will handle the data retrieved by the service.

Here is Flake User Object code that demonstrates the use of a callback function:

  <script id='com.pageflakes.devdocs.weatherflake' type='text/javascript'>

    function com_pageflakes_devdocs_weatherflake(id)
    {
      this.id = id;
      this.fso = null;
    }

    com_pageflakes_devdocs_weatherflake.prototype = {
      
      load : function (fso)
      {
        this.fso = fso;
        ContentProxy.GetUrl("http://xml.weather.yahoo.com/forecastrss?p=80301&u=c",
                                PF.F(this, this._callback));  
      },

      _callback : function(result)
      {
        var xml = PF.getXmlDoc(result);
  
        var desc = PF.getFirstNode(xml, "item:description").firstChild.nodeValue;
        var title = PF.getFirstNode(xml, "title").firstChild.nodeValue;
    
        var div = $(this.id + "current_weather");
        div.innerHTML = desc;
  
        if (this.fso.title != title)
        {
          this.fso.setTitle(title);
          this.fso.save();
        }

        xml = null;
      }
    };
    </script>

In this example, the class containing the code is com_pageflakes_devdocs_weatherflake. This class takes a single parameter, id, which contains a unique identifier for the flake being created. This id is what the framework uses when it replaces the _PAGEFLAKES_ string described in the previous example.

The Flake User Object can contain as many variables and functions as your flake requires. However, there is one function that is mandatory: the load() function. The Pageflakes framework calls load() after it instantiates the Flake User Object and is ready to load the flake on the page.

The load() function takes a single parameter, fso, which holds a reference to the Flake System Object. The fso parameter is stored for future use (see next example). The Flake System Object enables the Flake User Object to interact with the Pageflakes framework and make use of the framework API.

Note:

• The <script> block is included only once in the Generated XHTML Document. The framework does this by using the id attribute of the script. It is important to select the id attribute carefully to avoid conflicts with other flakes. One way to do this is to use a reverse domain name, as shown in the example.
• Similarly, the Flake User Object function defined within the <script> block must also be named uniquely. You should use the same naming convention you use with script block itself, replacing the "." character with the underscore ("_").
• All of your flake's variables and functions should be defined within its Flake User Object function. Any member defined outside the Flake User Object function may collide with the Pageflakes framework or other Flakes.

When the Pageflakes framework calls your flake's load() function, the flake:

1. Uses the ContentProxy to fetch an XML document containing the weather for the 80301 zip code. We’re hard coding this zip code in the URL for now.
2. When the ContentProxy retrieves the data, it calls the _callback() function with an XML string. The PF.F(this, this._callback) ensures that the callback is fired in the context of this, not in the context of the calling ContentProxy object. If the callback were set directly, then the this reference would be unusable inside _callback as it would not refer to the flake user object.
3. The callback() function uses the Pageflakes functions to extract the <title> and <description> elements of the XML document.
4. The "current_weather" <div> element is retrieved from the HTML markup and filled with retrieved weather content. The id attribute is prepended to ensure the correct <div> element is retrieved.
5. The Flake System Object sets and saves the title for the flake.

Putting it all together, the weather flake looks like this:

<html>
  <head>
    
    <title>Weather Flake</title>

    <script id='com.pageflakes.devdocs.weatherflake'
        type='text/javascript'>

    function com_pageflakes_devdocs_weatherflake(id)
    {
      this.id = id;
      this.fso = null;
    }

    com_pageflakes_devdocs_weatherflake.prototype = {
      
      load : function (fso)
      {
        this.fso = fso;
        ContentProxy.GetUrl("http://xml.weather.yahoo.com/forecastrss?p=80301&u=c",
                            PF.F(this, this._callback));  
      },

      _callback : function(result)
      {
        var xml = PF.getXmlDoc(result);
  
        var desc = PF.getFirstNode(xml, "item:description").firstChild.nodeValue;
        var title = PF.getFirstNode(xml, "title").firstChild.nodeValue;
    
        var div = $(this.id + "current_weather");
        div.innerHTML = desc;
  
        if (this.fso.title != title)
        {
          this.fso.setTitle(title);
          this.fso.save();
        }

        xml = null;
      }
    };

    </script>

    <script id='_PAGEFLAKES_Instance' type="text/javascript">
      var _PAGEFLAKES_ = new com_pageflakes_devdocs_weatherflake('_PAGEFLAKES_');
    </script>

  </head>

  <body>
    <div id='_PAGEFLAKES_current_weather'/>
  </body>

</html>