Learn about the Google Wave Federation Protocol and get involved
The fundamental element in any Google Wave API application is the "wave" itself,
which is held within a WavePanel object. This
tutorial discusses how to set up and populate a WavePanel object to hold a
wave.
The easiest way to understand the Google Wave API is to see a simple example. The following web page displays the "Welcome" wave on the Wave API home page:
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Wave Embed API Example: Simple Wave</title>
<script src="http://wave-api.appspot.com/public/embed.js" type="text/javascript"></script>
<script type="text/javascript">
function initialize() {
var wavePanel = new WavePanel('http://wave.google.com/a/wavesandbox.com/');
wavePanel.loadWave('wavesandbox.com!w+waveID');
wavePanel.init(document.getElementById('waveframe'));
}
</script>
</head>
<body onload="initialize()">
<div id="waveframe" style="width: 500px; height: 100%"></div>
</body>
</html>
You can download this sample to edit and play around with it, but to interact with the wave, you'll need to request Sandbox access and provide your own Wave ID for the wave you wish to embed.
Even in this simple example, there are a few things to note:
script tag.<div> element named "waveframe" to hold the wave. The wave
will actually exist as an <iframe> within that element.WavePanel object.init() the WavePanel and attach it to the <div> element.
<body> tag's onload event.These steps are explained below.
<script src="http://wave-api.appspot.com/public/embed.js" type="text/javascript"></script>
The http://wave-api.appspot.com/public/embed.js URL points to
the location of the JavaScript file that includes all of the symbols and definitions you need
for using the Google Wave API. Your page must contain a <script> tag pointing to this URL, and
this <script> tag should be placed before any JavaScript you write using those symbols.
<div id="waveframe" style="width: 500px; height: 100%"></div>
For the wave to display on a web page, we must reserve a spot for it. Commonly, we
do this by creating a named div element and obtaining a reference to
this element in the browser's document object model (DOM). In the example above, we
define a <div> named "waveframe" and set its size
using style attributes. Generally, you should allow enough horizontal space
for proper use of the wave by wave participants.
WavePanel Object
var wavePanel = new WavePanel("http://wave.google.com/a/wavesandbox.com/");
The JavaScript class that holds a wave is the WavePanel class. Objects
of this class may hold a single wave on a page. (You may create more than one instance
of this class - each object will define a separate wave on the page.) We create a new
instance of this class using the JavaScript new operator.
When you create a new wave instance, you specify a DOM node in the
page (usually a div element) as a container for the wave. HTML nodes
are children of the JavaScript document object, and
we obtain a reference to this element via the document.getElementById() method.
The function WavePanel() is known as a constructor and
its definition (condensed for clarity from the
Google Wave Embed API Reference) is shown below:
| Constructor | Description |
|---|---|
| WavePanel(Wave server instance) | Creates a new Wave panel using the indicated Wave server instance. For
development purposes, this instance will be http://wave.google.com/a/wavesandbox.com/.
(Note the trailing slash in the URL; this is required.)
|
wavePanel.loadWave("wavesandbox.com!w+waveID");
Once we've created a wave via the WavePanel() constructor, we need to
load it with an initial wave. (Currently, we do not allow you to create a new wave
from scratch in this environment.) This loading is accomplished via the
loadWave() method, which accepts the unique wave ID of the desired
wave.
Currently, you can obtain the wave ID within Wave by selecting a wave and then selecting
Debug->Get Current Wave ID. Note that people accessing this wave must be "participants"
of the wave, which is not feasible for a public website. To account for this case, there is a special
reserved participant address which you can add to a wave (public@a.gwave.com)
to provide public access to any wave. For now, "public access" is restricted to users with
Wave sandbox access.
Note: we are planning to release read-only access to wave in the future. For the time being, all participants to waves are active (read/write) participants, and must have wave accounts on Sandbox.
wavePanel.init(document.getElementById('waveframe'));
While an HTML page renders, the document object model (DOM) is built out, and any external
images and scripts are received and incorporated into the document object. To ensure
that our wave is only placed on the page after the page has fully loaded, we only execute the function
which constructs the WavePanel object once the <body> element
of the HTML page receives an onload event. Doing so avoids unpredictable behavior and gives us more
control on how and when the wave draws.
A wave is an interactive entity. People, groups, and robots can interact with the wave
provided that they have been invited or have otherwise been authorized to contribute. We
anticipate adding this functionality directly to the Wave Embed API in the near future;
however, currently you must set up this access control within the wave beforehand. To
allow all users access to your wave, add the special address public@a.gwave.com
as a participant of the wave.
You can alter the look and feel of an embedded wave by using the
setUIConfig() method. This method takes a set of strings
which are used to configure the background color and font characteristics
of the wave upon initialization. Note that calling this method after you've
called the init() method will have no effect.
The following code alters the wave to provide a green background with white Arial text:
setUIConfig('green', 'white', 'Arial', '12pt');
For more detailed information about the Embed API, consult the Embed API Reference.