scratch – Blame information for rev 94
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
84 | office | 1 | # drawingboard.js |
2 | |||
3 | This is a canvas based drawing app that you can integrate easily on your website. |
||
4 | |||
5 | 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. |
||
6 | |||
7 | 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. |
||
8 | |||
9 | local and session storage are supported: your last drawing is restored when you come back on the website. |
||
10 | |||
11 | You can set a background image at initialization, or let the user drop one on the canvas. |
||
12 | |||
13 | 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. |
||
14 | |||
15 | ## Requirements and Installation |
||
16 | |||
17 | [Check the source of the demo page to see how to integrate the drawingboard in practice](http://manu.habite.la/drawingboard/example/) |
||
18 | |||
19 | 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. |
||
20 | |||
21 | If you use [Bower](http://twitter.github.com/bower/), getting the files is easy with command line: `bower install drawingboard.js`. |
||
22 | |||
23 | 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. |
||
24 | |||
25 | ## Creating a drawingboard |
||
26 | |||
27 | [Check the source of the demo page to see how to integrate the drawingboard in practice](http://manu.habite.la/drawingboard/example/) |
||
28 | |||
29 | 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: |
||
30 | |||
31 | ```html |
||
32 | <div id="zbeubeu"></div> |
||
33 | |||
34 | <style> |
||
35 | #zbeubeu { |
||
36 | width: 400px; |
||
37 | height: 600px; |
||
38 | } |
||
39 | </style> |
||
40 | |||
41 | <script> |
||
42 | var myBoard = new DrawingBoard.Board('zbeubeu'); |
||
43 | </script> |
||
44 | ``` |
||
45 | |||
46 | ### Options |
||
47 | |||
48 | When instantiating the drawingboard, you can pass a few options as the 2nd parameter in an object: |
||
49 | |||
50 | * `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 }}]`). |
||
51 | * `controlsPosition`: define where to put the controls: at the "top" or "bottom" of the canvas, aligned to "left"/"right"/"center". `"top left"` by default. |
||
52 | * `color`: the board's pencil color. `"#000000"` (black) by default. |
||
53 | * `size`: the board's pencil size (integer). `1`px radius by default. |
||
54 | * `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. |
||
55 | * `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. |
||
56 | * `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. |
||
57 | * `droppable`: do we allow the user to drop an image on the board to draw on it? `false` by default. |
||
58 | * `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. |
||
59 | * `errorMessage`: html string to put in the board's element on browsers that don't support canvas. |
||
60 | * `stretchImg`: default behavior of image setting on the canvas: set to the canvas width/height or not? `false` by default |
||
61 | |||
62 | ## Controls |
||
63 | |||
64 | 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. |
||
65 | |||
66 | 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. |
||
67 | |||
68 | ### Included controls |
||
69 | |||
70 | * `DrawingBoard.Control.Color`: the color picker. |
||
71 | * `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). |
||
72 | * `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. |
||
73 | * `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. |
||
74 | * `DrawingBoard.Control.Download`: show a button to download current drawing *(not loaded by default)*. |
||
75 | |||
76 | ### Creating new controls |
||
77 | |||
78 | 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: |
||
79 | |||
80 | ```javascript |
||
81 | DrawingBoard.Control.Example = DrawingBoard.Control.extend({ |
||
82 | //prototype |
||
83 | }); |
||
84 | ``` |
||
85 | |||
86 | A control has a few attributes and methods: |
||
87 | |||
88 | * `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-"). |
||
89 | * `$el`: the jQuery object that will be appended to the drawing-board-controls container. |
||
90 | * `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. |
||
91 | * `board`: the `DrawingBoard.Board` attached to the control. |
||
92 | * `opts`: the options passed at initialization of an instance. |
||
93 | * `defaults`: default options of the class. |
||
94 | * `addToBoard`: appends the control to the DOM. |
||
95 | * `onBoardReset`: method bind to the `board:reset` event. |
||
96 | |||
97 | 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. |
||
98 | |||
99 | *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. |
||
100 | |||
101 | ## Events |
||
102 | |||
103 | 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). |
||
104 | |||
105 | Events currently triggered are: |
||
106 | |||
107 | * board:reset |
||
108 | * board:restoreLocalStorage |
||
109 | * board:restoreSessionStorage |
||
110 | * board:saveLocalStorage |
||
111 | * board:saveSessionStorage |
||
112 | * board:clearLocalStorage |
||
113 | * board:clearSessionStorage |
||
114 | * board:mode |
||
115 | * board:startDrawing |
||
116 | * board:drawing |
||
117 | * board:stopDrawing |
||
118 | * board:mouseOver |
||
119 | * board:mouseOut |
||
120 | * board:userAction |
||
121 | * board:imageDropped |
||
122 | * color:changed *(from the Color control)* |
||
123 | * size:changed *(from the Size control)* |
||
124 | |||
125 | When using the drawingboard or adding features, follow the MicroEvent simple API: |
||
126 | |||
127 | ```javascript |
||
128 | var myBoard = new DrawingBoard.Board('zbeubeu'); |
||
129 | |||
130 | //listen to an event |
||
131 | myBoard.ev.bind('board:reset', why); |
||
132 | |||
133 | //stop listening to it |
||
134 | myBoard.ev.unbind('board:reset', why); |
||
135 | |||
136 | function why() { |
||
137 | alert('OH GOD WHY'); |
||
138 | } |
||
139 | |||
140 | //you can also trigger new events |
||
141 | myBoard.ev.trigger('readme:example', 'what', 'up'); |
||
142 | |||
143 | //and listen to them |
||
144 | myBoard.ev.bind('readme:example', function(one, two) { |
||
145 | console.log(one, two); // 'what', 'up' |
||
146 | }); |
||
147 | ``` |
||
148 | |||
149 | |||
150 | ## Getting the image inside the board to store server-side |
||
151 | |||
152 | 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. |
||
153 | |||
154 | One very simple example of storing drawingboard images with PHP is shown [in this gist](https://gist.github.com/Leimi/9179019). |
||
155 | |||
156 | ## Building your own |
||
157 | |||
158 | If you have style changes to make, you can use [Compass](http://compass-style.org/). |
||
159 | If you've added some controls or changed the drawingboard a bit, you can rebuild the minified files with [Grunt](http://gruntjs.com/): |
||
160 | |||
161 | * in the `Gruntfile.js` file, update the `concat` task by setting all the source files you want |
||
162 | * [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. |
||
163 | |||
164 | ## Third party stuff used |
||
165 | |||
166 | The drawingboard works thanks to: |
||
167 | |||
168 | * [jQuery](http://jquery.com) for DOM manipulation, |
||
169 | * [Compass](http://compass-style.org/) for styling, |
||
170 | * [Yusuke Kamiyamane's Fugue Icons](http://p.yusukekamiyamane.com/) for icons, |
||
171 | * [MicroEvent](https://github.com/jeromeetienne/microevent.js) for simple events, |
||
172 | * [tim](http://github.com/premasagar/tim) for simple templates, |
||
173 | * [Grunt](http://gruntjs.com) for all the building stuff. |
||
174 | |||
175 | ## Want more? Alternatives to drawingboard.js |
||
176 | |||
177 | drawingboard.js is a library I built because I couldn't find anything like it in the beginning of 2013. |
||
178 | |||
179 | 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… |
||
180 | |||
181 | Here are a couple of other tools you can try if the drawingboard doesn't satisfy you: |
||
182 | |||
183 | * [Literally Canvas](http://literallycanvas.com/), |
||
184 | * [wPaint.js](http://wpaint.websanova.com/). |
||
185 | |||
186 | ## License |
||
187 | |||
188 | drawingboard.js is [MIT licensed](LICENSE). |
||
189 | |||
190 | Copyright (c) 2013 Emmanuel "[@Leimina](http://twitter.com/Leimina)" Pelletier. |