Class: App

(protected) jrt.App(versionopt, historyEnabledopt)

Base class for a single-page web application. This class is instantiated as a singleton by jrt.Runtime.

This class also represents the BODY element as an instance of jrt.Block.

An app contains "pages" an "dialogs". Pages represent the app's main screens or states, and are implemented with a SECTION element paired with an instance of jrt.Page. Dialogs are implemented with a DIALOG element and an instance of jrt.Dialog.

Pages and dialogs are generically called "views" (see jrt.TargetView). An app can also define actions with jrt.Action. Views and actions are generically called "targets" (see jrt.Target). Each target has a unique id, and the method getClassNameForTargetId must be implemented to pair a target id with the class that implements it.

Any target can be invoked from HTML by using a "hash URL" (see jrt.HashUrl). A target can also be requested by calling navigateTo, navigateBack, execute, openDialog or jrt.Dialog#open.

Constructor

(protected) new App(versionopt, historyEnabledopt)

Parameters:
Name Type Attributes Default Description
version string <optional>

The app's version string.
historyEnabled boolean <optional>
 false

Pass true to enable the browser's page URL history.

Extends

Members

(protected, constant, non-null) app :jrt.App

Reference to the app instance, just for convenience.

Type:
Overrides:

(non-null) currentPage :jrt.Page

The currently active page.

Type:

(non-null) currentView :jrt.TargetView

