ZURB JavaScript Annotation Plugin

Annotate Nutmeg (click the dog)

OK, this is just silly, but what's really silly is how simple this was to implement with our annotation plugin. Just link up jQuery (1.2.3 or higher) and our plugin.

Our latest application Verify allows you to collect user feedback through interactive tools. A lot of these tools require the user to annotate an image so we came up with a single plugin we could use for the entire app. Heck, we figured some other people might want to use it too.

Here's how it works: The first parameter to annotatableImage is a function implemented by you and defines the element that will be added when you click. In the example above that function is called blackNote. Simple right?

So how do I save these annotations?

Glad you asked. Use the jQuery selector to grab all the elements you want to serialize and call the seralizeAnnotations function. Give it a try below.

Serialize! Make sure you have some annotations on Nutmeg the dog.

These values are returned in an array of objects so you can easily save them with an AJAX call. response_time is the time in mili seconds it took the user to add the annotation after you made the call to annotatableImage. The x and y values may look a little strange so let me explain...

Let's get relative

In Notable as well as Verify we need to show our annotations on different sized versions of our original image. The full size is just not always going to cut it in the world of good design. To make this easier we store the x and y positions of our annotations relative to the width and height of the image.

If you didn't pass 5th grade math don't worry, our plugin does all the basic arithmetic for you. Don't believe me? Press the button and be amazed.

Warning: If you change the aspect ratio or crop the image this will not work properly. Also be sure to always store x and y as floating point data types.

The annotations variable is an array of objects with x and y attributes. It looks exactly like the array returned by the seralizeAnnotations function without the response_time attribute. What other attributes might you put in the annotation object? Read on...

Passing attributes

We might want to pass some data to each of our annotations when adding existing annotations. Maybe we have numbered our annotations, added special classes or behaviors, whatever.

The function we pass to annotatableImage accepts a single parameter which is the annotation object from the array you passed to addAnnotations. In this example we added a position attribute which we are going to display.

Hitting all the positions

Back when we were annotating Nutmeg you may have noticed that the annotation was centered at your click position. This may be great for circles and sparkly unicorns but sometimes we may want to position our annotations differently.

The xPosition and yPosition options allow you to indicate where the annotation is positioned relative to the click. Options are middle (default), left, right and middle (default), top, bottom respectively.

Give Nutmeg some clicks to see what I'm talking about. In this example we are positioning the click on the left side of the annotation.

Warning: Make sure you pass the xPosition and yPosition to the serializeAnnotations function if you set these options in annotatableImage. The default behavior is to calculate the x and y values from the middle of annotation.

Wanting more?

Take a peek at the plugin source to see how this works at a lower level. There are some lower level methods in there that could be called directly to get more advanced behavior. Make sure you direct any questions, comments or concerns to the blog post.

Copyright ZURB, freely available for distribution under the MIT license.