Google Mashup Editor - JavaScript API

JavaScript API Overview
Application Object
Module Object
Data Source Object

JavaScript API Overview

Google Mashup Editor (GME) includes a JavaScript API that gives you direct access to the document object model (DOM) via JavaScript. This API lets you use JavaScript to perform operations that duplicate and go beyond the features available in the GME tags. The API is useful when you want to access an object in the application from a JavaScript expression. You can also use the API to perform CRUD operations (create, read, update, delete) on entries in a data feed.

Application Object

The JavaScript API provides access to the application object, which you access via the google.mashups namespace. The methods provided by the application object allow you to get any object in the application and get the entry associated with a specified DOM element.

Method	Return Type	Description
`getObjectById('module_ID')`	module object	Given a GME module ID, returns the module object. This is similar to `getElementById()` in standard JavaScript.
`getEntryForElement(DOM Element)`	entry object	Given a DOM element, returns the entry associated with that element. Use this when you have added a non-GME element (such as an HTML button) to a template, and you want to get the entry associated with the element's row.

You can get access to any module in the application by passing its ID to getObjectById(). You can use getObjectById() to get a list, map, or other module, as in the following example:

<gm:page title="app">

  <gm:list id="myList" data="${test}/>

  <script>
    var list = google.mashups.getObjectById('myList');
  </script>

</gm:page>

The JavaScript API defines one static method:

Method	Return Type	Description
`cloneEntry(entry)`	entry object	Given an entry, returns a copy of the entry object that you can add to another feed. Note that because this is a static method, you call it without a namespace, like this: `cloneEntry(entry)`.

Module Object

The JavaScript API includes methods that operate on modules within your application. You can use these methods to work with the module's data source, change its template, and perform other functions.

General Module Interface

The module interface includes the following methods:

Method	Return Type	Description
`refresh()`	none	Tells the module to redraw itself.
`getData()`	data source object	Gets this module's data source object, which you can use to manipulate the elements of the module's data feed.
`setData(data)`	none	Sets the data source object to be used by the module.
`setVisible(bool)`	none	Sets the visibility of the module.
`setFilterParam(filterName,filterValue)`	none	Sets the module's filter to the given name and value. If `filterValue` contains a comma, a range filter is created, with the range limits specified by the comma-separated string. Otherwise, a value filter is created.

The following simple example shows how you can use the JavaScript API to get access to a list's data source and then change that data source:

<gm:page title="My App">
  <!-- Click on the "Switch data" button to switch the feed -->
  <gm:list id="feedItems" data="http://www.digg.com/rss/index.xml" template="default"/>
  <input type="button" value="Switch Data" onClick="switchData();"/>
  <script>
    function switchData(){
      var listModule = google.mashups.getObjectById('feedItems');
      listModule.setData('http://code.google.com/feeds/updates.xml');
    }
  </script>
</gm:page>

List Module Interface

In addition to the general module interface, GME provides a specific interface for lists that includes the following methods:

Method	Return Type	Description
`setFilter(param)`	none	Filters the list according to the given string. To specify a range, use one of the formats "min,max" ,",max", or "min,".
`setTemplate(id)`	none	Sets the template of the list module to the given object.
`isEditing()`	boolean	Returns true if this module is currently editing an item.
`selectEntry(entry)`	none	Selects the specified data element.
`getSelectedEntry()`	entry object	Returns the currently selected element.

Item Module Interface

There is a JavaScript GME interface for item modules that provides the following methods:

Method	Return Type	Description
`getEntry()`	entry object	Returns the entry associated with the item module.
`setEntry(entry)`	none	Sets the entry associated with the item module to the given object.
`setTemplate(id)`	none	Sets the template of the item module to the given object.

Map Module Interface

The GME JavaScript interface for map modules includes the following methods:

