Google Wave Extension Installers

Contents

1. What Is an Extension Installer?
2. Extension Manifests
   1. Extension Hooks
   2. Extension Actions
3. Using the Extension Installer
4. Installing an Extension
5. Example
6. Deploying Your Extensions to Wave Preview

What Is an Extension Installer?

An extension installer is a package consisting of one or more of the following parts:

• An Extension Manifest, which describes the way the extension installer interfaces with the client.
• An optional gadget that is specified within the extension installer.
• An optional robot that is specified within the extension installer.

You reference an extension installer through a special XML file, called the Extension Manifest. You can add this extension manifest directly within the Wave client to an existing or new wave, where it behaves according to the extension's defined hooks and actions.

Extension Manifests

Extension manifests are XML files that define how extensions hook into the Google Wave Client and how they behave. Manifests contain two parts: hooks and actions. Hooks tell the client how and where the extension works within the client, and actions define what happens when the extension is used.

For example, a typical hook adds a button on the Wave client Toolbar:

The last icon in this toolbar is an extension described in the following manifest:

<extension 
    name="Map Gadget"
    thumbnailUrl="http://google-wave-resources.googlecode.com/svn/trunk/samples/extensions/gadgets/mappy/screenshot_mapgadget.png"
    description="Collaborate on a map of placemarks, paths, and shapes with other participants. Great for planning events and trips."> 
  <author name="Google"/> 
  <menuHook location="toolbar" text="Add Map Gadget"
      iconUrl="https://wave-api.appspot.com/public/images/insertMap.png"> 
    <insertGadget url="http://google-wave-resources.googlecode.com/svn/trunk/samples/extensions/gadgets/mappy/mappy.xml"/> 
  </menuHook> 
</extension> 

This simple manifest declares that a <menuHook> extension should be installed on the wave client's toolbar by the statement location="toolbar". (<menuHook> extensions behave as buttons when placed in the toolbar.) The manifest also includes a URL (iconUrl) for the icon to be added to the toolbar. Further, the hook specifies a child action insertGadget that will add the specified gadget to the wave upon initiation of the hook specified in the extension. You may implement multiple hooks and actions for the same extension.

Extension Hooks

An extension hook defines how the extension hooks into a Google Wave client. As such, the wave client is responsible for implementing the hook. In theory, a hook could be implemented in different ways on different implementations of Google wave clients.

Currently, only one extension hook is supported:

• menuHook indicates that the extension is a UI element within the wave client. The menuHook's location attribute indicates where within the client the extension should be installed and/or initiated. Each location has an associated scope that defines to what extent the extension affects Wave. The following locations are supported:

  • toolbar indicates that the extension should be placed within the wave client toolbar and will appear as an icon.

    

  • newwavemenu indicates that the extension should be placed within the New Wave menu (as a submenu).

Extension Actions

Each hook in turn defines one or more actions that act within a defined scope. The following actions are supported:

• addParticipants adds the specified participants (added as a set of child <participant> elements) to the wave on which this extension is attached. This action is common for adding robots to conversations.
• insertGadget places a specified gadget within a wave. An action of this type has "editor" scope.
• insertGalleryGadget brings up the gadget gallery, allowing you to select a gadget from the gallery and insert it at the current cursor location. An action of this type has "editor" scope.
• createNewWave creates a new wave within the "global" scope.
• annotateSelection tags the current selection with an annotation.

The gadget example above used "editor" scope. The example below uses "global" scope:

<extension
    name="Tweety"
    description="Creates a new Twitter wave.">
  <menuHook location="newwavemenu" text="Creates a new Twitter wave." 
      iconUrl="http://wave-skynet.appspot.com/public/extensions/tweety/icon.png">
      <createNewWave>
        <participant id="tricky-bot@appspot.com" />
      </createNewWave>
  </menuHook>
</extension>

This extension will be added to the New Wave menu as a custom option when installed. Clicking it creates a new wave and adds the participant tweety-wave@appspot.com.

Using the Extension Installer

To add an extension to wave, and to share it with others, you must first install the Extension Installer, which is a special "meta" extension installer that allows you to specify and install other extensions. This installer is available within the Google Wave Sandbox instance. (User wishing to install extensions on the public Google Wave Preview should see Deploying Extensions to Production below.)

To install the Extension Installer on Sandbox:

1. Visit the Sandbox Extension Installation Wave and scroll to the bottom where you will see the Extension Installer widget.

   

2. Click Install. An Extension Permissions dialog box appears.

   

3. Click Confirm. The Extension Installer will be added to your wave instance as an available extension.

4. Navigate to your Settings panel within Wave and click on the Extension Gallery wave. You should see that the proper extension has been added to your wave instance. Note that you can remove or uninstall the extension from this settings wave.

   

Once operational, the Extension Installer adds a submenu to Wave's New Wave menu and a tool to an individual wave's toolbar, allowing you to specify additional extensions to add to wave. In the following section, we'll describe how you use this functionality to add an extension and share it with others.

Installing Extensions

You may add new extensions either via the Extensions Gallery wave or by specifying them yourself using the Extension Installer. You reference extensions using their extension manifests, which must be publicly hosted for the Wave client to use them.

To install extensions using the Extension Installer:

1. From Wave's New Wave menu, select its submenu and select the New Extension Installer selection. (You may also click the toolbox icon within an individual wave's toolbar.)

   

   The Insert Extension Installer dialog box appears.

2. Within the text field, enter an extension manifest URL and click Insert. Provided that the extension is defined correctly and supported within your client, an extension installer will be added in the appropriate location.

   

3. If the extension is then added to an existing wave, the wave will display an embedded widget showing extension information and an Install button. Click Install to install the extension on that wave. All other participants on that wave will then be presented with the widget to install the extension as well.

   

4. Click Done to complete installation.

   

To share an extension with "editor" scope with someone else, simply add the person to the wave as a participant. Then that person can also install the extension. Extensions with "global" scope cannot be shared as they hook directly into the client UI, not on a specific wave.

Example

Here is an extension you can install and try:

• Extension manifest URL: http://wave-skynet.appspot.com/public/extensions/areyouin/manifest.xml

This extension adds a button to the Toolbar that lets you add the "Where Are You?" gadget to any wave. The "Where Are You?" gadget lets wave participants place their location on a map.

To install this extension, follow the directions in Installing an Extension. Once you install it, you can create a new wave and you will see the "Where Are You?" gadget icon on the Toolbar when you create a new wave.

Deploying Your Extensions to Wave Preview

To add an extension to the Google Wave Preview instance, you must first install the Extension Installer, which is a special "meta" extension installer that allows you to specify and install other extensions. This Extension Installer is available within the Extensions Gallery wave which is linked from within the Welcome Wave.

To install the Google Preview Extension Installer:

1. Select the Welcome Wave (search for Welcome to Google \/\/ave) and within that wave, find the link to the Google Wave extensions and click on it.

2. Select the Extensions Gallery wave and scroll to the bottom where you will see the Extension Installer widget.

   

3. Click Install. An Extension Permissions dialog box appears.

   

4. Click Confirm. The Extension Installer will be added to your wave instance as an available extension.

5. Navigate to your Settings panel within Wave and click on the Extension Gallery wave. You should see that the proper extension has been added to your wave instance. Note that you can remove or uninstall the extension from this settings wave.

   

Once operational, the Extension Installer adds a submenu to Wave's New Wave menu and a tool to an individual wave's toolbar, allowing you to specify additional extensions to add to wave. You can then install your extensions as indicated in the Installing Extensions section.