lb.base.history

History (in Local Navigation) Adapter Module for Base Library

This module provides support for local navigation, setting, getting and detecting changes in the hash, the local part of the url.

The module must be loaded in a static way, e.g. part of an external script included at the end of the <body>.  During its loading, it will initialize the history manager, which must be done before the page “load” event.  Loading this module dynamically after the page “load” may result in the page being reset to blank.

The module requires two elements to be present in the initial document, an iframe of id ‘lb.base.history.iframe’ (in Internet Explorer) and a hidden input field of id ‘lb.base.history.input’ (in all browsers, including IE).  In case these elements are not found, they will be created during the module initialization using document.write.

The two elements should be hidden.  The source of the iframe can be any resource on the same from the same domain as the document [1].  We advise to set it to the location of the favicon, which has been loaded already and will not cost another roundtrip.  The iframe is only needed in IE [2], and can be created within a conditional comment to spare its creation cost in other browsers:

<!--[if IE]>
  <iframe id="lb.base.history.iframe" src="favicon.ico" class="hidden"
  ></iframe>
<![endif]-->
<input id="lb.base.history.input" type="hidden" />

The following CSS can be used to hide the iframe (in IE)

iframe.hidden {
  position: absolute;
  top: 0;
  left: 0;
  width: 1px;
  height: 1px;
  visibility: hidden;
}

When the iframe is not present in the document, its src attribute location is set to the expected location of the favicon:

  • either configured in a link part of the page <head>:
<link rel='shortcut icon' href='favicon.ico' />
  • or by default ‘/favicon.ico’, at the root of the web site.

Warning

In case the resource referenced by the iframe src is missing, e.g. because the iframe was not present in the document and no favicon is present at the root of the web server, “Access is denied” errors may happen at random in IE when the page is refreshed and setToken() is called to set a new hash.

References

Authors

Copyright

Eric Bréchemier © 2011, Some Rights Reserved Legal-Box SAS © 2010-2011, All Rights Reserved

License

BSD License http://creativecommons.org/licenses/BSD/

Version

2011-08-14

Summary
lb.base.historyHistory (in Local Navigation) Adapter Module for Base Library
Functions
getFaviconUrl(): stringGet the expected url of the shortcut icon.
getHash(): stringGet the hash part of current url.
setHash(hash)Set a hash part in current url.
addListener(callback)Register a callback for modifications of the hash.
removeListener(callback)Unregister a callback for hash modifications.
destroy()Terminate the history manager.

Functions

getFaviconUrl(): string

Get the expected url of the shortcut icon.

Returns

  • string, the href of the first link with rel ‘shortcut icon’ (case-insensitive) found in the <head>,
  • or ‘/favicon.ico’ by default

Reference

[1] How to Add a Shortcut Icon to a Web Page http://msdn.microsoft.com/en-us/library/ms537656%28VS.85%29.aspx

getHash(): string

Get the hash part of current url.

Returns

  • string, the url-decoded value of the current hash
  • null when the history manager has been destroyed

setHash(hash)

Set a hash part in current url.

Note

The hash will be encoded in this function.

Param

hashstring, the new hash part to set, with or without the initial hash sign, e.g.  ‘new-hash’, ‘#new-hash’ or ‘#new hash’

addListener(callback)

Register a callback for modifications of the hash.

Parameter

callbackfunction, a function callback(hash), which will be called for each subsequent change of hash.  The new hash, decoded and starting with ‘#’, will be provided as parameter.

removeListener(callback)

Unregister a callback for hash modifications.

Parameter

callbackfunction, a callback previously set to addListener().

Note

Nothing happens when the callback has never been added, or has been removed already.

destroy()

Terminate the history manager.

Close