API docs

When setting your whiteboard widget in code, you have several options at your disposal all of which are described in detail below.

AWW consists of three components:

  • whiteboard widget that runs inside the page
  • realtime sharing service that provides the whiteboard sharing functionality, hosted on AWW servers
  • image post and download service hosted on AWW servers

AwwApp has a concept of shared boards, where each board is separate, and identified by an unique string ID. By default, URL query strings are used to identify board IDs. For example, board TEST-BOARD would have URL: http://example.com/yourpage?awwBoard=TEST-BOARD

IMPORTANT: Do not download AWW scripts to your site and host them yourself, as this will break the sharing functionality. Use the files directly from AWW servers, as is shown in the examples here.

To create a whiteboard, invoke a AwwBoard() method in which you write the selected element in which you want to add the whiteboard and preferred options.

new AwwBoard(element, {options})

  • element [string | object] – contains a reference to the element in which whiteboard is
  • {options} [object] – options object
<div id="aww-wrapper"></div>
<script src="https://awwapp.com/static/widget/js/aww.min.js">
</script>
<script type="text/javascript">
      var aww = new AwwBoard('#aww-wrapper', {
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba',
            autoJoin: true,
            boardLink: '5aj5342-56tz-uhjk-9874',
            sizes: [3, 5, 8, 13, 20],
            fontSizes: [10, 12, 16, 22, 30],
            menuOrder: ['colors', 'sizes', 'tools', 'admin',
              'utils'],
            tools: ['pencil', 'eraser', 'text', 'image'],
            colors: [ "#000000", "#f44336", "#4caf50", "#2196f3",
              "#ffc107", "#9c27b0",     "#e91e63", "#795548"],
            defaultColor: "#000000",
            defaultSize: 8,
            defaultTool: 'pencil',
     });
</script>

AwwBoard options

apiKey [string]

The purpose of apiKey is to enable your premium plan features like voice chat and whiteboard sharing. You can find your apiKey in account information. Here's an example:

apiKey: '391e33ce-16fb-41e9-aced-ad424988deba'

autoJoin [boolean]

With the default value as true, whiteboard widget will automatically connect to the shared board if its ID is set in the URL as a query string or if you set your own boardLink in the options. If autoJoin is set to false, the whiteboard widget will not connect to the shared board even if an ID is present in the URL or you set a boardLink.

autoJoin: false

boardLink [string]

When set, the whiteboard widget will use its value as the board link ID to connect to instead of the URL query string. If autoJoin is set to true, then it will automatically create or join the specified board. By default this option is not set and if you are setting it, it should be a unique, unguessable string of text.

boardLink: '5aj5342-56tz-uhjk-9874'

sizes [array.number]

This option refers to and modifies the selectable list of sizes in the main whiteboard menu, specifically size of pencil and eraser; for text sizes see below under fontSizes. You can choose any number as an array item and any array size, just be mindful of the whiteboard screen size and if every size number you selected fits. If you choose a different array size, you should also modify fontSizes to match the arraySize. The defaults are:

sizes: [3, 5, 8, 13, 20]

fontSizes [array.number]

This option allows you to modify list of text sizes. If you are not changing the array size, then you don't have to modify the previously mentioned sizes. You can choose any text size you want, as long as it fits on whiteboard screen. The defaults are:

fontSizes: [10, 12, 16, 22, 30]

menuOrder [array.string]

This option allows you to change the main whiteboard menu order and with it to add or remove items. Available array items are 'colors' which shows all the default colors, 'sizes' which show all the default sizes of both pencil, eraser and text, 'tools' which by default are pencil, eraser, text, images, undo and trash, 'admin' which allows you to log in and 'utils' in which there is share image and download image. Here is an example:

menuOrder: ['colors', 'sizes', 'tools', 'admin', 'utils']

tools [array.string]

