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.
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
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.
In addition to ${app}, ${user}, and ${tmp}, GME provides several other built-in feeds:
<gm:data> tag. 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.To write data to a feed in your GME application, you must include the following three tags:
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.
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.
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.
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.
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>
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...."You can use
"ns:elemName[@attr='val']/ns:elemName2[@attr2='val2']/...."
"ns:elemName[@attr='val']/ns:elemName2/...."
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.
You can use the feed browser to find the XPath syntax for any element in a feed. Just follow these steps:
