API Docs for: 0.1.13
Show:

Stay Class

Extends EventDispatcher
Defined in: src\stay.js:23

The Stay XHR System.

Used for requesting page content asynchronously while staying on the same page.

Each request can have a hard timeout to avoid endless loading times that are often deemed to fail anyways.

Constructor

Stay

(
  • [options]
)

Defined in src\stay.js:23

Parameters:

  • [options] Object optional
    • The options.
    • [stderr=console] Array optional
      • The standard output for error messages.
    • [infix="/json"] String optional
      • The special url pattern infix for the asynchronous content requests.
    • [timeoutPost=60000] Number optional
      • Hard timeout for POST. 0 means no timeout.
    • [timeoutGet=5000] Number optional
      • Hard timeout for GET. 0 means no timeout.
    • [autoUpdate=true] Boolean optional
      • Whether Stay should automatically update the page content.

Throws:

Error:

An error is thrown if asynchronous requests are not supported.

Methods

_handleResponse

(
  • xhr
)
private

Defined in src\stay.js:700

This function acts when the xhr object changes its readyState. The response will be a JSON object or an error page. Anything else will be caught as a JSON parse exception and announced in stderr.

Parameters:

  • xhr XMLHttpRequest
    • The xhr object that fired the event.

_navigate

(
  • firingElement
)
private

Defined in src\stay.js:391

Navigates to the next target uri.

Parameters:

  • firingElement HTMLElement
    • The element on which the click event occured.

_switchPage

(
  • event
)
private

Defined in src\stay.js:316

This function is bound to all links and forms and executes the desired page navigation on left clicks.

Parameters:

  • event Event
    • The event.

_updateListeners

() private

Defined in src\stay.js:556

Binds event listeners to all links and forms. This method is combined with the cleanup and basically refreshes the navigation listeners.

_updateView

(
  • response
)
private

Defined in src\stay.js:453

Updates the containers with the new data.

Parameters:

  • response Object
    • The properties of the response object correspond with the target DOM containers.

getPathname

(
  • url
)
String private static

Defined in src\stay.js:3

Uses the native browser parsing mechanism to retrieve the pathname of a url.

Parameters:

  • url String
    • The URL to parse.

Returns:

String:

The pathname.

handleBackForward

(
  • event
)
private

Defined in src\stay.js:293

Support browser functionality "back" and "forward". Depends on the boolean variable "locked" in order to determine whether this navigation should be executed. The "backForward" flag tells the system that the next state mustn't be pushed.

Parameters:

  • event Object
    • The event.

handleResponse

(
  • event
)
private

Defined in src\stay.js:255

Triggers the internal response handler.

Parameters:

  • event Object
    • The event.

handleTimeout

() private

Defined in src\stay.js:265

Handles xhr timeouts, ignores the event object.

unbindListeners

()

Defined in src\stay.js:535

If you want to destroy Stay, you should call this method before you drop your reference to the Stay instance.

update

(
  • response
)

Defined in src\stay.js:619

Updates the view, the navigation listeners and the history state. Also emits an event to signilise that the page has been loaded.

The update function needs to be called after each navigation in order to unlock the system! This happens by default, but that behaviour can be disabled. It is then the responsibility of the programmer to call stay.update(response) with the response data provided by the "receive" event.

Parameters:

  • response Object
    • The response to display.

Properties

absolutePath

String private

Defined in src\stay.js:150

The current absolute path.

autoUpdate

Boolean

Defined in src\stay.js:110

Auto update flag.

backForward

Boolean private

Defined in src\stay.js:140

Back-forward flag.

containers

Array private

Defined in src\stay.js:171

A list of references to the response field DOM elements.

Error

Object private final static

Defined in src\stay.js:749

Enumeration of Error Messages.

exclusions

Array

Defined in src\stay.js:60

Regular expressions for excluded URIs.

historyState

Object private

Defined in src\stay.js:160

The current history state. Can't rely on history.state right now.

infix

String

Defined in src\stay.js:83

The infix to use for the asynchronous requests.

intermediateContainer

HTMLDivElement private

Defined in src\stay.js:181

A container which is filled by setting its innerHTML. The created DOM elements are taken from this container and appended to the response fields.

local

RegExp private

Defined in src\stay.js:50

Regular expression to check if a url is local.

locked

Boolean private

Defined in src\stay.js:130

Lock flag.

navigationListeners

Array private

Defined in src\stay.js:193

A list of navigation listeners for unbinding.

stderr

String

Defined in src\stay.js:69

The standard error output. This string represents the ID of the target DOM container which should hold any error messages. If none is specified, errors will be logged to the console. A request timeout is considered an error, for example.

timeoutGet

Number

Defined in src\stay.js:101

GET timeout.

timeoutPost

Number

Defined in src\stay.js:92

POST timeout.

xhr

XMLHttpRequest private

Defined in src\stay.js:229

The internal XMLHttpRequest instance.

Events

error

Defined in src\stay.js:247

Returns XmlHttpRequest errors.

load

Defined in src\stay.js:221

Signalises that a page update has finished.

navigate

Defined in src\stay.js:203

Signalises that a page navigation has started.

receive

Defined in src\stay.js:211

Returns the parsed server response.

Event Payload:

  • response Object
    • The server response, ready to be inserted into the respective response fields.
  • status Number
    • The status of the xhr response.