|
| 1 | +# js-offcanvas |
| 2 | + |
| 3 | +jQuery accessible Offcanvas plugin, using ARIA |
| 4 | + |
| 5 | +[View Demo](http://offcanvas.vasilis.co) |
| 6 | + |
| 7 | +## Why it is accessible |
| 8 | + |
| 9 | +- It relies on <a href="https://www.w3.org/TR/wai-aria-practices/#dialog_modal"><abbr title="Accessible Rich Internet Application">ARIA</abbr> Design pattern for Dialogs</a> |
| 10 | +- The tab key loops through all of the keyboard focusable items within the offcanvas |
| 11 | +- You can close it using <kbd>Esc</kbd>. |
| 12 | + |
| 13 | +##Features |
| 14 | + |
| 15 | +- Uses CSS transforms & transitions. |
| 16 | +- BEM <kbd>c-offcanvas c-offcanvas--left is-open</kbd> |
| 17 | +- From Any Direction: left, right, top and bottom. |
| 18 | +- Overlay, Reveal and Push. |
| 19 | +- API & Events |
| 20 | +- Package managers Bower & NPM |
| 21 | + |
| 22 | +*** |
| 23 | +######Table of Contents |
| 24 | + |
| 25 | + |
| 26 | +1. [Getting Started](#getting-started) |
| 27 | + * [CDN](#cdn) |
| 28 | + * [HTML](#html) |
| 29 | + * [JS](#js) |
| 30 | + * [Initialize with Vanilla JavaScript](#initialize-with-vanilla-javaScript) |
| 31 | + * [Initialize with jQuery](#initialize-with-vanilla-jquery) |
| 32 | + * [Initialize with HTML](#initialize-with-vanilla-html) |
| 33 | + * [Enhance](#enhance) |
| 34 | +2. [Options](#options) |
| 35 | + * [API](#api) |
| 36 | + * [Methods](#methods) |
| 37 | + * [Callbacks](#callbacks) |
| 38 | + * [Events](#events) |
| 39 | +3. [Examples](#examples) |
| 40 | +4. [Package Managers](#package-managers) |
| 41 | +5. [Dependencies](#dependencies) |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## Getting Started |
| 46 | +#####CDN |
| 47 | +Include the Offcanvas `.css` and `.js` files in your site. Link directly to Offcanvas files on [npmcdn](https://npmcdn.com/). |
| 48 | +```html |
| 49 | +<script src="https://npmcdn.com/js-offcanvas@1.0/dist/_js/js-offcanvas.pkgd.min.js"></script> |
| 50 | +<link rel="stylesheet" href="https://npmcdn.com/js-offcanvas@1.0/dist/_css/minified/js-offcanvas.css"> |
| 51 | +``` |
| 52 | + |
| 53 | +#####HTML |
| 54 | +Offcanvas works on a container element with no styles applied. |
| 55 | +```html |
| 56 | +<body> |
| 57 | + <div class="c-offcanvas-content-wrap"> |
| 58 | + ... |
| 59 | + <a href="#off-canvas" data-offcanvas-trigger="off-canvas">Menu</a> |
| 60 | + ... |
| 61 | + </div> |
| 62 | + <aside id="off-canvas"></aside> |
| 63 | +</body> |
| 64 | + |
| 65 | +``` |
| 66 | +#####JS |
| 67 | +```js |
| 68 | +$( function(){ |
| 69 | + $(document).trigger("enhance"); |
| 70 | +}); |
| 71 | +``` |
| 72 | + |
| 73 | +#### Initialize with Vanilla JavaScript |
| 74 | +```js |
| 75 | +$('#off-canvas').offcanvas({ |
| 76 | +// options |
| 77 | +}); |
| 78 | +``` |
| 79 | +#### Initialize with jQuery |
| 80 | +```js |
| 81 | +var elem = document.getElementById('#off-canvas'); |
| 82 | +var offcanvas = new w.componentNamespace.Offcanvas( elem, { |
| 83 | + // options |
| 84 | + modifiers: 'left,overlay' |
| 85 | +}); |
| 86 | + |
| 87 | +offcanvas.init(); |
| 88 | +``` |
| 89 | +#### Initialize with HTML |
| 90 | + |
| 91 | +```html |
| 92 | +<a class="js-offcanvas-trigger" data-offcanvas-trigger="off-canvas" href="#off-canvas">Menu</a> |
| 93 | +<aside class="js-offcanvas" data-offcanvas-options='{ "modifiers": "left,overlay" }' id="off-canvas"></aside> |
| 94 | +``` |
| 95 | +#####Enhance |
| 96 | +Typically the enhancement is triggered on DOM ready. |
| 97 | +```js |
| 98 | +$( function(){ |
| 99 | + $(document).trigger("enhance"); |
| 100 | +}); |
| 101 | +``` |
| 102 | +#Options |
| 103 | +Set instance options by passing a valid object at initialization, or to the public defaults method. Custom options for a specific instance can also be set by attaching a data-offcanvas-options attribute to the target elment. |
| 104 | +This attribute should contain the properly formatted JSON object representing the custom options. |
| 105 | +```html |
| 106 | + data-offcanvas-options='{ "modifiers": "left,overlay",... }' |
| 107 | +``` |
| 108 | +| Name |Default |Type| |
| 109 | +| --- |---|---| |
| 110 | +| **modifiers** | "left,overlay" |string| |
| 111 | +| **baseClass** | "c-offcanvas" |string| |
| 112 | +| **modalClass** | "c-offcanvas-bg" |string| |
| 113 | +| **contentClass** | "c-offcanvas-content-wrap" |string| |
| 114 | +| **closeButtonClass** | "js-offcanvas-close" |string| |
| 115 | +| **role** | "dialog" |string| |
| 116 | +| **bodyModifierClass** | "has-offcanvas" |string| |
| 117 | +| **supportNoTransitionsClass** | "support-no-transitions" |string| |
| 118 | +| **resize** | true |boolean| |
| 119 | +| **target** | null |string| |
| 120 | +| **onInit** | null |function| |
| 121 | +| **onOpen** | null |function| |
| 122 | +| **onClose** | null |function| |
| 123 | + |
| 124 | +##API |
| 125 | +The offcanvas API offers a couple of methods to control the offcanvas and are publicly available to all active instances. |
| 126 | + |
| 127 | +```js |
| 128 | +var dataOffcanvas = $('#off-canvas').data('offcanvas-component'); |
| 129 | +``` |
| 130 | +##Methods |
| 131 | +####`open` |
| 132 | +```js |
| 133 | +dataOffcanvas.open(); |
| 134 | +``` |
| 135 | +####`close` |
| 136 | +```js |
| 137 | +dataOffcanvas.close(); |
| 138 | +``` |
| 139 | +####`toggle` |
| 140 | +```js |
| 141 | +dataOffcanvas.toggle(); |
| 142 | +``` |
| 143 | +###Callbacks |
| 144 | +####`onInit` |
| 145 | +Fires an event when offcanvas is initialized. |
| 146 | +```js |
| 147 | +dataOffcanvas.onInit = function() { |
| 148 | + console.log(this); |
| 149 | +}; |
| 150 | +``` |
| 151 | +####`onOpen` |
| 152 | +Fires an event when offcanvas is opened. |
| 153 | +```js |
| 154 | +dataOffcanvas.onOpen = function() { |
| 155 | + console.log('Callback onOpen'); |
| 156 | +}; |
| 157 | +``` |
| 158 | +####`onClose ` |
| 159 | +Fires an event when offcanvas is closed. |
| 160 | +```js |
| 161 | +dataOffcanvas.onClose = function() { |
| 162 | + console.log(this); |
| 163 | +}; |
| 164 | +``` |
| 165 | +##Events |
| 166 | +jQuery.offcanvas fires several events. Simply listen for them with the jQuery.on function. All events are namespaced with offcanvas. |
| 167 | + |
| 168 | +####`beforecreate ` |
| 169 | +Fires an event before the offcanvas is initialized. |
| 170 | +```js |
| 171 | +$( document ).on( "beforecreate.offcanvas", function( e ){ |
| 172 | + var dataOffcanvas = $( e.target ).data('offcanvas-component'); |
| 173 | + console.log(dataOffcanvas); |
| 174 | + dataOffcanvas.onInit = function() { |
| 175 | + console.log(this); |
| 176 | + }; |
| 177 | +} ); |
| 178 | +``` |
| 179 | +####`create ` |
| 180 | +Fired once the Plugin is initialized. |
| 181 | +```js |
| 182 | +$( document ).on( "create.offcanvas", function( e ){ } ); |
| 183 | +``` |
| 184 | +####`open ` |
| 185 | +Fired when the `open` method is called. |
| 186 | +```js |
| 187 | +$( document ).on( "open.offcanvas", function( e ){ } ); |
| 188 | +``` |
| 189 | +####`close ` |
| 190 | +Fired when the `close` method is called. |
| 191 | +```js |
| 192 | +$( document ).on( "close.offcanvas", function( e ){ } ); |
| 193 | +``` |
| 194 | +####`resizing ` |
| 195 | +Fired when the window is resized. |
| 196 | +```js |
| 197 | +$( document ).on( "resizing.offcanvas", function( e ){ } ); |
| 198 | +``` |
| 199 | +####`clicked ` |
| 200 | +Fired when the trigger-btn is clicked. |
| 201 | +```js |
| 202 | +$( document ).on( "clicked.offcanvas-trigger", function( e ){ |
| 203 | + var dataBtnText = $( e.target ).text(); |
| 204 | + console.log(e.type + '.' + e.namespace + ': ' + dataBtnText); |
| 205 | +} ); |
| 206 | +``` |
| 207 | + |
| 208 | +##Examples |
| 209 | +####Left |
| 210 | +*With HTML* |
| 211 | +```html |
| 212 | +<button data-offcanvas-trigger="off-canvas-left">Left</button> |
| 213 | +<aside id="off-canvas-left"></aside> |
| 214 | +``` |
| 215 | +*With jQuery* |
| 216 | +```js |
| 217 | +$('#off-canvas-left').offcanvas({ |
| 218 | + modifiers: 'left' // default |
| 219 | +}); |
| 220 | +``` |
| 221 | +####Right |
| 222 | +*With HTML* |
| 223 | +```html |
| 224 | +<button data-offcanvas-trigger="off-canvas-right">Right</button> |
| 225 | +<aside id="off-canvas-right" data-offcanvas-options='{ "modifiers": "right" }'></aside> |
| 226 | +``` |
| 227 | +*With jQuery* |
| 228 | +```js |
| 229 | +$('#off-canvas-right').offcanvas({ |
| 230 | + modifiers: 'right' |
| 231 | +}); |
| 232 | +``` |
| 233 | + |
| 234 | +####Top |
| 235 | +*With HTML* |
| 236 | +```html |
| 237 | + |
| 238 | +<button data-offcanvas-trigger="off-canvas-top">Top</button> |
| 239 | +<aside id="off-canvas-top" data-offcanvas-options='{ "modifiers": "top" }'></aside> |
| 240 | +``` |
| 241 | +*With jQuery* |
| 242 | +```js |
| 243 | +$('#off-canvas-top').offcanvas({ |
| 244 | + modifiers: 'top' |
| 245 | +}); |
| 246 | +``` |
| 247 | + |
| 248 | +####Bottom |
| 249 | +*With HTML* |
| 250 | +```html |
| 251 | +<button data-offcanvas-trigger="off-canvas-bottom">Bottom</button> |
| 252 | +<aside id="off-canvas-bottom" data-offcanvas-options='{ "modifiers": "bottom" }'></aside> |
| 253 | +``` |
| 254 | +*With jQuery* |
| 255 | +```js |
| 256 | +$('#off-canvas-bottom').offcanvas({ |
| 257 | + modifiers: 'bottom' |
| 258 | +}); |
| 259 | +``` |
| 260 | + |
| 261 | +##Package managers |
| 262 | + |
| 263 | +* Install with Bower: `bower install js-offcanvas --save` |
| 264 | +* Install with npm: `npm install js-offcanvas` |
| 265 | + |
| 266 | +##Dependencies |
| 267 | +* jQuery |
| 268 | +* Modernizr |
| 269 | +* [js-utils](https://github.com/vmitsaras/js-utils) |
| 270 | +* [js-trap-tab](https://github.com/vmitsaras/js-trap-tab) |
| 271 | +* [js-button](https://github.com/vmitsaras/js-button) |
| 272 | + |
| 273 | +--- |
| 274 | + |
| 275 | +[View Demo](http://offcanvas.vasilis.co) |
| 276 | + |
| 277 | +Feel free to [let me know](http://www.twitter.com/vmitsaras) if you use js-offcanvas in one of your websites. |
| 278 | + |
| 279 | +## Release History |
| 280 | + |
| 281 | +* `v1.0.0`: Initial release. |
| 282 | + |
| 283 | +## License |
| 284 | +Licensed under the MIT license. |
0 commit comments