SimileAjax/History

From SIMILE Widgets
Jump to: navigation, search

Contents

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.

Attributes

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: SimileAjax.ListenerQueue
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 document.title
Description: History adds the label of the action to the original title. This is buggy.

Methods

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.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox