Working with Data

Contents

1. Overview
2. Data Sources
   1. RSS and Atom feeds
   2. Other built-in feeds
3. Reading and Displaying Data
4. Writing Data
5. Operating on Feeds
6. Access Control for Feeds
7. Ratings and Labels
8. Data Hierarchy
9. Introduction to XPath
   1. Getting XPath Syntax from the Feed Browser

Overview

Google Mashup Editor (GME) applications give you powerful features for reading, writing, and displaying data. Data in GME applications is always stored as a Google Data (better known as GData) feed. GData is a data protocol based on Atom and the Atom publishing protocol (APP). Data not natively stored in the GData format, such as data from RSS feeds, are automatically converted to GData by GME through an XSL transformation. This ensures that all data is read, written, and manipulated in the same common format, which makes it easy to operate on different types of data from different sources with GME modules.

GData's extensibility gives you the flexibility to create your own feeds containing the data you want to store. By extending the feed with custom elements or using elements already available in GData, you can create structured data feeds that are easy to manipulate using XPath, a regular expression-based language that allows you find elements in GData feeds. To learn more about how to use XPath, see the Introduction to XPath.

Data Sources

There are many data sources available for use in your GME applications. Some sources allow you to read and write, while others are read-only.

Each GME application provides built-in data feeds that allow users to read and write data.

${app}

The ${app} feed is specific to the GME application instance. Initially, the feed is empty. All users of your application can read data from and, if you enable it, write data to the ${app} feed. When you write to the ${app} feed, you can specify a path one level deep, called a stripe. For example, if you want to have two application-wide data stores for your Google Maps mashup (one for markers and one for a customer list), you can create the ${app}/markers stripe and the ${app}/customers stripe and use them separately in your application. For more about writing data to a feed, see Writing Data.

${user}

Each user of your application has access to a separate ${user} feed. Users can read and write data to their own personal feeds, but users don't have access to anyone else's feed. Initially, this feed is empty. Your application must provide a way for users to add data. When you write to the ${user} feed, you can specify a path one level deep, called a stripe. For example, if you want to have two user-specific data stores for your Google Maps mashup (one for the user's locations and one for the user's profile information), you can create the ${user}/locations stripe and the ${user}/profile stripe and use them separately in your application. For details on writing data to a feed, see Writing Data.

${tmp}

When you display data using ${app} or ${user}, the data is stored on the server so that it can persist between sessions. However, sometimes you won't care about persistent data. For example, you might create a mashup that reads the next 5 events from your calendar and displays them. Because the mashup reads the calendar events every time you run it, you don't need to save the events in the ${app} or ${user} feeds. Because reading and writing these feeds can cause brief delays in your mashup, you can use the ${tmp} feed to store data that you don't need to keep between sessions. The ${tmp} feed stores data in memory, eliminating the delays for reading and writing server data

RSS and Atom feeds

You can use any RSS or Atom feed as a data feed for GME modules. External RSS and non-GData Atom feeds are read-only. RSS feeds are automatically converted to GData (Atom) feeds through an XSL transformation. Custom extension elements are preserved during the transformation and can be accessed in the same way as Atom elements, through XPath queries.

You can use GME's handy feed browser to see how RSS feeds are transformed. Click the Feed Browser tab and select Remote Feed from the drop-down menu. Type the URL to the RSS feed, then click the Get Data button. You'll see all the elements available in the feed.

The feed browser can help you figure out the right XPath syntax to use for feeds. To learn how this works, see Getting XPath Syntax from the Feed Browser.

Other built-in feeds

In addition to ${app}, ${user}, and ${tmp}, GME provides several other built-in feeds:

• ${base} - Search Google Base for items using this feed (read-only).
• ${members} - Contains the names of the members of this application.
• ${test} - A test feed with various types of data, suitable for testing your applications (read-only).
• ${annotations} - Contains data entries associated with another feed. See Ratings and Labels.
• ${labels} - Contains the names of label annotations. See Ratings and Labels.
• <gm:data/> - To create data inline in your source and build on that data, you can use a <gm:data> tag.

Reading and Displaying Data

To read data in your GME application, you must include a module tag, such as a list, that accepts a data source in its data attribute. You'll probably want to include a template tag that references the data elements you want to read. If you don't include a template, GME uses a built-in template named "default".

In the following example, a list module reads entries from Digg and displays the title of each entry by referencing its atom:title element.

<gm:page title="myApp">

  <gm:list id="myList" data="http://www.digg.com/rss/index.xml" template="myListTemplate"/>
  <gm:template id="myListTemplate">
    <div repeat="true">
      <gm:text ref="atom:title"/>
    </div>
  </gm:template>

</gm:page>

