{"_id":"@1024pix/drawingboard.js","_rev":"7-794db2ba31e703e71a2ace46acc6efd9","name":"@1024pix/drawingboard.js","dist-tags":{"latest":"0.5.0"},"versions":{"0.5.0":{"name":"@1024pix/drawingboard.js","version":"0.5.0","_id":"@1024pix/drawingboard.js@0.5.0","maintainers":[{"name":"yoandl","email":"yoan.de-luca@pix.fr"},{"name":"mickaelalibert","email":"mickael.alibert@pix.fr"},{"name":"mireillecampourcy","email":"mireille.campourcy@pix.fr"},{"name":"nicolas.lepage","email":"nicolas.lepage@zenika.com"},{"name":"vincenthardouin","email":"vincenthardouin@icloud.com"},{"name":"yann_bertrand","email":"npm@y.bertrand.bzh"},{"name":"pix-owner","email":"dev@pix.fr"}],"dist":{"shasum":"2948ac30ae60fba4bc6b57e34f521c68d2b6d134","tarball":"https://registry.npmjs.org/@1024pix/drawingboard.js/-/drawingboard.js-0.5.0.tgz","fileCount":47,"integrity":"sha512-SMUOnO2fmu8TGLQTKxAOYAhgnUv0rrJWCQAtbdpUBpQd1ueCXLXUbj0we3+cTJxKg25yHu89/MJUXzmYF7yyFA==","signatures":[{"sig":"MEQCIC9aNRkn+HEm+ZDwa8QDUX4NJNZVTsfwemPIiKH7GnZnAiBJI/DNIATjBMJwF0nyHaLXiVGdQ8Hohkv8SF0b++Lbig==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":490405},"main":"dist/drawingboard.js","gitHead":"c37cdbf6a4d595732de7c3814686436e926495ef","_npmUser":{"name":"nicolas.lepage","email":"nicolas.lepage@zenika.com"},"_npmVersion":"9.8.1","description":"This is a canvas based drawing app that you can integrate easily on your website.","directories":{},"_nodeVersion":"18.18.2","_hasShrinkwrap":false,"devDependencies":{"grunt":"~0.4.1","grunt-contrib-concat":"~0.3.0","grunt-contrib-cssmin":"~0.6.1","grunt-contrib-uglify":"~0.2.2"},"_npmOperationalInternal":{"tmp":"tmp/drawingboard.js_0.5.0_1697481732770_0.3397575916679325","host":"s3://npm-registry-packages"}}},"time":{"created":"2023-10-16T18:42:12.644Z","modified":"2026-08-21T13:06:22.079Z","0.5.0":"2023-10-16T18:42:13.051Z"},"description":"This is a canvas based drawing app that you can integrate easily on your website.","maintainers":[{"email":"dev@pix.fr","name":"pix-owner"},{"email":"nicolas.lepage@zenika.com","name":"nicolas.lepage"}],"readme":"# drawingboard.js\n\nThis is a canvas based drawing app that you can integrate easily on your website.\n\ndrawingboard.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.\n\nYou 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.\n\nlocal and session storage are supported: your last drawing is restored when you come back on the website.\n\nYou can set a background image at initialization, or let the user drop one on the canvas.\n\nThe 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.\n\n## Requirements and Installation\n\n[Check the source of the demo page to see how to integrate the drawingboard in practice](http://leimi.github.io/drawingboard.js/)\n\nThe board requires jQuery. Since its usage is pretty light, it may work as usual if you use zepto but I didn't test it.\n\nIf you use [Bower](http://twitter.github.com/bower/), getting the files is easy with command line: `bower install drawingboard.js`.\n\nAfter 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.\n\n## Creating a drawingboard\n\n[Check the source of the demo page to see how to integrate the drawingboard in practice](http://leimi.github.io/drawingboard.js/)\n\nThe 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:\n\n```html\n<div id=\"zbeubeu\"></div>\n\n<style>\n\t#zbeubeu {\n\t\twidth: 400px;\n\t\theight: 600px;\n\t}\n</style>\n\n<script>\n\tvar myBoard = new DrawingBoard.Board('zbeubeu');\n</script>\n```\n\n### Options\n\nWhen instantiating the drawingboard, you can pass a few options as the 2nd parameter in an object:\n\n* `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 }}]`).\n* `controlsPosition`: define where to put the controls: at the \"top\" or \"bottom\" of the canvas, aligned to \"left\"/\"right\"/\"center\". `\"top left\"` by default.\n* `color`: the board's pencil color. `\"#000000\"` (black) by default.\n* `size`: the board's pencil size (integer). `1`px radius by default.\n* `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.\n* `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.\n* `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.\n* `droppable`: do we allow the user to drop an image on the board to draw on it? `false` by default.\n* `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.\n* `errorMessage`: html string to put in the board's element on browsers that don't support canvas.\n* `stretchImg`: default behavior of image setting on the canvas: set to the canvas width/height or not? `false` by default\n\n## Controls\n\nA \"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.\n\nThe 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.\n\n### Included controls\n\n* `DrawingBoard.Control.Color`: the color picker.\n* `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).\n* `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.\n* `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.\n* `DrawingBoard.Control.Download`: show a button to download current drawing *(not loaded by default)*.\n\n### Creating new controls\n\nEvery 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:\n\n```javascript\nDrawingBoard.Control.Example = DrawingBoard.Control.extend({\n\t//prototype\n});\n```\n\nA control has a few attributes and methods:\n\n* `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-\").\n* `$el`: the jQuery object that will be appended to the drawing-board-controls container.\n* `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.\n* `board`: the `DrawingBoard.Board` attached to the control.\n* `opts`: the options passed at initialization of an instance.\n* `defaults`: default options of the class.\n* `addToBoard`: appends the control to the DOM.\n* `onBoardReset`: method bind to the `board:reset` event.\n\nWith 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.\n\n*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.\n\n## Events\n\nThe 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).\n\nEvents currently triggered are:\n\n* board:reset\n* board:restoreLocalStorage\n* board:restoreSessionStorage\n* board:saveLocalStorage\n* board:saveSessionStorage\n* board:clearLocalStorage\n* board:clearSessionStorage\n* board:mode\n* board:startDrawing\n* board:drawing\n* board:stopDrawing\n* board:mouseOver\n* board:mouseOut\n* board:userAction\n* board:imageDropped\n* color:changed *(from the Color control)*\n* size:changed *(from the Size control)*\n\nWhen using the drawingboard or adding features, follow the MicroEvent simple API:\n\n```javascript\nvar myBoard = new DrawingBoard.Board('zbeubeu');\n\n//listen to an event\nmyBoard.ev.bind('board:reset', why);\n\n//stop listening to it\nmyBoard.ev.unbind('board:reset', why);\n\nfunction why() {\n    alert('OH GOD WHY');\n}\n\n//you can also trigger new events\nmyBoard.ev.trigger('readme:example', 'what', 'up');\n\n//and listen to them\nmyBoard.ev.bind('readme:example', function(one, two) {\n    console.log(one, two); // 'what', 'up'\n});\n```\n\n\n## Getting the image inside the board to store server-side\n\nA 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.\n\nOne very simple example of storing drawingboard images with PHP is shown [in this gist](https://gist.github.com/Leimi/9179019).\n\n## Building your own\n\nIf you have style changes to make, you can use [Compass](http://compass-style.org/).\nIf you've added some controls or changed the drawingboard a bit, you can rebuild the minified files with [Grunt](http://gruntjs.com/):\n\n* in the `Gruntfile.js` file, update the `concat` task by setting all the source files you want\n* [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.\n\n## Third party stuff used\n\nThe drawingboard works thanks to:\n\n* [jQuery](http://jquery.com) for DOM manipulation,\n* [Compass](http://compass-style.org/) for styling,\n* [Yusuke Kamiyamane's Fugue Icons](http://p.yusukekamiyamane.com/) for icons,\n* [MicroEvent](https://github.com/jeromeetienne/microevent.js) for simple events,\n* [tim](http://github.com/premasagar/tim) for simple templates,\n* [Grunt](http://gruntjs.com) for all the building stuff.\n\n## Want more? Alternatives to drawingboard.js\n\ndrawingboard.js is a library I built because I couldn't find anything like it in the beginning of 2013.\n\nIt'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…\n\nHere are a couple of other tools you can try if the drawingboard doesn't satisfy you:\n\n* [Literally Canvas](http://literallycanvas.com/),\n* [wPaint.js](http://wpaint.websanova.com/).\n\n## License\n\ndrawingboard.js is [MIT licensed](LICENSE).\n\nCopyright (c) 2013 Emmanuel \"[@Leimina](http://twitter.com/Leimina)\" Pelletier.\n","readmeFilename":"README.md"}