An extension installer is a package consisting of one or more of the following parts:
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 are XML files that define how extensions hook into the Google Wave Client and how they behave. Manifests contain three parts: metadata, hooks, and actions. The metadata tells Google Wave how to render the installer, 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, the following extension installer will add a toolbar icon to the toolbar, and when that is clicked (the hook), it will insert a map gadget (the action):
<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
Before specifying hooks and actions, an extension installer first describes various pieces of metadata. This information is primarily used for presenting the extension to users, such as rendering the installer as an installable puzzle piece in a wave.
The following attributes should be specified on the root
The author should be specified using
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.
For example, this menuHook adds a suboption to the "New Wave" menu, and when the user installs and clicks the option, the client will create a new wave with the two participants on it.
<menuHook location="NewWaveMenu" text="New Friends Wave"> <addParticipants> <participant id="firstname.lastname@example.org"/> <participant id="email@example.com"/> </addParticipants> </menuHook>
For example, this regexHook searches for smiley faces, and when it finds one, it prompts the user to add an emoticon robot:
<regexHook pattern="\:\)"> <addParticipants> <participant id="firstname.lastname@example.org"/> </addParticipants> </regexHook>
Note: This hook is in preview mode and currently only enabled on WaveSandbox.com. We look forward to hearing your feedback on this hook in the forum.
For example, this extension installs a saved search for unread waves:
<extension name="Unread Wave Search" description="Installs a saved search that shows all unread waves."> <savedSearchHook name="Show unread" query="is:unread" color="#00FF00"/> </extension>
Each hook in turn defines one or more actions that act within a defined scope. The following actions are supported:
Adds participants to the current wave. Participants are specified via
For example, this extension creates a new wave with a chess playing robot.
<menuHook location="NewWaveMenu" text="New Chess Match"> <addParticipants> <participant id="email@example.com"/> </addParticipants> </menuHook>
Similar to SavedSearchHook, adds a new saved search to the search menu. Note that adding saved searches in this way will not automatically remove them when the extension is uninstalled. See Saved Search Hook for a list of acceptable attributes.
For example, this extension adds a saves search for chess games after the user first uses the gadget.
<menuHook location="toolbar" text="Add Chess Gadget" iconUrl="http://wave-chess.appspot.com/WaveChess.png"> <insertGadget url="http://wave-chess.appspot.com/wavechess/com.google.wave.chess.client.ChessGadget.gadget.xml"/> <addSavedSearch title="Chess Game" query="has:gadget ChessGame" color="green"/> </menuHook>
Applies an annotation to the current selection while in edit mode. The annotation key and value is specified with key and value attributes, respectively.
For example, this extension applies bold and strike-out styles to the selected text:
<menuHook location="toolbar" text="Boldicize"> <annotateSelection key="style/fontWeight" value="bold"/> <annotateSelection key="style/fontStyle" value="italic"/> </menuHook>
Inserts a gadget at the current cursor location. The gadget url is
specified via a
For example, this extension inserts a chess gadget:
<menuHook location="toolbar" text="Add Chess Gadget" iconUrl="http://wave-chess.appspot.com/WaveChess.png"> <insertGadget url="http://wave-chess.appspot.com/wavechess/com.google.wave.chess.client.ChessGadget.gadget.xml"/> </menuHook>
Once you've created the installer XML, you will want to actually test it out and see how it works. To do that, you need to insert an installer element in the wave, and before you can do that, you must install a special extension, "Extension Installer Creator", that makes it easy to insert installer elements.
1. Install "Extension Installer Creator":
Once you're viewing the wave, just click "Install" on the installer.
2. Once you install the extension, you will see a toolbox on your editing toolbar while editing a blip. To insert an installer, click that toolbar icon, and paste the URL of your XML in the text box.
3. After clicking "OK", you will see an installer element in the wave, showing the information from your XML. If the installer does not load correctly, then check the XML and make sure that it is valid.
4. If you make changes to your installer XML and want to test the new XML, you will need to re-insert the installer with a random query parameter appended to the end of the URL, to avoid the wave using a cached copy of the XML. For more information on caching of installers, see this FAQ.
5. Once you're happy with the installer you can share it with your
friends by adding them to the wave, or share it with the world by adding
The following are actual example installer XMLs that can show you how to use the actions and hooks described above.