History
Extends:
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 |
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 |
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 |
|
public |
decodeFragment(fragment: string): string Unicode characters in |
|
public |
getFragment(fragment: string): * | void | string | XML Get the cross-browser normalized URL fragment from the path or hash. |
|
public |
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 |
Attempt to load the current URL fragment. |
|
public |
Does the pathname match the root? |
|
public |
Save a fragment into the hash history, or replace the URL state if the 'replace' option is passed. |
|
public |
Add a route to be tested when the fragment changes. |
|
public |
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 |
|
public |
Tell an object to listen to a particular event on an other object. |
|
public |
listenToOnce(obj: object, name: string, callback: function): Events Just like |
|
public |
Remove a previously-bound callback function from an object. |
|
public |
Bind a callback function to an object. |
|
public |
Just like |
|
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 |
Public Constructors
Public Members
public handlers: Array<Object<string, function>> source
Stores route / callback pairs for validation.
Public Methods
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.
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:
Name | Type | Attribute | Description |
fragment | string | URL fragment |
public getFragment(fragment: string): * | void | string | XML source
Get the cross-browser normalized URL fragment from the path or hash.
Params:
Name | Type | Attribute | Description |
fragment | string |
|
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:
Name | Type | Attribute | Description |
window | object | Browser |
Return:
* |
public getSearch(): string source
In IE6, the hash fragment and search params are incorrect if the fragment contains ?
.
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:
Name | Type | Attribute | Description |
fragment | string | URL fragment |
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.
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.
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:
Name | Type | Attribute | Description |
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.