Class: App

App


new App()

App class that handle routes and screens lifecycle.

Extends

  • EventEmitter

Members


<protected, nullable> activePath :string

Holds the active path containing the query parameters.
Type:
  • string

<protected, nullable> activeScreen :Screen

Holds the active screen.
Type:

<protected> allowPreventNavigate :boolean

Allows prevent navigate from dom prevented event.
Type:
  • boolean
Default Value:
  • true

<protected, non-null> basePath :string

Holds link base path.
Type:
  • string
Default Value:
  • ''

<protected, non-null> captureScrollPositionFromScrollEvent :boolean

Captures scroll position from scroll event.
Type:
  • boolean
Default Value:
  • true

<protected> defaultTitle :string

Holds the default page title.
Type:
  • string
Default Value:
  • null

<protected, non-null> formSelector :string

Holds the form selector to define forms that are routed.
Type:
  • string
Default Value:
  • form[enctype="multipart/form-data"]:not([data-senna-off])

<protected, non-null> linkSelector :string

Holds the link selector to define links that are routed.
Type:
  • string
Default Value:
  • a:not([data-senna-off])

<protected, non-null> loadingCssClass :string

Holds the loading css class.
Type:
  • string
Default Value:
  • senna-loading

<protected> nativeScrollRestorationSupported :boolean

Using the History API to manage your URLs is awesome and, as it happens, a crucial feature of good web apps. One of its downsides, however, is that scroll positions are stored and then, more importantly, restored whenever you traverse the history. This often means unsightly jumps as the scroll position changes automatically, and especially so if your app does transitions, or changes the contents of the page in any way. Ultimately this leads to an horrible user experience. The good news is, however, that there’s a potential fix: history.scrollRestoration. https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration
Type:
  • boolean

<protected, nullable> pendingNavigate :CancellablePromise

Holds a deferred with the current navigation.
Type:
  • CancellablePromise
Default Value:
  • null

<protected, non-null> popstateScrollLeft :Number

Holds the window horizontal scroll position when the navigation using back or forward happens to be restored after the surfaces are updated.
Type:
  • Number
Default Value:
  • 0

<protected, non-null> popstateScrollTop :Number

Holds the window vertical scroll position when the navigation using back or forward happens to be restored after the surfaces are updated.
Type:
  • Number
Default Value:
  • 0

<protected, nullable> redirectPath :string

Holds the redirect path containing the query parameters.
Type:
  • string

<protected, nullable> routes :Array

Holds the screen routes configuration.
Type:
  • Array
Default Value:
  • []

<protected, nullable> screens :Object

Maps the screen instances by the url containing the parameters.
Type:
  • Object
Default Value:
  • {}

<protected> skipLoadPopstate :boolean

When set to true the first erroneous popstate fired on page load will be ignored, only if globals.window.history.state is also null.
Type:
  • boolean
Default Value:
  • false

<protected, nullable> surfaces :Object

Maps that index the surfaces instances by the surface id.
Type:
  • Object
Default Value:
  • {}

<protected, non-null> updateScrollPosition :boolean

When set to true, moves the scroll position after popstate, or to the top of the viewport for new navigation. If false, the browser will take care of scroll restoration.
Type:
  • boolean
Default Value:
  • true

Methods


addRoutes(or)

Adds one or more screens to the application. Example: app.addRoutes({ path: '/foo', handler: FooScreen }); or app.addRoutes([{ path: '/foo', handler: function(route) { return new FooScreen(); } }]);
Parameters:
Name Type Description
or Object {Array} routes Single object or an array of object. Each object should contain path and screen. The path should be a string or a regex that maps the navigation route to a screen class definition (not an instance), e.g: { path: "/home:param1", handler: MyScreen } { path: /foo.+/, handler: MyScreen }

addSurfaces(surfaces)

Adds one or more surfaces to the application.
Parameters:
Name Type Description
surfaces Surface | String | Array.<(Surface|String)> Surface element id or surface instance. You can also pass an Array whichcontains surface instances or id. In case of ID, these should be the id of surface element.

canNavigate(url)

Returns if can navigate to path.
Parameters:
Name Type Description
url string
Returns:
Type
boolean

clearScreensCache()

Clear screens cache.

createScreenInstance(path)

Retrieves or create a screen instance to a path.
Parameters:
Name Type Description
path string Path containing the querystring part.
Returns:
Type
Screen

dispatch()

Dispatches to the first route handler that matches the current path, if any.
Returns:
Returns a pending request cancellable promise.
Type
CancellablePromise

disposeInternal()


doNavigate_(path [, opt_replaceHistory])

Starts navigation to a path.
Parameters:
Name Type Argument Description
path string Path containing the querystring part.
opt_replaceHistory boolean <optional>
Replaces browser history.
Returns:
Returns a pending request cancellable promise.
Type
CancellablePromise

<protected> finalizeNavigate_(path, nextScreen)

Finalizes a screen navigation.
Parameters:
Name Type Description
path string Path containing the querystring part.
nextScreen Screen

findRoute(path)

Finds a route for the test path. Returns true if matches has a route, otherwise returns null.
Parameters:
Name Type Description
path string Path containing the querystring part.
Returns:
Route handler if match any or null if the path is the same as the current url and the path contains a fragment.
Type
Object

getAllowPreventNavigate()

Gets allow prevent navigate.
Returns:
Type
boolean

getBasePath()

Gets link base path.
Returns:
Type
string

getDefaultTitle()

Gets the default page title.
Returns:
defaultTitle
Type
string

getFormSelector()

Gets the form selector.
Returns:
Type
string

getLinkSelector()

Gets the link selector.
Returns:
Type
string

getLoadingCssClass()

Gets the loading css class.
Returns:
Type
string

getUpdateScrollPosition()

Gets the update scroll position value.
Returns:
Type
boolean

<protected> handleNavigateError_(path, nextScreen, error)

Handle navigation error.
Parameters:
Name Type Description
path string Path containing the querystring part.
nextScreen Screen
error Error

hasRoutes()

Checks if app has routes.
Returns:
Type
boolean

<protected> isLinkSameOrigin_(hostname)

Tests if hostname is an offsite link.
Parameters:
Name Type Description
hostname string Link hostname to compare with globals.window.location.hostname.
Returns:
Type
boolean

<protected> isSameBasePath_(path)

Tests if link element has the same app's base path.
Parameters:
Name Type Description
path string Link path containing the querystring part.
Returns:
Type
boolean

<protected> lockHistoryScrollPosition_()

Lock the document scroll in order to avoid the browser native back and forward navigation to change the scroll position. In the end of navigation lifecycle scroll is repositioned.

maybeDisableNativeScrollRestoration()

If supported by the browser, disables native scroll restoration and stores current value.

maybeNavigate_(href, event)

Maybe navigate to a path.
Parameters:
Name Type Description
href string Information about the link's href.
event Event Dom event that initiated the navigation.

maybeRepositionScrollToHashedAnchor()

Maybe reposition scroll to hashed anchor.

maybeRestoreNativeScrollRestoration()

If supported by the browser, restores native scroll restoration to the value captured by `maybeDisableNativeScrollRestoration`.

Navigates to the specified path if there is a route handler that matches.
Parameters:
Name Type Argument Description
path string Path to navigate containing the base path.
opt_replaceHistory boolean <optional>
Replaces browser history.
Returns:
Returns a pending request cancellable promise.
Type
CancellablePromise

<protected> onBeforeNavigate_(event)

Befores navigation to a path.
Parameters:
Name Type Description
event Event Event facade containing path and replaceHistory.

<protected> onBeforeNavigateDefault_(event)

Befores navigation to a path. Runs after external listeners.
Parameters:
Name Type Description
event Event Event facade containing path and replaceHistory.

<protected> onDocClickDelegate_(event)

Intercepts document clicks and test link elements in order to decide whether Surface app can navigate.
Parameters:
Name Type Description
event Event Event facade

<protected> onDocSubmitDelegate_(event)

Intercepts document form submits and test action path in order to decide whether Surface app can navigate.
Parameters:
Name Type Description
event Event Event facade

<protected> onLoad_()

Listens to the window's load event in order to avoid issues with some browsers that trigger popstate calls on the first load. For more information see http://stackoverflow.com/questions/6421769/popstate-on-pages-load-in-chrome.

<protected> onPopstate_(event)

Handles browser history changes and fires app's navigation if the state belows to us. If we detect a popstate and the state is null, assume it is navigating to an external page or to a page we don't have route, then globals.window.location.reload() is invoked in order to reload the content to the current url.
Parameters:
Name Type Description
event Event Event facade

<protected> onScroll_()

Listens document scroll changes in order to capture the possible lock scroll position for history scrolling.

<protected> onStartNavigate_(event)

Starts navigation to a path.
Parameters:
Name Type Description
event Event Event facade containing path and replaceHistory.

prefetch(path)

Prefetches the specified path if there is a route handler that matches.
Parameters:
Name Type Description
path string Path to navigate containing the base path.
Returns:
Returns a pending request cancellable promise.
Type
CancellablePromise

prepareNavigateHistory_(path, nextScreen [, opt_replaceHistory])

Prepares screen flip. Updates history state and surfaces content.
Parameters:
Name Type Argument Description
path string Path containing the querystring part.
nextScreen Screen
opt_replaceHistory boolean <optional>
Replaces browser history.

prepareNavigateSurfaces_(nextScreen, surfaces)

Prepares screen flip. Updates history state and surfaces content.
Parameters:
Name Type Description
nextScreen Screen
surfaces object Map of surfaces to flip keyed by surface id.

reloadPage()

Reloads the page by performing `window.location.reload()`.

removeRoute(route)

Removes route instance from app routes.
Parameters:
Name Type Description
route Route
Returns:
True if an element was removed.
Type
boolean

removeScreen(path)

Removes a screen.
Parameters:
Name Type Description
path string Path containing the querystring part.

saveHistoryCurrentPageScrollPosition_()

Saves scroll position from page offset into history state.

setAllowPreventNavigate(allowPreventNavigate)

Sets allow prevent navigate.
Parameters:
Name Type Description
allowPreventNavigate boolean

setBasePath(path)

Sets link base path.
Parameters:
Name Type Description
path string

setDefaultTitle(defaultTitle)

Sets the default page title.
Parameters:
Name Type Description
defaultTitle string

setFormSelector(formSelector)

Sets the form selector.
Parameters:
Name Type Description
formSelector string

setLinkSelector(linkSelector)

Sets the link selector.
Parameters:
Name Type Description
linkSelector string

setLoadingCssClass(loadingCssClass)

Sets the loading css class.
Parameters:
Name Type Description
loadingCssClass string

setUpdateScrollPosition(updateScrollPosition)

Sets the update scroll position value.
Parameters:
Name Type Description
updateScrollPosition boolean

<protected> stopPendingNavigate_()

Cancels pending navigate with Cancel pending navigation error.

<protected> syncScrollPositionSyncThenAsync_()

Sync document scroll position twice, the first one synchronous and then one inside async.nextTick. Relevant to browsers that fires scroll restoration asynchronously after popstate.
Returns:
Type
CancellablePromise

<protected> updateHistory_(title, path, state [, opt_replaceHistory])

Updates or replace browser history.
Parameters:
Name Type Argument Description
title string <nullable>
Document title.
path string Path containing the querystring part.
state object
opt_replaceHistory boolean <optional>
Replaces browser history.