In the gm:template tag, we specify how the data will look when displayed. The template must have one repeating element in order to display multiple entries. In this case, we set the <div> element to repeat by adding the repeat attribute to the <div> tag and setting it to true. This creates a div for every entry in the feed. You can use the repeat attribute in any HTML element in a gm:template tag. For example if you want to create a table with a repeating row, you can put the repeat attribute in the <tr> or <tbody> HTML element.

Within the <div> we specify a <gm:text> tag and have it refer to atom:title in the feed. The value of the ref attribute is actually an XPath query to the element in the feed. The title of each entry is specified by the XPath query atom:title. For more on XPath, see the Introduction to XPath section.

In addition to defining your own templates, GME supplies built-in templates you can use for displaying data. To use a built-in template, you specify it by name in the template attribute; for example:

<gm:list id="myList" data="http://digg.com/rss/index.xml" template="default" />

The built-in templates are as follows:

• simple, a basic template.
• task, suitable for a task list.
• blog, which shows the headlines from a blog feed or similar information.
• base, useful for displaying product queries from Google Base.
• contact, best used for displaying contacts.
• default, a minimal template that shows headlines in a table.
• debug, which displays every element of the feed.
• articlelist, good for showing articles, as from a blog feed.

Writing Data

To write data to a feed in your GME application, you must include the following three tags:

• A module, such as a list, that accepts a writable data source in its data attribute.
• A template that references the data elements you want to write.
• A gm:create tag to add new data or a gm:editButtons tag to edit and delete data.

In the example below, a list module reads data from the ${app}/foo stripe. The list module also displays a create button below the list and edit and delete buttons next to each item in the list.

<gm:page title="myApp">

  <!-- Here we create the list to display the data we save 
       in the $app/foo feed -->

  <gm:list id="myList" data="${app}/foo" template="myListTemplate"/>

  <!-- Here we create the template that contains edit
       and delete buttons. We also specify a create button to add
       data to the feed. -->

  <gm:template id="myListTemplate">
    <table>
      <tbody repeat="true">
        <tr>
          <td><gm:text ref="atom:title"/></td>
          <td><gm:editButtons /></td>
        </tr>
      </tbody>
    </table>
    <gm:create label="Create new entry"/>
  </gm:template>

</gm:page>

The template allows the user to read and write an element using the same control -- gm:text, in this case. To add the ability to edit an entry, all we need is a gm:editButtons tag somewhere in the repeating element. In this case, we've added it right next to the text we display. The gm:editButtons tag adds two buttons to the HTML element that contains it: one for editing the entry and one for deleting the entry. When an entry is deleted, it's removed from the data store and can no longer be accessed.

By default, the edit buttons are image buttons. You can have them displayed as textual buttons by adding text="true" to the editButtons tag.

To create a new entry in the feed, we place a gm:create tag outside the repeating element. When the user clicks the create button, a new row appears and the user can enter data. That data is saved to the feed according to the reference attribute for that item. In the example above, a new entry is created and the data entered by the user is saved into the atom:title element of the newly created entry. Again, atom:title is just an XPath query to an element in the feed. If you're using the ${app} or ${user} feeds and you create an XPath query to an element that is not currently in the feed, that element is created for you.

The ${app} and ${user} feeds are extensible XML documents, so you can add any elements you want. To add elements that aren't defined by the atom: or gd: namespaces, use the gmd: namespace. For example if you want to store a time element in the feed, you can reference it with the query gmd:time, and any data you store will appear in the feed as the gmd:time element.

Operating on Feeds

GME provides various features you can use to work with feed data, such as reading, writing, searching and so on. In order to optimize performance of your applications, not all features are available for all feeds. The following matrix shows which features you can use on which feeds:

Feed	Read	Write	Paging	Search
${app} and ${user}	Yes	Yes	Yes
External RSS/Atom feeds	Yes		Yes
${members}	Yes		Yes
${base}	Yes		Yes	Yes
${test}	Yes		Yes

For information on which feeds and elements can be used for filtering, see the sorting and filtering document.

Access Control for Feeds

When you publish a GME application, you can control access to the feeds that belong to it. For each application, you have access control over these built-in feeds: ${app}, ${user}, and ${members}. For the ${app} and ${user} feeds, you can specify separate access settings for members and for non-members; the ${members} feed is available to members only.

For members, you can specify read and write, read-only, or no access for each feed. For non-members, you can specify read-only or no access for the ${app} and ${user} feeds.

The following table summarizes these access options:

Feed	Access options for members	Access options for non-members
${app}	Read and write all, Read all and write own entries, Read-only, No access	Read and write all, Read all and write own entries, Read-only, No access
${user}	Read and write all	Read-only, No access
${members}	Read and write all	none
	(Default setting is in bold)

The Read and write all setting means that users can read and write all entries in the feed. Read all and write own entries means users can read entries made by all users, but can only write to or edit their own entries. Read-only means users can read all entries but can't write any entries. No access means users can't read or write any entries.

To specify access settings for feeds, click the Published Apps tab on the right side of the Editor screen, then click an application to select it. Use the drop-down menus on the right to select access settings.

You can also use this page to manage membership in your application. Click the Members tab to see the membership controls. To add a member, type the new member's Google Account name in the box, then click Add. To remove a member, click to select the member, then click the trash can next to the name.

Use the following syntax to refer to the user feed for a particular user:

${user}:abc@gmail.com/

where abc@gmail.com is the user's Google Account ID.

Ratings and Labels

When you read and display a feed, you can create data elements, called annotations, that are associated with entries in the feed. For example, you can read a feed of real estate data, then create associated gm:rating elements that include your ratings on each entry in the real estate feed. Because the associated data is stored in a separate feed by your application, you can create annotations for read-only feeds as well as feeds that provide write-access. You can use the annotations feed to store two kinds of data: numeric ratings and textual labels.

All annotations for an application are stored in and retrieved from the built-in ${annotations} feed. Each annotation is associated with one element in the feed. When you display an element, you can also display any annotations for that element. The syntax for a data source that combines a feed with annotations is:

http://somedata.com/somefeed/rss | ${annotations}

Use this syntax for referring to items that have a particular label:

http://somedata.com/somefeed/rss | ${annotations}:(somelabel)

To display data from the annotations feed, you set the data source to the feed combined with the annotations. For example, if you want to display a list with ratings annotations, sorted from highest rated to lowest, you could use the following:

<gm:list id="annotatedList" data="http://digg.com/rss/index.xml | ${annotations}" 
         pageSize="10" sort="rating" template="t">
  <gm:sort ref="gd:entryLink/entry/gd:rating/@value" name="rating" reverse="true"/>
</gm:list>

To restrict the list to a particular label, you can use this syntax for the data source:

data="http://digg.com/rss/index.xml | ${annotations}:('favorite')"

GME provides the ${labels} feed, a built-in feed containing all labels used by your application. By iterating over the ${labels} feed, you can display data entries associated with all the labels your application uses. You can set or change the data source dynamically using JavaScript and the setData function, as described in the JavaScript API document.

You use gm:rating and gm:labels tags in your template to display the ratings and labels associated with a particular feed.

For more information about annotations and labels, see this example. For more about the syntax you use to refer to data elements in a feed, see the Introduction to XPath.

Data Hierarchy

Some applications require a hierarchy of data, in which each element at an outer level contains specific data at a secondary level. One example of this kind of application is a task list. In a task list, you often have a list of projects, each of which contains a list of tasks. In order to associate projects to lists of data, you can reference the feed of the parent list by id in the data attribute of the child list. As with all built-in feeds, you reference the feed using the feed variable substitution method (that is, ${feed_name}), as in the following example.

<gm:page title="hierarchy">

  <h1>Projects</h1>
  <gm:list id="Projects" data="${app}/ProjectData" template="myTemplate"/>

  <h1> Project tasks </h1>
  <gm:list id="tasks" data="${Projects}/taskData" template="myTemplate">
    <gm:handleEvent src="Projects" />
  </gm:list>

  <gm:template id="myTemplate">
    <table>
      <tbody repeat="true">
        <tr>
          <td><gm:text ref="atom:title"/></td>
          <td><gm:template type="img"/></td>
        </tr>
      </tbody>
    </table>
    <gm:create label="Create new entry"/>
  </gm:template>

</gm:page>

Introduction to XPath

GME applications use a small subset of XPath, a search and query language that allows you to refer to tags and attributes in an XML document. You use XPath to access namespaces, elements, and attribute names and values from data feeds, and you use XPath syntax in your applications to refer to feed elements for reading and writing. Here are the forms of XPath syntax you can use in Google Mashup applications:

"ns:elemName/ns:elemName2...."
"ns:elemName[@attr='val']/ns:elemName2[@attr2='val2']/...."
"ns:elemName[@attr='val']/ns:elemName2/...."

You can use text() and @attr expressions for text and attribute selection at the end of the XPath:

"ns:elemName/ns:elemName2/text()"
"ns:elemName/ns:elemName2/@attr2"
"ns:elemName[@attr='val']/ns:elemName2/@attr1"

You can see examples of XPath syntax in most GME sample applications. Note that GME supports only the subset of XPath described here, not the full specification. For more information on XPath, see this Introduction to XPath on the Web.

Getting XPath Syntax from the Feed Browser

You can use the feed browser to find the XPath syntax for any element in a feed. Just follow these steps:

1. In the Editor, click the Feed Browser tab.
2. Choose Remote Feed from the drop-down menu and type the URL of the feed you're interested in.
3. In the display, elements in feed entries are underlined. Point to any underlined entry and hover. You'll see the XPath expression for that element in the hover text.

   

4. To add the XPath expression to your mashup, click the underlined entry. The XPath expression appears below the feed content. Select and copy the XPath, then paste it into your mashup.