The Google Wave document model supports tagging sections of text within a wavelet's Document elements via annotations. The Google Wave client uses some reserved annotations itself to denote textual styling issues, hyperlinks, and some metadata. You can also use your own annotations to tag certain strings of text for your own purposes. Many robots use annotations to perform operations on strings of text.
Note that these annotations, by themselves, are simply ways to mark selections of text. They may, or may not, have visible effects. How you use or process annotations is up to you. An annotation may simply contain meta-information about a text selection, or it may require additional processing by your robot to have some effect. (For an example of annotation processing, see Custom Annotations below.)
The Google Wave client uses annotations to style runs of text strings, defining each annotation with a start and end point (known as a range). For example, the following text string (as displayed to the user in the client) and its annotations are shown below:
The quick brown fox jumped over the lazy dog.
(4,19) : style/fontStyle=italic (10,15) : style/color=rgb(150,75,0) (36,40) : style/fontWeight=bold
The following table lists these reserved annotations:
You can view a Blip's annotations within Wave Sandbox by selecting Editor Debug from the right hand menu on a blip and then clicking on annotations in the Editor Debug dialog box.
You can also create your own annotations. Robots often use annotations to mark text and repurpose it for some other use. For example, a shopping robot might allow users to select items within a wavelet for a shopping list, extract those annotated items, and add them to a gadget.
Annotations should be tagged using unique identifiers. It's
good practice to preface your annotations using a namespace, so
that they don't collide with other annotations (or system
annotations). Using the robot's
Annotations may additionally take on a value. In many cases, a value is not necessary; the annotation and its underlying text contains all information that is needed for designating the range of text. In other cases, an annotation requires a value. The system styling annotations take on values, for example, to denote font sizes, colors, families, and weights, for example.
Using annotations effectively within a robot generally requires one (or both) the following patterns (one active and one passive):
Note that the first pattern is more computationally expensive.
If you wish to have a robot respond to new annotations, the following pattern is recommended:
The following extension installer annotates a selection
as a "band name" using
<extension name="Band Name Tagger" description="Tags selected text as a band name and adds it to a blip" thumbnailUrl="http://band-name.appspot.com/preview.png"> <author name="Tom Manshreck"/> <menuHook location="TOOLBAR" text="Tag Bandname" iconUrl="http://band-name.appspot.com/toolbaricon.png"> <annotateSelection key="band-name.appspot.com/name" /> <addParticipants> <participant id="firstname.lastname@example.org"/> </addParticipants> </menuHook> </extension>
The following code will then monitor
def onAnnotationChanged(event, wavelet): # Get the text of the blip blip = event.blip text = blip.text # Set up our array to hold the retrieved annotations bandnames =  # Get the annotation start and end points and add # them to the array for ann in blip.annotations: if ann.name == 'band-name.appspot.com/name': bandnames.append((ann.range.start, ann.range.end)) # For each bandname, call addBandName to do any post processing # Also make sure to delete the existing annotation for start, end in bandnames: bandname = text[start:end] blip.range(start, end).clear_annotation('band-name.appspot.com/name') addBandName(bandname)
For more details on annotations and events see the article Responding to User Selection, which covers annotations in Extension Installers and robots.
The following examples demonstrate using annotations: