Tutorial

Overview

This document is intended for webmasters who want to include WaveThis within a webpage. It provides an introduction to using the API and reference material on the available parameters.

Using WaveThis is simple. Just provide a linked URL of the following form on your website:

 
https://wave.google.com/wave/wavethis?parameters 

Users clicking on a WaveThis link will be redirected to an intermediate webpage asking the user for permission. Once authenticated, a new wave is created with the specified content and the gadget, if specified. The user can then edit the contents, add other people and start a discussion etc.

All parameters are optional, though absent parameters imply usage of certain defaults noted below. As is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

URL Parameters

A WaveThis URL may contain any or all of the following parameters, which provide information to populate the initial wave. Note that all parameters must also be URL-encoded. This is especially important for parameters which, in turn, contain URL special characters.

    Content Parameters:

    All parameters are optional and can be specified either as a single letter or as a more descriptive word based on the http://www.oexchange.org/spec/ standard.

  • t (or title) specifies the title of the new wave. If no parameter is passed, the specified url will be used as the title.
  • u (or url) specifies the URL to show within the new wave. If no parameter is passed, wave will use the contents of the HTTP request's Referer field. Note that the passed URL must be URL-encoded.
  • c (or message) specifies the "snippet" of content to show within the new wave. If no content is specified, Wave will use the URL provided in the u parameter.
  • g specifies the URL of the gadget to insert into the wave. This gadget can be used to show a dynamic aspect of the source page. The wavethis_referer key will be automatically set in the gadget state and can be used to determine what to show.

Examples

Using the above parameters, you can see that WaveThis can be used for the following use cases:

Waving a blog post entry, populating the wave with an intitial title, url and content:

 
https://wave.google.com/wave/wavethis?u=http://myblog.com/post4&t=New+Post&c=I+was+thinking...

Waving a YouTube video, specifying the gadget to render the initial content within the wave:

 
https://wave.google.com/wave/wavethis?u=http://www.youtube.com/watch%3Fv%3D3ichQOqbewA%26feature%3Dfvst&g=http://wave-this.appspot.com/public/youtube.xml&c=%0A%09%09YouTube%0A%09%09%09%09-%20Teletubbies%0A%09

Using POST

A WaveThis operation can also be initiated within the body of an HTTP POST, which you may want to use if you are sending a long content string and want to avoid surpassing the URL length limits in the browser.

To put a button on your site that uses WaveThis via POST, you can pass the URL parameters from a form, like so:

 
  <form name="wavethis" method="post" action="https://wave.google.com/wave/wavethis" target="_blank">
      <input type="text" name="t" value="Testing WaveThis!"/>
      <input type="text" name="c" value="Just seeing if this works."/>
  </form>
 
  <a href="javascript:document.wavethis.submit()"><img src="http://wave.google.com/wavethis/button32.png" alt="WaveThis"></a> 

The live form would look like this (try it out!):

If you don't want users to modify or see the title and description, just set the input type to "hidden" instead of "text".

WaveThis Icons

Use the following icons/buttons to store your WaveThis hyperlinks:

Height (pixels)IconsButtons
16
24
32

You should link to these icons/buttons directly at http://wave.google.com/wavethis/. A typical WaveThis hotlink using one of the above images will look like the following:

 
<a name="wavethis_link" href="https://wave.google.com/wave/wavethis?u=http://myblog.com/post4&t=New+Post&c=I+was+thinking..."
target="_blank"><img src="http://wave.google.com/wavethis/icon16.png" /></a>

WaveThis Wizard

If you want an easy way to experiment with the WaveThis parameters and see the resulting HTML and URL, try out the WaveThis Wizard.



Comments