This option allows you to change the 'tools' sub-menu order and remove or add items. Available array items are:

  • 'pencil' - basic drawing tool
  • 'eraser' - basic erasing tool
  • 'text' - inputs text
  • 'image' - allow user to add a picture from your computer or device
  • 'rectangle' - draws a rectangle
  • 'filledRectangle' - draws a rectangle filled with the same color
  • 'ellipse' - draws an ellipse
  • 'ellipseFilled' - draws an ellipse filled with the same color
  • 'lineStraight' - draws a straight line
  • 'eraserArea' - enables user to erase a specific are of the page
  • 'mark' - enables user to point to the place on the board without leaving a mark
  • 'trash' - erases everything on a current page
  • 'undo' - undoes the last operation on the board
  • 'pan' - enables user to move along the board

Here is an example:

tools: ['pencil', 'eraser', 'text', 'image']

colors [array.string]

This option allows you to change color sub-menu with adding or removing colors as you wish. They can be inputted in all standard CSS codes which include names, hex, rgb, hsl and hsv. Here are the default colors:

colors: [ "#000000", "#f44336", "#4caf50", "#2196f3", "#ffc107",
          "#9c27b0", "#e91e63", "#795548"]

defaultColor [string]

With this option you can set a default color that will appear as the color button on the main menu. It doesn't have to be a part of your color sub-menu array. As with above mentioned colors, you can set in all standard CSS codes. The default of this option is black. Here is an example:

defaultColor: "#000000"

defaultSize [number]

With this option you can set a default size, a size you start with when you begin painting a new picture. Default of this option is 8. Here is an example:

defaultSize: 8

defaultTool [string]

With this option you can set a default tool which you use to paint a picture with, the options are the same as in above mentioned tools: pencil, eraser, text, image. Default of this option is pencil. Here is an example:

defaultTool: 'pencil'

inviteViaQr [boolean]

With this option you can enable a QR code to be shown in the invite dialog so users can scan the code and automatically join the board. This feature is great for in person presentations like conferences or classrooms. Generated code points to the current board and it is in 1000x1000 dimensions so it can be opened in new tab in a large size. Default value is false.

inviteViaQr: true

multiPage [boolean]

With this option you can enable your board to have multiple pages. By default, this flag is set to false when the board will have only one page and by setting it to true, you will see a navigation bar on the bottom of the board. Keep in mind that navigation bar, along with the plus sign for adding another page is visible only after the first thing is drawn on the current page. Pages on the board are unlimited.

multiPage: true

AwwBoard methods

Available methods for awwapp are:

Get methods:

awwapp.getCanvas()

  • get canvas element
  • returns: [element] canvas element

awwapp.getImage(type)

  • calls toDataURL
  • parameter: type [string] defaults to image/png
  • returns: [string] canvas image as data URL

awwapp.getBoardInfo()

  • get board information
  • gives information of a shared board (only if the board is shared)
  • returns: [object] has boardLink, boardGuestLink and boardID

awwapp.getLocalOps()

  • get all operations received from server
  • gives a list of drawing operations which have been made on canvas
  • returns: [array] list of operations

awwapp.getQueuedOps()

  • get a list of queued operations
  • gives a list of drawing operations which have been made on canvas but haven't been sent to the server
  • returns: [array] list of queued operations

Do methods:

awwapp.doResize()

  • trigger resize

awwapp.doRedraw()

  • trigger redraw

awwapp.doClear()

  • clears the whole canvas