Method	Return Type	Description
`selectEntry(entry)`	none	Selects the specified data element.
`getSelectedEntry()`	entry object	Returns the currently selected element.
`getCenter()`	GLatLng object	Returns the latitude and longitude of the current map center.
`getBounds()`	GLatLngBounds object	Returns the bounds of the map. Equivalent to `GMap2.getBounds()` in the Google Maps API.
`getMap()`	GMap2 object	Returns the native GMap2 map object. You should not modify this object.
`createItem(latlng)`	none	Creates a new item at the given location, specified as a GLatLng object. If the map has an infotemplate, this method opens an edit form at that location; otherwise, a map pin is created.
`showAllMarkers()`	none	Centers and zooms the map to fit all the current markers at the most appropriate zoom level.

Data Source Object

This section describes how you can use the JavaScript API to access data feeds and perform the CRUD operations: create, read, update, and delete.

Data Source Object Interface

The data source object interface gives you access to data feeds and exposes the following methods:

Method	Return Type	Description
`size()`	int	Returns the number of entries in the feed.
`entryAt(index)`	entry object	Returns the specific entry in the feed. The index of the first entry is zero; the last entry is `size()` - 1.
`canCreate()`	boolean	Returns true if the feed is writable, or false otherwise.
`createEntry()`	entry object	Creates and returns a new entry for the feed. The entry is not inserted into the feed until you call `addEntry()`.
`addEntry(entry)`	none	Adds the given element to the feed.
`updateEntry(entry)`	none	Saves an updated version of the given element to the feed.
`removeEntry(entry)`	none	Removes the given element from the feed.

Data Source Element Interface (GPath)

The data source element interface provides access to methods that set and get the value of elements in a feed. To get or set a particular element, you declare a GPath object, then create an XPath query to the entry you want to operate on.

This interface defines the following methods you can use:

Method	Return Type	Description
`setValue(element,value)`	none	Sets the value of the given element to the specified value. The value must be a string.
`getValue(element)`	String	Returns the string representation of the value for the given element.

The following example shows how to set a feed element from another value:

//Declare a new GPath
var titleGPath = new GPath("atom:title");

//Get an element from a feed
var myData = google.mashups.getObjectById('myData');
feed = myData.getData();
entry = feed.getSelected();

//set the value of an element in that entry
titleGPath.setValue(entry,"This is a title");

Running a Script at Load Time

If you have JavaScript calls that you want to execute when the application loads, you must ensure that the GME JavaScript library is loaded before your JavaScript runs. An easy way to do this is to place your JavaScript inside a function, then call the function from an onload handler in the gm:page tag.

Performing the Basic CRUD Operations

The example in this section shows how you can create, read, update, and delete entries from a data feed, using the JavaScript API. These are the steps:

Create a new Gpath object to specify the location in the feed where data will be read from and saved to.
Get the feed object.
Create a new entry.
Set the values in the entry whose locations in the feed correspond to the XPath expression we created with the GPath object.
Add the newly created entry to the feed.

Here's the sample code:

<script>

  //Create the new GPath object and set the path of the location where you will store or read data
  var titleGPath = new GPath("atom:title");
  var contentGPath = new GPath("atom:content");

  //Get the Feed
  var feed = google.mashups.getObjectById('myList').getData();

  if(feed.canCreate()){

    //Create a new entry
    var entry = feed.createEntry();


    //Set the values
    titleGPath.setValue(entry,'New Title');

    contentGPath.setValue(entry,"This is where you put the content');


    //Add the entry to the feed
    feed.addEntry(entry);
  }

</script>

If we simply want to read an element, we get the selected entry and read its value:

<script>

  var titleGPath = new GPath("atom:title");
  var contentGPath = new GPath("atom:content");

  var feed = google.mashups.getObjectById('myList').getData();
  var listEntry = google.mashups.getObjectById('myList').getSelected();
  
  var title = titleGPath.getValue(listEntry);

  alert(title);

  }

</script>

We can delete an element from the feed by getting the selected entry and removing it:

<script>

  var feed = google.mashups.getObjectById('myList').getData();
  var listEntry = google.mashups.getObjectById('myList').getSelected();
  
  if(feed.canCreate()){

    feed.removeEntry(listEntry);
  }

</script>

Google混搭编辑器(Google Mashup Editor)