English | Site Directory

Google Mashup Editor

Getting Started Guide

Contents

  1. Using Google Mashup Editor
  2. Hello World!
  3. Structure of a Mashup Application
  4. Displaying a Data Feed in a Simple List
    1. Defining the user interface
    2. Create the template and reference the data source
    3. Adding the list tag
    4. Specifying the data source
    5. Applying a visual theme
  5. Creating a Simple Mashup with a Map
    1. Specifying the list
    2. Creating the map
    3. Handling user clicks
  6. Reading and Writing Data
    1. Specify the projects display
    2. Set up the tasks display
    3. Create the overall display and handle events

Using Google Mashup Editor

Google Mashup Editor (GME) is an interactive development environment in which you edit, compile, test, and manage your applications. The editor includes a built-in reference guide to all GME tags and attributes. When your application is finished, you can publish it on Google's servers, where it's available for others to run.

Here's an introduction to various key parts and functions of GME:

  • Editor

    The editor is a text panel that contains the <gm:page> </gm:page> tags. You create your application by placing all of your HTML, CSS, JavaScript, and GME tags between the <gm:page> tags.

    Any viable HTML, CSS, or JavaScript that's usually placed between the <body> and </body> tags can go into your application. GME provides syntax error checking and highlighting for your source. When you compile your application for testing and publishing, all the GME tags are transformed into JavaScript. You can view the resulting HTML document that contains your application by navigating to the View -> Page Source in your browser's menu.

    What about debugging? The best tool we've found for debugging JavaScript applications is Firebug, a Firefox extension that allows you to view JavaScript errors, inspect the DOM, and debug JavaScript (set breakpoints, view variables, and so on).

  • Managing Projects and Files

    You can use the File menu in the header to save your project, create a new one, test your project, and publish it. For faster service, you can also click the Test button at the top of the editor to test your application.

    You can use the links on the right side of the screen to see the projects you've created, as well as a list of sample applications we've built to help you get started.

  • Publishing Applications

    You can try out your application whenever you want by clicking Test. Once you're satisfied that it's ready to go, you can use the File > Publish Project menu item to deploy your application on Google's servers. When you publish your application, GME will show you a URL; that's the URL where your application is hosted.

    You can also deploy your application as a Google Gadget. To do this, choose File > Submit Gadget in the Editor. This creates a Google Gadget and a gadget.xml file containing settings for the gadget. You can edit the gadget.xml file directly in the Editor.

  • Google Hosts your Code

    Applications you create are hosted by Google. Your source code and uploaded resource files are stored using the open source project hosting feature of Google Code. When you start a new project, GME creates a new, public open source repository on Google Code to store your source files and other resources associated with your project. The source code is created under the Apache 2.0 open source license. You can change the license any time, using the project hosting feature of Google Code. You can also use the subversion repository on Google Code to edit your files outside of GME.

    To access your projects in Google Code, use the following URL format: http://code.google.com/u/<your gmail username>. You'll see a list of your projects, and you'll be able to browse their files and change settings.

  • Additional Files

    You can use additional files with your application. To add existing files to your project, choose File > Upload Resource File in the Editor, or use File > New Source File to create a fresh file. You can use the Editor to edit your HTML, XML, CSS, and other text files.

  • Reference Guide

    Figure out how to use Google Mashup Editor by exploring our Tag Reference. You can see descriptions from the Tag Reference right in the editor by clicking a GME tag and pressing F2 on your keyboard.

Hello World!

The "Hello World!" program for Google Mashup Editor couldn't be easier.

<gm:page title="hello">
  <h1>Hello World!</h1>
</gm:page>

That's it! This application creates a page that contains the text Hello World styled as a header. You see that we've mixed gm:page, a GME tag, with h1, an HTML tag. This illustrates one of the great strengths of GME: you can use any HTML, CSS, or JavaScript syntax alongside GME tags in your applications.

Structure of a Mashup Application

The following diagram shows the general structure of applications created with Google Mashup Editor:

mashup application structure

Displaying a Data Feed in a Simple List

Many GME applications provide a way for users to interact with data from a feed. You can often use the following steps to create your application:

  • Define the user interface.
  • Specify a template from the UI components that includes a repeating element.
  • Specify a GME module (such as a list) that uses the template.
  • Define the source of the data that will appear in the template.
  • Decide how modules will interact with each other and handle events, such as selection.

Let's walk through some examples.

Defining the User Interface

Google Mashup Editor applications consist of HTML, CSS, JavaScript, and Google Mashup (gm:) tags. Using HTML and CSS, we first define how we want our display to look. In this application, we want to display the title of the application, followed by a table that shows the title and "digg count" of the entries in an RSS feed from digg.com. We'll use HTML for this, with GME's gm:page tag added. 

<gm:page title="Mashup">

  <h1>Hello World!</h1>

  <table>
    <tr>
      <td>story title</td>
      <td>digg count</td>
    </tr>
  </table>

</gm:page>

For now, we simply define how we want one row of the display to look. Later, we'll make it so that this row layout is repeated for each item in the data source.

Create the template and reference the data source