The currently active view. It can be the currently open modal dialog (if it's not a system dialog box) or the current page.

Type:

currentView

(constant, non-null) element :HTMLElement

The HTML element represented by this instance.

Type:
  • HTMLElement
Overrides:

mainPageId :string

Id of the app's main page. It defaults to the first page found in the HTML source. For an installed app, if the main page is showing and the app goes back (either with the #back URL or with navigateBack), then the app will be closed.

Type:
  • string

(constant) version :string

The app's version string, as specified in the constructor ("" by default).

Type:
  • string

Methods

(static) getInstance() → (non-null) {jrt.App}

Returns:

Returns the app instance.

Type
jrt.App

(protected) actionFinished(actionnon-null)

This is called immediately after jrt.Target#actionFinished when an action is finished explicitly with jrt.Action#finish. This base implementation does nothing.

Parameters:
Name Type Description
action jrt.Action

clearViewCache(idopt)

Removes one view or all views from the view cache.

Parameters:
Name Type Attributes Description
id string <optional>

closed()

Called when the app is unloaded (or reloaded, if running as a web app). This base implementation does nothing.

Quirk: Note that when using Cordova on Android, the paused method will be called when the app exits and this method will not be called at all (because the "unload" event is not triggered).

dialogClosed(dialognon-null)

This is called immediately after jrt.Target#dialogClosed when a dialog is closed. This base implementation does nothing.

Parameters:
Name Type Description
dialog jrt.Modal

(protected) dialogRequested(reqnon-null)

This is called immediately before jrt.Target#requested when a dialog is requested. This base implementation does nothing.

Parameters:
Name Type Description
req jrt.AppRequest

endWait()

Puts the app in the ready state and removes the "wait" class from the BODY element.

error(errnon-null)

This is called when an uncaught error is thrown in client code.

Parameters:
Name Type Description
err Error

execute(actionId, paramsopt, nullable)

Starts the specified action. The resulting target request has the "call" type. The current target becomes the action's caller and it will be notified when the action is finished explicitly with jrt.Action#finish.

Parameters:
Name Type Attributes Description
actionId string

The target action id.
params Object.<!jrt.FormValue> <optional>
<nullable>

Request parameters for the target action.
Throws:

If the action is not defined or the current state precludes the operation.

Type
jrt.JrtError

getAction(id) → (non-null) {jrt.Action}

Returns a new action object for the specified id. Action targets are created when executed and are discarded when their execution finishes.

Parameters:
Name Type Description
id string

The action id.
Throws:

If an action class does not exist for the specified id.

Type
jrt.JrtError
Returns:
Type
jrt.Action

(protected) getClassNameForTargetId(id) → (nullable) {string}

Returns the fully qualified name of the class that implements the target for the specified id, if defined. The returned string will be evaluated with 'eval' in order to get the actual class. Note that all actions must define a class, but pages and dialogs are not required to.

The default implementation simply returns the specified id. This will only work if your target classes are defined as global variables with the same name as the id.

Parameters:
Name Type Description
id string
Returns:
Type
string

getDialog(id) → (non-null) {jrt.Dialog}

Returns the dialog object for the specified id. A view cache is maintained, so dialogs are only created once (subsequent calls to this method return the cached instance).

Parameters:
Name Type Description
id string

The id of the DIALOG element.
Throws:

If a dialog element or class does not exist for the specified id.

Type
jrt.JrtError
Returns:
Type
jrt.Dialog

getLocale() → (nullable) {jrt.LocaleBundle}

Returns the last locale object set with jrt.LocaleBundle.setBundle.

Returns:
Type
jrt.LocaleBundle

getPage(id) → (non-null) {jrt.Page}

Returns the page object for the specified id. A view cache is maintained, so pages are only created once (subsequent calls to this method return the cached instance).

Parameters:
Name Type Description
id string

The id of the page element (a SECTION element).
Throws:

If a page element or class does not exist for the specified id.

Type
jrt.JrtError
Returns:
Type
jrt.Page

(protected) handleEvent(enon-null, labelnullable)

This method is called when an event registered with listenToEvent is triggered.

Parameters:
Name Type Attributes Description
e Event

The event object.
label string <nullable>

The label specified when registering the event.
Overrides:

(protected) ignoreEvent(eventType, elementopt, nullable)

Stops listenig to the specified event type on the specified element.

Parameters:
Name Type Attributes Description
eventType string

The event type to listen to.
element Element <optional>
<nullable>

The HTML element to stop listening to. Defaults to this element.
Overrides:

(protected) listenToEvent(eventType, elementopt, nullable, labelopt, nullable, useCaptureopt)

Sets this object as the event listener for the specified event type and element. The handleEvent method is called when the event occurs.

Parameters:
Name Type Attributes Description
eventType string

The event type to listen to.
element Element <optional>
<nullable>

The HTML element to listen to. Defaults to this element.
label string <optional>
<nullable>

Optional label passed to the event handler.
useCapture boolean <optional>
Overrides:

If a dialog is open, this method simply closes the dialog without setting its return value. Otherwise, it navigates back to the parent page, if defined by jrt.Page#getParentId. If no parent page is defined, then this method navigates to the previous page in the browser history or, if browser history is not enabled, to the main page (that defined by mainPageId).

For an installed app, if the current page is the main page, then this method will exit the application.

Navigate to the specified page with the given paramenters using the given method. The special request method "replace" can be used to make this page replace the current page in the browser's history.

Parameters:
Name Type Attributes Description
pageId string

The page id (without a leading "#").
params Object.<!jrt.FormValue> <optional>
<nullable>

Request parameters for the target page.
method string <optional>

Either "get" or "post" ("get" by default).
Throws:

If the page id is invalid, the app is waiting, or there is an error in client code.

Type
jrt.JrtError

openDialog(dialogId, paramsopt, nullable)

Opens the specified dialog. This method is equivalent to jrt.Dialog#open.

Parameters:
Name Type Attributes Description
dialogId string

The target dialog's id.
params Object.<!jrt.FormValue> <optional>
<nullable>

Request parameters for the dialog.
Throws:

If the dialog is not defined or the current state precludes the operation.

Type
jrt.JrtError

(protected) pageRequested(reqnon-null)

This is called immediately before jrt.Target#requested when a page is requested from a different page. This base implementation does nothing.

Parameters:
Name Type Description
req jrt.AppRequest

paused()

Called when system puts the app in the background (this is for installed apps only). This base implementation does nothing.

(protected) processResponse(reqnon-null, status, responsenullable)

Implement this method to process the response received after a call to sendRequest. The response data type depends on the responseType property specified in the request.

The response status can be "success", "server-error", "type-error" (when the specified response type does not match the received data), "error" (if there is a connection error), "timeout" or "offline". Note that the "offline" status is not reliable in all devices, so an "error" status may be received when offline.

The default implementation does nothing.

Parameters:
Name Type Attributes Description
req jrt.AjaxRequest

The request object.
status string

The response status (see method description).
response jrt.AjaxResponse <nullable>

The server response. This will be null on error or timeout.
Overrides:

query(selector, baseElement) → (nullable) {HTMLElement}

Returns the first element that matches the specified selector. If no base element is specified, this block is used as base element. Returns null if no element is found.

Parameters:
Name Type Description
selector string

The CSS selector.
baseElement HTMLElement | DocumentFragment

Optional base element.
Overrides:
Returns:
Type
HTMLElement

queryAll(selector, baseElement) → (non-null) {NodeList.<!HTMLElement>}

Returns all elements that match the specified selector. If no base element is specified, this element is used.

Parameters:
Name Type Description
selector string

The CSS selector.
baseElement HTMLElement | DocumentFragment

Optional base element.
Overrides:
Returns:
Type
NodeList.<!HTMLElement>

resumed()

Called when the system restores the app back to the foreground (this is for installed apps only). This base implementation does nothing.

(protected) sendRequest(reqnon-null)

Sends an asynchronous AJAX request to the URL specified in req'. The supported methods are "GET" (the default), "POST", "PUT", "PATCH", "DELETE" and "HEAD". The response will be passed to processResponse. The expected response type can be specified with the responseType property in the specified request ("json" by default).

Parameters:
Name Type Description
req jrt.AjaxRequest
Overrides:
Throws:

If any of the request parameters is invalid.

Type
Error

wait()

Puts the app in the wait state and adds the "wait" class to the BODY element (this class can be used to disable the UI through CSS).