backbone.modal.js

Awkward

A plugin for Backbone.js that simplifies creating modals for your application.

Backbone.Modal.js removes boilerplate code and adds default behaviors and interactions. You can create a simple dialog modal or complex wizards with stacked modals on top of each other in a few lines of code.

Getting Started

Backbone.modal.js is built on top of Backbone.js. Make sure you include everything that's needed for Backbone and add Backbone.Modal.js and the CSS files to start playing with it. You can also start out with the examples.

If you'd like to create a stacked modal (multiple modals on top of each other), you'll need to use Backbone.Marionette.js and Backbone.Marionette.Modals.js.

Backbone.Modal

Options can be added when extending from Backbone.Modal like: prefix (for classnames), animate and keyControl (disable enter/esc events).

views modal.views

You can bind your views by adding an event handler, just like you would define events in a Backbone.View. You can add additional options to pass along: view (as Backbone.View or template which is required), viewOptions (for specific options for that view). By using the onActive callback, you can see whenever a view is active.

views.length modal.views.length

Get the amount of views in a modal.

template modal.template

You don't need the views to create a modal, you can simply use a template if you just want to show one view. But if you want to create a complex modal, you can combine the template and views, but you'll have to define a viewContainer.

viewContainer modal.viewContainer

All views will be rendered within the viewContainer. Select a container from your template by doing: viewContainer: '.container'

submitEl modal.submitEl

You can define an element that will trigger all submit events. This will result in calling beforeSubmit, submit and closing the modal.

cancelEl modal.cancelEl

Similar to submitEl you can define an element that will cancel the modal. This will result in calling beforeCancel, cancel and closing the modal.

openAt modal.openAt([index])

Open the modal at a specific index from views.

next modal.next()

Open the next view from views. Useful when creating a wizard like modal.

previous modal.previous()

Similar to next(), but will open the previous view from views.

onRender modal.onRender() (callback)

Useful when you want to do some custom work while it's rendering the modal.

onShow modal.onShow()

Triggered whenever the animation has ended and the modal is displayed.

beforeCancel modal.beforeCancel() (callback)

This will be called when the user hits ESC, clicking on the cancelEl or clicking outside the modal and before cancel is called. It expects true or false.

cancel modal.cancel()

This method is called when the user canceled the modal.

beforeSubmit modal.beforeSubmit() (callback)

This will be called when the user hits ENTER or clicking on the submitEl. It expects true or false, so you can do any validation for example.

submit modal.submit() (callback)

This method is called when the user submitted the modal.

currentIndex modal.currentIndex

Returns the index of the current view that is visible.

destroy modal.destroy()

Call this method to remove all events listerners, modal and internal views.

onDestroy modal.onDestroy() (callback)

This method is called when the modal view is destroyed.

Backbone.Marionette.Modals

When you're using Marionette, you can set a Marionette.Region class as modal region: Backbone.Marionette.Modals. When showing views in this region, it will behave like you would expect. Adding multiple modals, will result in stacked modals. You can close them individually, or all at once.

show modals.show(modal)

Like you'd expect from a region, to render a view. When you already have a modal in there, it will animate differently and stack the modal.

destroy modals.destroy()

This will destroy the last modal you have in the region.

destroyAll modals.destroyAll()

Useful when you want to destroy all modals at once in this region.

zIndex modals.zIndex

This will let you know how many modals are stacked.

Examples

Single view/template
Tab based
Stacked modal with Marionette
Wizard

Changelog

1.1.0

1.0.0

Tweet