Documentation Class: 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:

Screen

<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:

<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:

<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`.

navigate(path [, opt_replaceHistory])

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.