API Docs

The AWW plugin can be embedded into your application and provide an interactive whiteboard for your visitors.

There are two ways to embed AWW:

basic – provide just a canvas area, with no whiteboard sharing; visitors posting or saving the image will be redirected to awwapp.com
premium – provide a canvas area, with whiteboard sharing, no aww branding, API for tweaking the way AwwApp behaves

Components

AwwApp consists of three components:

the canvas, client side UI, implemented as a jQuery plugin
the realtime sharing service, implemented as a Node.js server, hosted
the image post / save service, implemented as a Python server, hosted

The UI and the sharing service communicate using Nowjs. AwwApp has a concept of shared boards, where each board is separate. Boards are identified by an opaque string ID.

AwwApp uses url fragments to identify board IDs. For example, board ‘dc63a’ would have the url: http://example.com/yourpage#dc63a

If the current URL of the page has the url fragment and autoJoin is enabled (default), awwApp will automatically try to join the board identified by the fragment.

Embedding

The HTML boilerplate required is the same for all versions.

Page head

HTML canvas support is required. As IE doesn’t provide it natively, the open source excanvas plugin is used for emulation:

<!--[if IE]> <script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script>
   <script src="http://static.awwapp.com/plugin/1.0/excanvas.min.js"></script>
<![endif]-->

Also, you’ll need jQuery:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>

AwwApp UI is one JavaScript file one CSS file, and a couple of images linked to from the CSS rules:

<link rel="stylesheet" type="text/css" href="http://static.awwapp.com/plugin/1.0/aww.css"/>
 <script type="text/javascript" src="http://static.awwapp.com/plugin/1.0/aww.min.js"></script>

That’s all that’s required for basic embed. For realtime collabration, you need to link to the nowjs endpoint as well:

<script type="text/javascript" src="http://awwapp.com:7000/nowjs/now.js"></script>

Body

Provide a block HTML element occupying the space you want the whiteboard to fill. Then, initialise the awwCanvas plugin on it:

<div id="wrapper"></div> <script type="text/javascript">
  $(function() {
    var aww = $('#wrapper').awwCanvas({ apiKey: 'YOUR-API-KEY' });
    /* if the canvas can be resized */
    $(window).resize(function() {
        $('#wrapper').awwCanvas().resize();
    });
  });
</script>

The awwCanvas plugin has several options, described later in detail. A required option if you want to enable realtime collaboration is apiKey. If you don’t supply it, the whiteboard sharing option won’t be enabled.

Embed options

When initialising the awwCanvas plugin, you can set various options which modify the behaviour of the plugin. Here’s a full list:

apiKey: ‘YOUR-API-KEY’ (default: undefined) – your API key which enables full use of the AwwApp service
autoJoin: true/false (default: true) – whether to automatically join a shared whiteboard when initialising the plugin if a hash fragment is present
toolbar: true/false (default: true) – whether the toolbar should be shown
smallIcons: true/false (default: false) – whether to force use only small icons; by default, icons are shown big if the board is big
orientation: ‘portrait/landscape/auto’ (default: auto) – toolbar orientation; in portrait mode, toolbar is on the top; in landscape, it’s on the left; in auto, the mode is determined by the canvas aspect ratio
msgbox_handler - by default, AwwApp uses standard JavaScript alert box for info/error messages; if you want to present a custom message box, set this handler; the example handler that’s equivalent to the default functionality:
```
msgbox_handler: function(msg) { alert(msg); } 
```
invite_handler - called when the visitor wishes to share the whiteboard; the default action is to create a new shared board and display the message to the user; if user was already on a shared board, they disconnect; you can completely change this action by seting a custom invite_handler; an example:
```
invite_handler: function() { if (this.isShared()) { alert('Already sharing board ' + this.getBoardId()); } else { alert('Preparing to create shared board'); ... } } 
```
post_handler - called when the visitor wishes to post the image online; the default action is to make a POST request in a new window/tab, which will show the posted image to the visitor; you can set a custom handler to eg. use ajax post instead:
```
post_handler: function() { this.doAjaxPostImage(function(data) { alert('Direct image URL: ' + data.image + '\nPosted page URL: ' + data.link); }); } 
```

awwCanvas methods

Once initialized, awwCanvas has several methods you can use.

Canvas methods

$(wrapperelement).awwCanvas() – calling it again will return the awwCanvas object that was attached to the wrapper element
resize() – resize the canvas to match the (new) dimensions of the wrapper element
saveImage() – make a POST request to save the image (visitor will download it as a PNG image)
postImage() – make a POST request to post the image (visitor will be redirected to the image page on awwapp.com)
doAjaxPostImage(cb) – make an ajax POST request to post the image; the callback will be called with an object containing ‘image’ (URL to the image file) and ‘link’ (URL to the page on awwapp.com hosting the image) properties

Image methods

doDrawLine(color, width, x1, y1, x0, y0) – draw a line with a specified color (‘#rrggbb’ format), width (in pixels)
doErase(x, y) – erase a circle of radius 20px centered at (x,y)
doClear() – clear entire drawing

Share methods

isShared() – returns true if the whiteboard is shared, false otherwise
getBoardId() – returns board ID if the whiteboard is shared, otherwise null
joinBoard(board_id, cb) – join a shared board; if there’s something drawn on the canvas before joining, it will be merged with the whiteboard content; to remove local data, call doClear() beforehand; upon joining the board, the callback is called with the board ID as the only parameter; if an error occurrs, the callback is called with null instead
createBoard(cb) – create a new shared board and join it; the callback will be called with the board ID or null in case of failure
createNamedBoard(board_id, cb) – create a shared board with the specified board_id and join it; if the board already exists, this will join an existing board; the callback will be called with the board ID or null in case of failure
leaveBoard() – leave current shared board