Home Manual Reference Source Repository
import History from 'backbone/src/History.js'
public class | source

History

Extends:

Events → History

Backbone.History - History serves as a global router. (http://backbonejs.org/#History)

History serves as a global router (per frame) to handle hashchange events or pushState, match the appropriate route, and trigger callbacks. You shouldn't ever have to create one of these yourself since Backbone.history already contains one.

pushState support exists on a purely opt-in basis in Backbone. Older browsers that don't support pushState will continue to use hash-based URL fragments, and if a hash URL is visited by a pushState-capable browser, it will be transparently upgraded to the true URL. Note that using real URLs requires your web server to be able to correctly render those pages, so back-end changes are required as well. For example, if you have a route of /documents/100, your web server must be able to serve that page, if the browser visits that URL directly. For full search-engine crawlability, it's best to have the server generate the complete HTML for the page ... but if it's a web application, just rendering the same content you would have for the root URL, and filling in the rest with Backbone Views and JavaScript works fine.

Handles cross-browser history management, based on either pushState and real URLs, or onhashchange and URL fragments. If the browser supports neither (old IE, natch), falls back to polling.

Constructor Summary

Public Constructor
public

Member Summary

Public Members
public

fragment: * | void | string | XML

URL fragment

public

Stores route / callback pairs for validation.

public

Browser history

public

Proxy iframe

public

The default interval to poll for hash changes, if necessary, is twenty times a second.

public

location: Location | String

Browser Location or URL string.

public

Figure out the initial configuration.

public

URL root

public

Has the history handling already been started?

Method Summary

Public Methods
public

Are we at the app root?

public

Checks the current URL to see if it has changed, and if it has, calls loadUrl, normalizing across the hidden iframe.

public

Unicode characters in location.pathname are percent encoded so they're decoded for comparison. %25 should not be decoded since it may be part of an encoded parameter.

public

getFragment(fragment: string): * | void | string | XML

Get the cross-browser normalized URL fragment from the path or hash.

public

getHash(window: object): *

Gets the true hash value.

public

getPath(): *

Get the pathname and search params, without the root.

public

In IE6, the hash fragment and search params are incorrect if the fragment contains ?.

public

loadUrl(fragment: string): boolean

Attempt to load the current URL fragment.

public

Does the pathname match the root?

public

navigate(fragment: string, options: object): *

Save a fragment into the hash history, or replace the URL state if the 'replace' option is passed.

public

route(route: string, callback: function)

Add a route to be tested when the fragment changes.

public

start(options: object): *

When all of your Routers have been created, and all of the routes are set up properly, call Backbone.history.start() to begin monitoring hashchange events, and dispatching routes.

public

stop()

Disable Backbone.history, perhaps temporarily.

Inherited Summary

From class Events
public

bind(): *

Delegates to on.

public

listenTo(obj: object, name: string, callback: function): Events

Tell an object to listen to a particular event on an other object.

public

listenToOnce(obj: object, name: string, callback: function): Events

Just like listenTo, but causes the bound callback to fire only once before being removed.

public

off(name: string, callback: function, context: object): Events

Remove a previously-bound callback function from an object.

public

on(name: string, callback: function, context: object): *

Bind a callback function to an object.

public

once(name: string, callback: function, context: object): *

Just like on, but causes the bound callback to fire only once before being removed.

public

stopListening(obj: object, name: string, callback: function): Events

Tell an object to stop listening to events.

public

Trigger callbacks for the given event, or space-delimited list of events.

public

unbind(): *

Delegates to off.

Public Constructors

public constructor source

Override:

Events#constructor

Public Members

public fragment: * | void | string | XML source

URL fragment

public handlers: Array<Object<string, function>> source

Stores route / callback pairs for validation.

public history: History source

Browser history

public iframe: Element source

Proxy iframe

public interval: number source

The default interval to poll for hash changes, if necessary, is twenty times a second.

public location: Location | String source

Browser Location or URL string.

public options: Object source

Figure out the initial configuration. Do we need an iframe?

public root: string source

URL root

public started: boolean source

Has the history handling already been started?

Public Methods

public atRoot(): boolean source

Are we at the app root?

Return:

boolean

public checkUrl(): boolean source

Checks the current URL to see if it has changed, and if it has, calls loadUrl, normalizing across the hidden iframe.

Return:

boolean

public decodeFragment(fragment: string): string source

Unicode characters in location.pathname are percent encoded so they're decoded for comparison. %25 should not be decoded since it may be part of an encoded parameter.

Params:

NameTypeAttributeDescription
fragment string

URL fragment

Return:

string

public getFragment(fragment: string): * | void | string | XML source

Get the cross-browser normalized URL fragment from the path or hash.

Params:

NameTypeAttributeDescription
fragment string
  • URL fragment

Return:

* | void | string | XML

public getHash(window: object): * source

Gets the true hash value. Cannot use location.hash directly due to bug in Firefox where location.hash will always be decoded.

Params:

NameTypeAttributeDescription
window object

Browser window

Return:

*

public getPath(): * source

Get the pathname and search params, without the root.

Return:

*

public getSearch(): string source

In IE6, the hash fragment and search params are incorrect if the fragment contains ?.

Return:

string

public loadUrl(fragment: string): boolean source

Attempt to load the current URL fragment. If a route succeeds with a match, returns true. If no defined routes matches the fragment, returns false.

Params:

NameTypeAttributeDescription
fragment string

URL fragment

Return:

boolean

public matchRoot(): boolean source

Does the pathname match the root?

Return:

boolean

public navigate(fragment: string, options: object): * source

Save a fragment into the hash history, or replace the URL state if the 'replace' option is passed. You are responsible for properly URL-encoding the fragment in advance.

The options object can contain trigger: true if you wish to have the route callback be fired (not usually desirable), or replace: true, if you wish to modify the current URL without adding an entry to the history.

Params:

NameTypeAttributeDescription
fragment string

String representing an URL fragment.

options object

Optional hash containing parameters for navigate.

Return:

*

public route(route: string, callback: function) source

Add a route to be tested when the fragment changes. Routes added later may override previous routes.

Params:

NameTypeAttributeDescription
route string

Route to add for checking.

callback function

Callback function to invoke on match.

public start(options: object): * source

When all of your Routers have been created, and all of the routes are set up properly, call Backbone.history.start() to begin monitoring hashchange events, and dispatching routes. Subsequent calls to Backbone.history.start() will throw an error, and Backbone.History.started is a boolean value indicating whether it has already been called.

To indicate that you'd like to use HTML5 pushState support in your application, use Backbone.history.start({pushState: true}). If you'd like to use pushState, but have browsers that don't support it natively use full page refreshes instead, you can add {hashChange: false} to the options.

If your application is not being served from the root url / of your domain, be sure to tell History where the root really is, as an option: Backbone.history.start({pushState: true, root: "/public/search/"})

When called, if a route succeeds with a match for the current URL, Backbone.history.start() returns true. If no defined route matches the current URL, it returns false.

If the server has already rendered the entire page, and you don't want the initial route to trigger when starting History, pass silent: true.

Because hash-based history in Internet Explorer relies on an <iframe>, be sure to call start() only after the DOM is ready.

Params:

NameTypeAttributeDescription
options object

Optional parameters

Return:

*

Example:

import WorkspaceRouter from 'WorkspaceRouter.js';
import HelpPaneRouter  from 'HelpPaneRouter.js';

new WorkspaceRouter();
new HelpPaneRouter();
Backbone.history.start({pushState: true});

public stop() source

Disable Backbone.history, perhaps temporarily. Not useful in a real app, but possibly useful for unit testing Routers.