After we've created the table that determines how a display row will look, we need to turn the table into a template. To change the table into a template, we need to make 3 changes:

  • Add the gm:template tags.
  • Add a repeat attribute to the element that will be repeated for each item in the data source.
  • Replace the text "story title" and "digg count" with references to the data we want in the source.

Let's take the table we defined earlier and add the required template elements.

Add the template tags:

<gm:template id="diggTemplate"> 
  <table>
    <tr>
      <td>story title</td>
      <td>digg count</td>
    </tr>
  </table>
</gm:template>

Now add the repeat attribute to the element we want to repeat -- in this case, a row, represented by the tr tag. This will create a new row for each item in the data source. 

<gm:template id="diggTemplate">
  <table>
    <tr repeat="true">
      <td>story title</td>
      <td>digg count</td>
    </tr>
  </table>
</gm:template>

Next, we replace the placeholder text "story title" and "digg count" with gm:text tags that have references to the source data. Because of the repeat attribute, the row tags will be repeated for each item in the data source. GME converts every data feed to Atom feed format so that accessing data is standardized. In this case, we want to grab the atom:title and digg:diggCount elements of each entry and display them as text in table rows. 

<gm:template id="diggTemplate">
  <table>
    <tr repeat="true">
      <td><gm:text ref="atom:title"/></td>
      <td><gm:text ref="digg:diggCount"/></td>
    </tr>
  </table>
</gm:template>

Adding the list tag

Next, we need to add a list tag to specify the template we're going to display: 

<gm:page title="Mashup">

  <h1>Hello World!</h1>

  <gm:list id="diggFeed" template="diggTemplate"/>

  <gm:template id="diggTemplate">
    <table>
      <tr repeat="true">
        <td><gm:text ref="atom:title"/></td>
        <td><gm:text ref="digg:diggCount"/></td>
      </tr>
    </table>
  </gm:template>

</gm:page>

Specifying the data source

You can use any RSS or Atom feed as a data source in your GME applications. (There are also built-in data sources that we'll show you later; if you don't want to wait, you can read about them here.) You use the data attribute to associate data sources with lists and other modules.

In our example, we specify a feed from digg.com as the source of our feed reader list by doing the following.

<gm:list id="diggFeed" data="http://www.digg.com/rss/index.xml" pagesize="10" template="diggTemplate"/>

The pagesize attribute tells how many rows of data to display.

Applying a visual theme

GME provides a set of visual themes, available in 7 different colors, that you can use to make your mashups look great. To use a theme, you specify its CSS class in a <div> or <table> tag, like this:

<table class="blue-theme">

When you use a theme on a table, the theme provides a style for the following elements in the table: th, td, tfoot, gm:text, gm:header, gm:footer.

When you use a theme on a div, the theme will provide a style for the following elements in the div: gm:header, gm:item, gm:footer.

Here's the complete list of themes:

blue-theme
gray-theme
orange-theme
purple-theme
green-theme
red-theme
black-theme

You can try out all the themes here: http://themeviewer.googlemashups.com. For our sample, we'll use the purple theme (adjust to suit your personal taste): 

<table class="purple-theme">

We're done! Here's our completed application that reads a feed from digg.com and displays the titles and digg count of stories:

<gm:page title="Mashup">

  <h1>Hello World!</h1>

  <gm:list id="diggFeed" data="http://www.digg.com/rss/index.xml" pagesize="10" template="diggTemplate"/>

  <gm:template id="diggTemplate">
    <table class="purple-theme">
      <tr repeat="true">
        <td><gm:text ref="atom:title"/></td>
        <td><gm:text ref="digg:diggCount"/></td>
      </tr>
    </table>
  </gm:template>

</gm:page>

You can change the data attribute to point to any RSS or Atom feed. Your GME application will get data from the locations in the feed you've specified and put the data into the template.

Creating a Simple Mashup with a Map

Google Mashup Editor provides an easy way to create interactive applications that use powerful components. In our next example, we'll get a list of park names and locations from a data feed. We'll display the information in two ways: as a textual list, and as a map. And we'll hook them up so that when we select an item in the list, the selected park will scroll to the center of the map.

Specifying the list

We'll start by creating a list module and specifying how to display it:

<div style="float: left; width: 50%">
  <gm:list id="CAParks" data="http://www.mapnut.com/calstatepark.xml" pagesize="25"/>
</div>

As in the previous sample, we specify the data source feed and the number of items we want to list. There are a couple of new wrinkles this time. First, we haven't specified a template. Without a template, the data will appear by default as a bulleted list. Second, we're using a div tag to give the list 50% of the window width.

Creating the map

Next we'll specify the map module: 

<div style="float: left; width: 50%">
  <gm:map id="CAParkMarkers" data="${CAParks}" latref="geo:lat" lngref="geo:long">
    <gm:handleEvent src="CAParks"/>
  </gm:map>
</div>

Take a look at the data attribute: it refers to the gm:list, which has CAParks as its ID. To grab the latitude and longitude from the feed, we request the geo:lat and geo:long elements.

Handling user clicks

