marksmccann / boost-js-modal

A style-free modal plugin for jQuery and Boost JS

Boost JS Modal

A style-free and accessible modal plugin for jQuery and Boost JS. This plugin only includes styles absolutely necessary for the modal to work properly, the rest is up to you.

Installation

Install with npm:

npm install boost-js-modal

Install in browser:

<script src="https://cdn.rawgit.com/marksmccann/boost-js-modal/v0.1.1/dist/modal.min.js"></script>

---

AND include styles:

<link rel="stylesheet" href="https://cdn.rawgit.com/marksmccann/boost-js-modal/v0.1.1/dist/modal.min.css">

Usage

Create Plugin

var boost = require('boost-js');
// var boost = $.fn.boost; (browser install)

var modal = require('boost-js-modal');
// var modal = $.fn.boost.modal; (browser install)

$.fn.modal = boost( modal.plugin, modal.defaults );

Markup Structure

<div id="modal">
    <h2 data-bind="#modal" data-role="heading">Heading</h2>
    <button data-bind="#modal" data-role="close">Close</button>
</div>
<button data-bind="#modal" data-role="open">Open</button>

Tip: Add style="display:none;" to your source element if your modal is momentarily visible before the app is able to hide it; the attribute will be removed after instantiation.

Note: data-bind is used to link the element to the instance, data-role is used to define the element's role in that instance. See Boost JS for more details.

Instantiate Plugin

$('#modal').modal();

Options

Name	Default	Description
activeClass*	"is-open"	the class added to the outer container when active
wrapClass*	"modal-wrap"	the class added to the inner container of the modal
maskClass*	"modal-mask"	the class added to the mask/outer-most container of the modal
effect	null	an optional animation for modal, see below for details
closeOnClickOff	true	close the modal if user clicks anywhere off of it
closeOnEsc	true	close the modal when user presses the esc key
openOnLoad	false	open the modal at instantiation (page load)
onOpen	null	a callback function called when the modal is opened
onClose	null	a callback function called when modal is closed
onInit	null	a callback function called when modal is initialized
*Note: if you change any of the class names, you will have to update the same classes in the css as well.

Usage

$('#modal').modal({
    onInit: function() {
        console.log( this.id ); // 'modal'
    }
});

- or -

<div id="modal" data-open-on-load="true">...</div>

Roles

Name	Element	Description
open	a, button	defines a trigger that opens the modal
close	a, button	defines a trigger that closes the modal
toggle	a, button	defines a trigger that toggles the modal open and closed
heading	h2	used to define the modal with a aria-labelledby on container
end	a, button	defines the last focusable element in modal for blur event

Usage

<button data-bind="[instance-id]" data-role="[role-name]">...</button>

Effects

1. scale-up
2. scale-down
3. slide-left
4. slide-right
5. slide-up
6. slide-down
7. sticky-top
8. horizontal-flip
9. vertical-flip
10. spin-up
11. spin-down
12. fall-left
13. fall-right
14. swing-down
15. swing-up
16. swing-left
17. swing-right
18. front-flip
19. back-flip

Usage

Include the effects stylesheet

<link rel="stylesheet" href="https://cdn.rawgit.com/marksmccann/boost-js-modal/v0.1.1/dist/effects.min.css">

Then update the setting

<div id="modal" data-effect="scale-up">...</div>

API

open( fn )

Opens the modal. fn: optional callback function called after opening.

instance.open();

close( fn )

Closes the modal. fn: optional callback function called after opening.

instance.close();

toggle( fn )

Closes the modal if it is open and opens the modal if it is closed. fn: optional callback function called after opening.

instance.toggle();

isOpen()

Determines if modal is open or not, returns a boolean.

instance.isOpen();

lastOpenedBy

The element last triggered to open this modal. After the modal is closed, this value returns to null.

instance.lastOpenedBy;

container

The outer-most containing element for the modal.

instance.container;

Running Tests

$ npm install && npm test

License

Copyright © 2016, Mark McCann. Released under the MIT license.