I'm looking for maintainer(s) of this lib. If you're interested, let me know! I'd be happy to help you get set up ✌️
Backbone.Intercept
Backbone.Intercept intelligently manages link clicks and form submissions within Backbone applications.
About
The default action of form submissions and link clicks is often undesirable in Backbone applications. One would usually rather prevent that default behavior, then handle those through Backbone.history and possibly also in a Router's callback. Backbone doesn't do any of this for you, but Backbone.Intercept does.
If you're writing e.preventDefault()
in many of your view's event callbacks – or otherwise handling this problem on a per-view
basis – then Backbone.Intercept might be what you're looking for.
// before Backbone.Interceptvar MyView = BackboneView; // after Backbone.Interceptvar MyView = BackboneView;
Installation
Install through bower
or npm
.
bower install backboneinterceptnpm install backboneintercept
Dependencies
Backbone.Intercept depends on Underscore, Backbone and a jQuery-like API on the Backbone.$
object.
Table of Contents
Getting Started
Getting started is easy. Simply call Backbone.Intercept.start()
when your application is started up. If
you're using Marionette, this might look something like
app;
Links
Default Behavior
In general, links with relative URIs will be intercepted, whereas absolute URIs will be ignored by Backbone.Intercept. A few examples will best illustrate the default behavior of Intercept.
// The following URIs will be intercepted'path/to/my-page';'/absolute/path/to/my-page';'www.my-website.com'; // The following URIs will be ignored by Backbone.Intercept and handled like normal'http://www.my-site.com';'#my-page-fragment';'mailto:stacy@email.com';'javascript:void';
Navigation
By default your intercepted links will be sent along to Backbone.history.navigate
to be processed. You can customize this
by overriding the navigate
method on Backbone.Intercept. By doing this you could make Intercept work with a Router instead,
or integrate other libraries like Backbone.Radio.
// Create a Routervar myRouter = ; // Attach it to InterceptBackboneIntercept { myRouter;}; // Or use a Backbone.Radio ChannelBackboneIntercept { var routerChannel = BackboneRadio; routerChannel;};
If you don't want anything to happen when you click links you can specify the navigate
function as a falsey value,
or an empty function.
// This won't cause any navigation to occur when links are clickedBackboneInterceptnavigate = undefined;
Customizing the Behavior Per-Link
This behavior can be changed by setting custom attributes on the element.
<!-- Force this link to be ignored by Backbone.Intercept --> <!-- If you want to follow the HTML5 spec, then this version works, too --> <!-- You can also be explicit, though this isn't necessary --> <!-- If you've specified a navigateWith property, you can specify the trigger as an attribute --> <!-- There's an HTML5-compliant version for that as well -->
Setting Global Link Trigger Behavior
You can set the default trigger behavior by specifying it directly on the Backbone.Intercept defaults
option.
// Let's set the trigger setting to false by defaultBackboneInterceptdefaultstrigger = false;
Forms
Forms are much simpler than links. All forms are intercepted unless the action
attribute has been specified. And unlike links, there's
no integration of forms with a Router.
<!-- This form will be intercepted --> <!-- But this one will not -->
Setting the Root Element of Backbone.Intercept
Backbone.Intercept will intercept links and forms on the body
on the page, but this can be customized by setting the
rootSelector
property.
BackboneInterceptrootSelector = '.backbone-app';
This is useful for webapps where Backbone might not be the only library running on the page.
When Not To Use Backbone.Intercept
Backbone.Intercept works best in an application that is entirely controlled by Backbone. Of course, not every project is like this. It's not uncommon for there to be Backbone components on a page that is otherwise not Backbone. In those situations it is likely a better choice to manage link clicks and form submissions on a per-view basis.
This library is only meant to act as a proxy between the DOM and your JS, and nothing more, if you want to be able to cancel routes, this library won't help you with that, you'd need to handle that in your router.
API
Properties
VERSION
The version of Backbone.Intercept.
rootSelector
A query selector for the root element of Intercept. Defaults to 'body'
.
defaults
An object for the default values for the router. There are three properties in defaults, links
, forms
, and trigger
,
and all three are true
out-of-the-box. The first two options determine if Intercept handles links and forms, respectively. The
trigger
option determines if intercepted links pass trigger:true
by default.
The value of the trigger
or data-trigger
attribute on the anchor tag itself will always trump the value of the
value of trigger
in the defaults
hash.
Methods
start( [options] )
Starts Backbone.Intercept. You can pass options
as an argument to override the defaults
property.
// In this app we will only intercept formsBackboneInterceptstart links: false; // And in this one only linksBackboneInterceptstart forms: false;
stop()
Stop intercepting links and forms.
navigate( uri, options )
default: Backbone.history.navigate
A method that's called when links are intercepted. By default it just forwards it along to Backbone.history.navigate
, but you
can specify a custom method to do whatever you'd like.
The uri is the value of the link's href
attribute. options
are the navigation options, which is just an object
with a trigger
property.