The handleEvent inside the map tag creates the connection between the map and the list. Specifically, handleEvent lets its containing tag (the map, in this case) listen to another object (the list). When an item in the list is selected, the map is notified, and it scrolls the selected location to the center.

Here's the complete listing:

<gm:page title="Mashup">

  <div style="float: left; width: 50%">
    <gm:list id="CAParks" data="http://www.mapnut.com/calstatepark.xml" pagesize="25"/>
  </div>

  <div style="float: left; width: 50%">

    <gm:map id="CAParkMarkers" data="${CAParks}" latref="geo:lat" lngref="geo:long">
      <gm:handleEvent src="CAParks"/>
    </gm:map>

  </div>

</gm:page>

Reading and Writing Data

You can create applications with GME that not only read feeds, but write to them as well. This gives your application the power to accept and save user input. In this sample, we'll create a basic project list. Each project has a name and can have any number of tasks. The tasks within projects have a title and date.

Specify the projects display

We'll start by setting up the display for our list of projects. We don't know how many projects there are going to be, so we need a template that includes a repeat attribute.

<gm:template id="simpleProjects">
  <div repeat="true">
    <gm:text ref="atom:title"/>
    <gm:editButtons/>
  </div>
  <gm:create label="New Project"/>
</gm:template>

The repeat attribute specifies that we'll have a text object (the title) for each project in the list. The editButtons tag adds buttons to each entry that allow users to edit or delete the entry. When an entry is edited, it's saved to the data feed.

The create tag adds a "New Project" button to the template. This button is the key to letting users add projects to the list. When the user clicks New Project, the application creates a new entry as described by the template and displays it for the user to edit. When the user presses Enter or clicks the save button, the data is saved to the data feed.

Set up the tasks display

Next, we need to create a template that displays tasks within each project. Because each task can have multiple elements (such as task name and date), we'll create a table to define the display.

<gm:template id="simpleTasks">
  <table width="100%">
    <tr repeat="true">
      <td><gm:text ref="atom:title"/></td>
      <td><gm:date ref="gd:when/@startTime"/></td>
      <td><gm:editButtons deleteonly="true"/></td>
    </tr>
  </table>
  <gm:create label="new task"/>
</gm:template>

The first line in the repeat block is the task title, just like the one in the project template. The next tag references the task's date from the data feed. The last repeated line is another editButtons tag. This one includes the deleteonly attribute, which means that when existing tasks are displayed, only a delete button (and not an edit button) will appear.

Like the project template, the task template includes a create tag that displays a button. Users can click "new task" to add a new task to the data feed.

Create the overall display and handle events

To complete our application, we need to specify a table that will be used to display projects, one project per row. When a project is selected, its tasks will be displayed on the right, one task per row. We also need to specify that when the user clicks on a project, that project's tasks should be displayed.

<table width="100%">
  <tr>
    <td width="50%">
      <gm:list id="Projects" data="${app}/Projects" template="simpleProjects"/>
    </td>
    <td width="50%">
      <gm:list id="tasks" data="${Projects}/tasks" template="simpleTasks">
        <gm:handleEvent src="Projects"/>
      </gm:list>
    </td>
  </tr>
</table>

The td tags divide the table into two cells. The left cell holds a list object that gets the projects from the application's data feed, using the syntax ${app}/Projects. What's that? Each application includes its own data feed, which you refer to with the syntax ${app}. You can subdivide the information in this feed by using a slash in the syntax, like this: ${app}/Projects. When you use the slash syntax, you create a stripe, sort of a subdirectory of data in the feed.

Getting back to our application: the right cell displays the tasks and is connected to the data at ${Projects}/tasks. This hierarchy ensures that the list reads and writes the tasks that belong to each specific project.

The list tag that's defined for the right cell also includes a handleEvent tag. This handleEvent tag listens to the project's list tag, and when a selection event occurs there, the tasks list responds by loading and displaying the tasks that go with that project.

Here's the complete listing for our application:

<gm:page title="Task List" authenticate="true">

  <table width="100%">
    <tr>
      <td width="50%">
        <gm:list id="Projects" data="${app}/Projects" template="simpleProjects"/>
      </td>
      <td width="50%">
        <gm:list id="tasks" data="${Projects}/tasks" template="simpleTasks">
          <gm:handleEvent src="Projects"/>
        </gm:list>
      </td>
    </tr>
  </table>

  <gm:template id="simpleProjects">
    <div repeat="true">
      <gm:text ref="atom:title"/>
      <gm:editButtons/>
    </div>
    <gm:create label="New Project"/>
  </gm:template>

  <gm:template id="simpleTasks">
    <table width="100%">
      <tr repeat="true">
        <td><gm:text ref="atom:title"/></td>
        <td><gm:date ref="gd:when/@startTime"/></td>
        <td><gm:editButtons deleteOnly="true"/></td>
      </tr>
    </table>
    <gm:create label="new task"/>
  </gm:template>

</gm:page>

These examples should help you get started. The best way to learn Google Mashup Editor is to get in there and try out your own ideas. Good luck and have fun!