SimileAjax/History

= SimileAjax.History =

A set of methods for tracking in-page actions so the back and forward browser buttons will work, undoing or redoing accordingly. The history activity uses an iframe element and looks for a blank __history__.html in a neighboring location to incorporate itself into browser history.

Code: http://api.simile-widgets.org/ajax/2.2.1/scripts/history.js

Migration Notes
Something like this is definitely necessary, though a history that can also give out a bookmark is much preferred to the current implementation. This may come with.

Back to SimileAjax.

Classes
There is an implicit contract for actions. The developer should also know when to call addAction vs. addLengthyAction.

Implicit Action Class
These methods and attributes are required on the action object passed in to either add method.

label
A short, user-friendly string describing the action.

uiLayer
The UI layer on which the action takes place.

perform
An argument-less function that carries out the action.

undo
An argument-less function that undoes the action.

Events
The following are events fired using the history system's ListenerQueue:

onBeforePerform
Called in addAction before an action's perform method is called.

onAfterPerform
Called in addAction after an action's perform method is called.

onBeforeUndoSeveral
Called in _handleIFrameOnLoad before several undo steps are called.

onAfterUndoSeveral
Called in _handleIFrameOnLoad after several undo steps are called.

onBeforeRedoSeveral
Called in _handleIFrameOnLoad before several perform steps are called.

onAfterRedoSeveral
Called in _handleIFrameOnLoad after several perform steps are called.

SimileAjax.History.maxHistoryLength

 * Type: int
 * Default: 10
 * Description: Maximum amount of actions to retain in the history.

SimileAjax.History.historyFile

 * Type: string
 * Default: "__history__.html"
 * Description: Relative location of the URL to use in an iframe; generally should be an empty but existent file.

SimileAjax.History.enabled

 * Type: boolean
 * Default: true
 * Description: Whether or not history tracking is on.

SimileAjax.History._initialized

 * Type: boolean
 * Default: false
 * Description: Internal flag to track subsystem setup.

SimileAjax.History._listeners

 * Type:
 * Default: new instance of type
 * Description: Holds listeners for history events: onBeforeUndoSeveral, onAfterUndoSeveral, onBeforeRedoSeveral, onAfterRedoSeveral, onBeforePerform, onAfterPerform

SimileAjax.History._actions

 * Type: Array
 * Default:
 * Description: List of actions.

SimileAjax.History._baseIndex

 * Type: int
 * Default: 0
 * Description: Earliest retained action; changes as action history exceeds maximum.

SimileAjax.History._currentIndex

 * Type: int
 * Default: 0
 * Description: Last executed action, which may not be equal to latest action depending on undo and redo level.

SimileAjax.History._plainDocumentTitle

 * Type: string
 * Default: The original value of
 * Description: History adds the label of the action to the original title. This is buggy.

SimileAjax.History.formatHistoryEntryTitle

 * Arguments:
 * actionLabel: string, Action description
 * Returns: string
 * Description: Changes the document title by appending the action description

SimileAjax.History.initialize

 * Arguments: None
 * Returns: Nothing
 * Description: Sets up an iframe element and event handlers for history tracking

SimileAjax.History.addListener

 * Arguments:
 * listener: Implicit Listener class
 * Returns: Nothing
 * Description: Interface for interacting with private ListenerQueue

SimileAjax.History.removeListener

 * Arguments:
 * listener: Listener
 * Returns: Nothing
 * Description: Interface for interacting with private ListenerQueue

SimileAjax.History.addAction

 * Arguments:
 * action: Action
 * Returns: Nothing
 * Description: Handles executing the action's perform method and internal system maintenance to store and track its execution.

SimileAjax.History.addLengthyAction

 * Arguments:
 * perform: Method, what the action does
 * undo: Method, how to undo the action
 * label: string, describes the action
 * Returns: Nothing
 * Description: Creates an Action with the additional designation that it's lengthy before passing it on to addAction.

SimileAjax.History.getNextUndoAction

 * Arguments: None
 * Returns: Action or null
 * Description: Provides the previous action with its undo method, or null if not available

SimileAjax.History.getNextRedoAction

 * Arguments: None
 * Returns: Action or null
 * Description: Provides the next action with its perform method, or null if not available

SimileAjax.History._handleIFrameOnLoad

 * Arguments: None
 * Returns: Nothing
 *  Description: This function is invoked when the user herself navigates backward or forward. We need to adjust the application's state accordingly.

Back to SimileAjax.