/bower_components/drawingboard.js/README.md |
@@ -0,0 +1,190 @@ |
# drawingboard.js |
|
This is a canvas based drawing app that you can integrate easily on your website. |
|
drawingboard.js consists of a blank canvas surrounded by a few UI elements that control it: a color picker, a pencil, a paint can, an eraser, a pencil size chooser, navigations and reset buttons. |
|
You can draw with mouse or touch on pretty much [every browser that supports `<canvas>`](http://caniuse.com/#feat=canvas). Didn't test that much on IE but hey, WIP. |
|
local and session storage are supported: your last drawing is restored when you come back on the website. |
|
You can set a background image at initialization, or let the user drop one on the canvas. |
|
The drawingboard is really lightweight, but also really simple: if you want something more complete, go look at similar projects at the bottom of this doc. |
|
## Requirements and Installation |
|
[Check the source of the demo page to see how to integrate the drawingboard in practice](http://manu.habite.la/drawingboard/example/) |
|
The board requires jQuery. Since its usage is pretty light, it may work as usual if you use zepto but I didn't test it. |
|
If you use [Bower](http://twitter.github.com/bower/), getting the files is easy with command line: `bower install drawingboard.js`. |
|
After jQuery, you can include the minified script and stylesheet contained in the `dist` folder. `drawingboard.min.js` *(~4.1kb minified and gzipped)* contains everything whereas `drawingboard.nocontrol.min.js` *(~2.6kb)* [does not contain controls](http://manu.habite.la/drawingboard/img/moto.jpg). Don't worry about having to store icon files on your server: they are directly embedded in the CSS as base64 strings. |
|
## Creating a drawingboard |
|
[Check the source of the demo page to see how to integrate the drawingboard in practice](http://manu.habite.la/drawingboard/example/) |
|
The drawingboard is tied to an HTML element with an #id. Set the dimensions of the desired board with CSS on the HTML element, and create it with one line of JavaScript: |
|
```html |
<div id="zbeubeu"></div> |
|
<style> |
#zbeubeu { |
width: 400px; |
height: 600px; |
} |
</style> |
|
<script> |
var myBoard = new DrawingBoard.Board('zbeubeu'); |
</script> |
``` |
|
### Options |
|
When instantiating the drawingboard, you can pass a few options as the 2nd parameter in an object: |
|
* `controls`: an array containing the list of controls automatically loaded with the board. The 'Color', 'DrawingMode', 'Size' and 'Navigation' controls are loaded by default. You can pass an object instead of a string to pass control options (ie `['Color', { Navigation: { reset: false }}]`). |
* `controlsPosition`: define where to put the controls: at the "top" or "bottom" of the canvas, aligned to "left"/"right"/"center". `"top left"` by default. |
* `color`: the board's pencil color. `"#000000"` (black) by default. |
* `size`: the board's pencil size (integer). `1`px radius by default. |
* `background`: the board's background. Give an hex/rgb/hsl value for a color, `false` to have nothing (transparent board). Anything else will be seen as an image. `"#fff"` (white) by default. |
* `eraserColor`: color of the eraser tool. Set to `"background"` so that the eraser takes the background color, `"transparent"` to make transparent lines or set any other color directly (rgb, hsl, #). `"background"` by default. |
* `webStorage`: do we enable webStorage support? can be `"session"`, `"local"` or false. The drawing is saved in sessionStorage or localStorage and restored when you come back on it. `"session"` by default. |
* `droppable`: do we allow the user to drop an image on the board to draw on it? `false` by default. |
* `enlargeYourContainer`: how should be sized the drawingboard? When `true`, the CSS width and height will be set on the final board's *canvas*, ie the drawing zone. In the example above, that means the board's container will be taller than 400px because of the controls height. If `false`, the CSS width and height will be set on the board's container. That means the addition of the canvas and the controls will be 400px high. `false` by default. |
* `errorMessage`: html string to put in the board's element on browsers that don't support canvas. |
* `stretchImg`: default behavior of image setting on the canvas: set to the canvas width/height or not? `false` by default |
|
## Controls |
|
A "control" is a UI element designed to let the user interact with the board. Change the size/color of the pencil, navigate through the drawings history, have an "eraser" button... you can pretty much do what you want. |
|
The drawingboard has a few simple controls loaded by default, but you can easily create your own if the given ones don't satisfy you or else. |
|
### Included controls |
|
* `DrawingBoard.Control.Color`: the color picker. |
* `DrawingBoard.Control.Size`: a pencil size chooser. Choose your `type` in the options: `"dropdown"` is a simple dropdown menu, whereas `"range"` uses a range input. Default to `"auto"`: if the browser supports the range input it will use it, otherwise it will use the dropdown menu. As seen in the example page, you can set the type to `"range"` and add a [range input polyfill](https://github.com/freqdec/fd-slider) if you want it on [every browser](http://caniuse.com/#feat=input-range). |
* `DrawingBoard.Control.DrawingMode`: show buttons to draw with the `"pencil"` (normal mode), the `"filler"` (the paint can) and an `"eraser"`. You can choose which buttons to show with the options. |
* `DrawingBoard.Control.Navigation`: undo, redo actions and reset the canvas to blank with 3 buttons. You can choose to show or hide each button individually with options. |
* `DrawingBoard.Control.Download`: show a button to download current drawing *(not loaded by default)*. |
|
### Creating new controls |
|
Every control extends the `DrawingBoard.Control` class. You can define a new control by extending it in the same way [Backbone.js](http://backbonejs.org/) works: |
|
```javascript |
DrawingBoard.Control.Example = DrawingBoard.Control.extend({ |
//prototype |
}); |
``` |
|
A control has a few attributes and methods: |
|
* `name`: name of the control. Used to add a class on the div element that will be appended to the drawing-board-controls container (prefixed with "drawing-board-control-"). |
* `$el`: the jQuery object that will be appended to the drawing-board-controls container. |
* `initialize`: the function invoked when a new instance of the control is created. A `DrawingBoard.Board` object is passed as 1st argument and an object of options as 2nd. |
* `board`: the `DrawingBoard.Board` attached to the control. |
* `opts`: the options passed at initialization of an instance. |
* `defaults`: default options of the class. |
* `addToBoard`: appends the control to the DOM. |
* `onBoardReset`: method bind to the `board:reset` event. |
|
With the `board` property you can pretty much do what you want: bind to and trigger events (`this.board.ev`), manipulate the canvas through the rendering context (`this.board.ctx`), etc. |
|
*Note:* since the controls are displayed as `table-cell`, you might want to add a `div.drawing-board-control-inner` when you create your control template (like in the 'Color' and the 'Size' controls) if you need to position relative/absolute things. |
|
## Events |
|
The drawingboard has events included that you can rely on. Events are all dispatched in the `ev` attribute of the board, which is based on [the microevent.js library](https://github.com/jeromeetienne/microevent.js). |
|
Events currently triggered are: |
|
* board:reset |
* board:restoreLocalStorage |
* board:restoreSessionStorage |
* board:saveLocalStorage |
* board:saveSessionStorage |
* board:clearLocalStorage |
* board:clearSessionStorage |
* board:mode |
* board:startDrawing |
* board:drawing |
* board:stopDrawing |
* board:mouseOver |
* board:mouseOut |
* board:userAction |
* board:imageDropped |
* color:changed *(from the Color control)* |
* size:changed *(from the Size control)* |
|
When using the drawingboard or adding features, follow the MicroEvent simple API: |
|
```javascript |
var myBoard = new DrawingBoard.Board('zbeubeu'); |
|
//listen to an event |
myBoard.ev.bind('board:reset', why); |
|
//stop listening to it |
myBoard.ev.unbind('board:reset', why); |
|
function why() { |
alert('OH GOD WHY'); |
} |
|
//you can also trigger new events |
myBoard.ev.trigger('readme:example', 'what', 'up'); |
|
//and listen to them |
myBoard.ev.bind('readme:example', function(one, two) { |
console.log(one, two); // 'what', 'up' |
}); |
``` |
|
|
## Getting the image inside the board to store server-side |
|
A common thing you may want to do is to store images drawn with the board on your server. This is simple to do with the `getImg` method that returns the board content as a 64 bit encoded PNG URL. |
|
One very simple example of storing drawingboard images with PHP is shown [in this gist](https://gist.github.com/Leimi/9179019). |
|
## Building your own |
|
If you have style changes to make, you can use [Compass](http://compass-style.org/). |
If you've added some controls or changed the drawingboard a bit, you can rebuild the minified files with [Grunt](http://gruntjs.com/): |
|
* in the `Gruntfile.js` file, update the `concat` task by setting all the source files you want |
* [install grunt](http://gruntjs.com/getting-started) globally if necessary, and run `npm install` in your command line in the project to install the project-specific grunt tools. In the end, run `grunt`. Minified files in the `dist` folders are now updated. |
|
## Third party stuff used |
|
The drawingboard works thanks to: |
|
* [jQuery](http://jquery.com) for DOM manipulation, |
* [Compass](http://compass-style.org/) for styling, |
* [Yusuke Kamiyamane's Fugue Icons](http://p.yusukekamiyamane.com/) for icons, |
* [MicroEvent](https://github.com/jeromeetienne/microevent.js) for simple events, |
* [tim](http://github.com/premasagar/tim) for simple templates, |
* [Grunt](http://gruntjs.com) for all the building stuff. |
|
## Want more? Alternatives to drawingboard.js |
|
drawingboard.js is a library I built because I couldn't find anything like it in the beginning of 2013. |
|
It's really lightweight, simple to use and integrate, works great on mobile and draws really smooth lines! But it misses a few important features and it's not that extendable… |
|
Here are a couple of other tools you can try if the drawingboard doesn't satisfy you: |
|
* [Literally Canvas](http://literallycanvas.com/), |
* [wPaint.js](http://wpaint.websanova.com/). |
|
## License |
|
drawingboard.js is [MIT licensed](LICENSE). |
|
Copyright (c) 2013 Emmanuel "[@Leimina](http://twitter.com/Leimina)" Pelletier. |