awwapp.doUndo()

  • does undo of the previous own operation (not someone else's in case there are multiple users of one shared board)

Draw methods:

awwapp.doDrawLine(color, width, x1, y1, x2, y2)

  • draws line on canvas with a set color, width in px, between (x1, y1) and (x2, y2)
  • parameters:
    • color [string] can be set to 'eraser'
    • width [number] line width
    • x1 [number]
    • y1 [number]
    • x2 [number]
    • y2 [number]
  • example:
<div id="aww-wrapper"></div>
<script src="https://awwapp.com/static/widget/js/aww.min.js">
</script>
<script type="text/javascript">
        var aww = new AwwBoard('#aww-wrapper', {
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba'
        });
aww.doDrawLine('green', 10, 50, 50, 600, 600);
</script>

awwapp.drawText(text, x, y, color, font)

  • draws text on canvas using set font (font size, font family) in a set color, on coordinates (x, y)
  • parameters:
    • text [string]
    • x [number]
    • y [number]
    • color [string]
    • font [string] css shorthand font definition
  • example:
<div id="aww-wrapper"></div>
<script src="https://awwapp.com/static/widget/js/aww.min.js">
</script>
<script type="text/javascript">
        var aww = new AwwBoard('#aww-wrapper', {
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba'
        });
        aww.drawText("This is drawing text", 100, 200, "green",
                     "30px mono");
</script>

awwapp.drawImage(url, x, y)

  • draw image to canvas
  • directly inserts an image from the input URL to (x,y) coordinates without any resizing or rotating
  • parameters:
    • url [string]
    • x [number]
    • y [number]
  • example:
<div id="aww-wrapper"></div>
<script src="https://awwapp.com/static/widget/js/aww.min.js">
</script>
<script type="text/javascript">
        var aww = new AwwBoard('#aww-wrapper', {
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba'
        });
        aww.drawImage('http://www.placekitten.com/g/200/300', 100, 50);
</script>

The rest of the methods:

awwapp.defaultOps

  • [object] contains default operation definitions, which can be extended and used as custom operations

awwapp.openImageDialog()

  • open image selection dialogue, has to be used in callback of user initiated event
  • allows the user to open, select and insert an image to the canvas

awwapp.openImageEditor(src)

  • opens image editor with specified image URL
  • allows user to position the image but not select it, the editing image is taken from the input URL
  • parameter:
    • src [string] URL of the image to put onto canvas (can be data URL)

awwapp.joinBoard(link)

  • join board with optional link
  • parameter:
    • link [string] (optional) desired boardLink

awwapp.leaveBoard()

  • disconect from board

awwapp.downloadBoardPicture()

  • download board picture

awwapp.shareBoardPicture()

  • share board picture on awwapp.com

awwapp.toggleChatWindow()

  • toggle chat window
  • turns chat window on and off (only with shared board)

awwapp.toggleVoiceChat()

  • toggles voice call
  • turns voice chat on and off (only with chrome, android and firefox)

API custom behaviour

If you wish to customize your awwapp with more buttons, menus and tools than this is the page for you.

Adding the whiteboard widget is simple, easy and takes only a few lines of code to have the basic, default board. If you wish to further modify your whiteboard, other that the already made options and methods, you can. Please read further is you are interested in adding and modifying behaviours as needed.

Add a menu

To add a menu or (a complete) submenu item, all you need to do is write a few extra lines of code. First you will need to define it's behaviour (what happens when you click on it) and appearance (the icon and the background of the item). Second is adding it to the 'menuOrder' list, so that your new menu can be shown in the whiteboard widget.

For a start, here is a helper function that creates image for the menu button and we will be using it for the rest of examples:

function makeButton(src) {
     var btnImg = document.createElement('img');
     btnImg.setAttribute('src', src);
     btnImg.setAttribute('width', '24px');
     btnImg.setAttribute('height', '24px');
     return btnImg;
}

Now, let's define a function that will run your custom behaviour code. In this example, it will only show a message box with a greeting:

function myHandler() {
     alert ('Hello, World!');
}

With that set up, we can now create a simple menu button. Here is an example of just that:

var aww = new AwwBoard('#aww-wrapper', {
  … // other options as needed
  menuItems: {
    myMenuItem: {
      style: {background: 'darkgreen'},
      onclick: myHandler,
      content: makeButton('http://www.entypo.com/images/chat.svg')
    },
  },
  menuOrder: ['colors', 'tools', 'myMenuItem']
});

As you can see from this example, customizing the button style is also possible (here we set background to be dark green instead of the default).

Add a submenu

Adding a submenu is very similar to adding a menu, the difference is that instead of 'onClick' handler, the menuItem has a 'submenu' property, which is again a list of menu items:

var aww = new AwwBoard('#aww-wrapper', {
  ... // other options as needed
  menuItems: {
    mySubMenu: {
      style: {padding: '18px', background: 'red'},
      content: makeButton('http://www.entypo.com/images/folder.svg'),
      submenu: [{
        style: { padding: '18px', color: 'white'},
        onclick: function(){ alert('First'); },
        content: '1'
      }, {
        style: { padding: '18px', color: 'white'},
        onclick: function(){ alert('Second'); },
        content: '2'
      }, {
        style: { padding: '18px', color: 'white'},
        onclick: function(){ alert('Third'); },
        content: '3'
      }]
    }
  },
  menuOrder: ['colors', 'tools', 'mySubMenu']
});

Add a tool

You can also extend the functionality of the whiteboard by adding custom tools.

Here is a simple tool that draws circle (functionalities: mouse down selects center, mouse up selects point on a circle, hold-and-drag defines radius) with the currently selected color.

var aww = new AwwBoard('#aww-wrapper', {
  ... // other options as needed
  customOps: {
    circle: {
      onPenDown: function(e) {
        this.center = e.normalizedPoint;
      },
      onPenUp: function(e) {
        e.preventDefault();
        if (e.type === 'mouseout') return;

        var p = e.normalizedPoint;
        var r = Math.sqrt(Math.pow(p[0] - this.center[0], 2) +
          Math.pow(p[1] - this.center[1], 2));

        if (r < 1) return;
          aww.drawArc(this.opState.color(), this.center[0],
              this.center[1], r, 0, 2 * Math.PI, false);
      }
    }
  },
});

This makes a fully functional tool, but for it to be visible on the whiteboard itself, we will need to add it to the 'tools' menu by specifying the 'tools' option:

var aww = new AwwBoard('#aww-wrapper', {
  ... // other options as needed
  tools: [ ... other tools..., 'circle']
});

Alternatively, you can leave it hidden and explicitly switch to it from your own custom menu item, by emitting a 'change-tool' message in your menu item handler like this:

function myHandler() {
  alert('Switching to circle tool');
  aww._dispatcher.emit('change-tool', {tool: 'circle'});
}

Here is a code sample of everything that was mentioned in the examples on this page:

<div id="aww-wrapper"></div>
<script src="https://awwapp.com/static/widget/js/aww.min.js">
</script>
<script type="text/javascript">
  function makeButton(src) {
    var btnImg = document.createElement('img');
    btnImg.setAttribute('src', src);
    btnImg.setAttribute('width', '24px');
    btnImg.setAttribute('height', '24px');
    return btnImg;
  }
  function myHandler() {
    alert('Switching to circle tool');
    aww._dispatcher.emit('change-tool', { tool: 'circle' });
  }
  var aww = new AwwBoard('#aww-wrapper', {
    menuItems: {
      myMenuItem: {
        style: {background: 'darkgreen'},
        onclick: myHandler,
        content: makeButton('http://www.entypo.com/images/chat.svg')
      },
      mySubMenu: {
        style: {padding: '18px', background: 'red'},
        content: makeButton('http://www.entypo.com/images/folder.svg'),
        submenu: [{
            style: { padding: '18px', color: 'white'},
            onclick: function(){ alert('First'); },
            content: '1'
        }, {
            style: { padding: '18px', color: 'white'},
            onclick: function(){ alert('Second'); },
            content: '2'
        }, {
            style: { padding: '18px', color: 'white'},
            onclick: function(){ alert('Third'); },
            content: '3'
        }]
      }
    },
    menuOrder: ['colors', 'tools', 'myMenuItem', 'mySubMenu'],
    customOps: {
      circle: {
        onPenDown: function(e) {
          this.center = e.normalizedPoint;
        },
        onPenUp: function(e) {
          e.preventDefault();
          if (e.type === 'mouseout') return;

          var p = e.normalizedPoint;
          var r = Math.sqrt(Math.pow(p[0] - this.center[0], 2) +
            Math.pow(p[1] - this.center[1], 2));

          if (r < 1) return;
          aww.drawArc(this.opState.color(), this.center[0],
            this.center[1], r, 0, 2 * Math.PI, false);
        },
        onPenMove: function() {}
      }
    }
  });
</script>