scratch – Blame information for rev 84

Subversion Repositories:
Rev:
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.