# backbone.intercept

> Automatically manage link clicks and form submissions within Backbone applications.

Latest version **0.4.4** (published 2017-04-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install backbone.intercept
pnpm add backbone.intercept
yarn add backbone.intercept
bun add backbone.intercept
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.4 |
| Published | 2017-04-03 |
| First published | 2014-09-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 44 |
| Author | Jmeas |
| Maintainers | jmeas |
| Keywords | backbone, marionette, link, links, click, router, route, routes, history, anchor, intercept, forms, submit, interception, SPA |

## Links

- npm: https://www.npmjs.com/package/backbone.intercept
- Repository: https://github.com/jmeas/backbone.intercept
- Issues: https://github.com/jmeas/backbone.intercept/issues
- npm.io page: https://npm.io/package/backbone.intercept

## Dependencies (2)

- [backbone](https://npm.io/package/backbone.md) >=0.9.9 <=1.3.3
- [underscore](https://npm.io/package/underscore.md) >=1.3.3 <=1.8.3

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 0.4.4 (latest) — 2017-04-03
- 0.4.3 — 2016-04-17
- 0.4.2 — 2015-11-20
- 0.4.1 — 2015-11-20
- 0.4.0 — 2015-08-15
- 0.3.3 — 2015-05-15
- 0.3.2 — 2015-01-26
- 0.3.1 — 2014-11-05
- 0.3.0 — 2014-09-22
- 0.2.0 — 2014-09-18
- 0.1.1 — 2014-09-17

## README

> I'm looking for maintainer(s) of this lib. If you're interested, [let me know](https://twitter.com/jmeaspls)! I'd be happy to help you get set up :v:

# Backbone.Intercept

[![Travis Build Status](http://img.shields.io/travis/jmeas/backbone.intercept.svg?style=flat)](https://travis-ci.org/jmeas/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.

```js
// before Backbone.Intercept
var MyView = Backbone.View.extend({
  events: {
    'click a': 'onClick',
    'submit form': 'onSubmit'
  },

  onClick: function(e) {
    e.preventDefault();
    myRouter.navigate($(e.currentTarget).attr('href'));
  },

  onSubmit: function(e) {
    e.preventDefault();
    // form submit logic
  }
});

// after Backbone.Intercept
var MyView = Backbone.View.extend({
  events: {
    'submit form': 'onSubmit'
  },

  onSubmit: function(e) {
    // form submit logic
  }
});
```

## Installation

Install through `bower` or `npm`.

```js
bower install backbone.intercept
npm install backbone.intercept
```

#### Dependencies

Backbone.Intercept depends on Underscore, Backbone and a jQuery-like API on the `Backbone.$` object.

### Table of Contents

- [Getting Started](#getting-started)
  - [Links](#links)
    - [Default Behavior](#default-behavior)
    - [Navigation](#navigation)
    - [Customizing the Behavior Per-Link](#customizing-the-behavior-per-link)
    - [Setting Global Link Trigger Behavior](#setting-global-link-trigger-behavior)
  - [Forms](#forms)
  - [Setting the Root Element of Backbone.Intercept](#setting-the-root-element-of-backboneintercept)
  - [When Not to Use Backbone.Intercept](#when-not-to-use-backboneintercept)
- [API](#api)
  - [Properties](#properties)
    - [`VERSION`](#version)
    - [`rootSelector`](#rootselector)
    - [`defaults`](#defaults)
  - [Methods](#methods)
    - [`start()`](#start-options-)
    - [`stop()`](#stop)
    - [`navigate()`](#navigate-uri-options-)

## 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

```js
app.on('start', Backbone.Intercept.start);
```

### 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.

```js
// 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](https://github.com/marionettejs/backbone.radio).

```js
// Create a Router
var myRouter = new Backbone.Router();

// Attach it to Intercept
Backbone.Intercept.navigate = function(uri, options) {
  myRouter.navigate(uri, options);
};

// Or use a Backbone.Radio Channel
Backbone.Intercept.navigate = function(uri, options) {
  var routerChannel = Backbone.Radio.channel('router');
  routerChannel.command('navigate', uri, options);
};
```

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.

```js
// This won't cause any navigation to occur when links are clicked
Backbone.Intercept.navigate = undefined;
```

#### Customizing the Behavior Per-Link

This behavior can be changed by setting custom attributes on the element.

```html
<!-- Force this link to be ignored by Backbone.Intercept -->
<a href='path/to/my-document.pdf' bypass></a>

<!-- If you want to follow the HTML5 spec, then this version works, too -->
<a href='path/to/my-document.pdf' data-bypass></a>

<!-- You can also be explicit, though this isn't necessary -->
<a href='path/to/my-document.pdf' bypass='true'></a>

<!-- If you've specified a navigateWith property, you can specify the trigger as an attribute -->
<a href='path/to/my-document.pdf' trigger='false'></a>

<!-- There's an HTML5-compliant version for that as well -->
<a href='path/to/my-document.pdf' data-trigger='false'></a>
```

#### Setting Global Link Trigger Behavior

You can set the default trigger behavior by specifying it directly on the Backbone.Intercept `defaults` option.

```js
// Let's set the trigger setting to false by default
Backbone.Intercept.defaults.trigger = 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.

```html
<!-- This form will be intercepted -->
<form></form>

<!-- But this one will not -->
<form action='post'></form>
```

### 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.

```js
Backbone.Intercept.rootSelector = '.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.

```js
// In this app we will only intercept forms
Backbone.Intercept.start({
  links: false
});

// And in this one only links
Backbone.Intercept.start({
  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.

---
_Source: https://npm.io/package/backbone.intercept · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._