# App/Page Lifecycle

Quick app engines separates the view layer, responsible of rendering the content, and the logic layer, that performs the business logic of the app. The view layer renders the pages and its components using an hybrid approach (using both native and web elements). The logic layer or scripting layer, deals with events, API interaction, and lifecycle management.

The quick app lifecycle enable developers to manage both, the view and logic layers through the global app lifecycle events and the specific individual page lifecycle events.

# App Lifecycle Events

A quick app implements the following event handlers that control the global behavior of the app.

onCreate
onRequest
onShow
onHide
onError
onPageNotFound

# `onCreate`

Event triggered when the app is created.

Return: -

# `onRequest`

Event triggered when the app is started.

Return: -

# `onShow`

Event triggered when the app is app is displayed.

Return: -

# `onHide`

Event triggered when the app is hidden.

Return: -

# `onError`

Event triggered when the an error occurs in the app.

Return: object that contains the message and stack information.
- message member indicates the error description.
- stack member indicates the system stack of the call about an error message.

# `onPageNotFound`

Event triggered when the engine redirects to an error page

Return: object that contains the attribute uri, with the source where the error was produced.

# `onDestroy`

Event triggered when the app is destroyed.

Return: -

# Page Lifecycle Events

A page implements the following event handlers that control the behavior of individual pages.

onInit
onReady
onShow
onHide
onDestroy
onBackPress
onMenuButtonPress
onRefresh
onConfigurationChanged

# `onInit`

Event triggered when the page completes the initialization.

Return: -

# `onReady`

Event triggered when the page is created and is ready to be displayed. This event is triggered only once for each page.

Return: -

# `onShow` (page)

Event triggered when a user accesses the page.

Return: -

WARNING

This event is not triggered when the root node of the page is a custom component. You are recommended to use div as the root node.

# `onHide` (page)

Event triggered when a page is redirected to another.

Return: -

# `onDestroy` (page)

Event triggered when a page is redirected to another without storing in the navigation stack.

Return: -

# `onBackPress`

Event triggered when the user activates the back button.

Return: boolean
Behavior:
- If the returned value is true, the page handles the return logic itself;
- If the returned value is false, the system uses the return logic by default;
- If no value is returned: same as false.

# `onMenuButtonPress`

Event triggered when a user presses a menu key.

Return: boolean
Behavior:
- If the returned value is true, the page handles the return logic itself;
- If the returned value is false, the system uses the return logic by default;
- If no value is returned: same as false.

# `onRefresh`

Event triggered when a page is re-opened.

Return: object
Behavior:
- If the page has launchMode set to singleTask, only one instance of this page can exist, so this event is triggered once the page is opened again.
- This event is triggered when the parameter of the router push function contains the clearTask flag when a page is opened (and an instance already exists). The callback parameters are the same provided when the page is re-opened. See more details in the page launch mode section.

# `onConfigurationChanged`

Event triggered when the app configuration changes (e.g., the language, country, region, and text output direction).

Parameters: -
Return: object (e.g., {"type": "locale","types":["locale","layoutDirection"]})
Behavior: The constants mark the changes.
- locale: changes in language, country, or region;
- layoutDirection: changes in the text direction of the system.

# Sequence of Page Lifecycle

The sequence of the page lifecycle (page A) is as follows:

Open page A: onInit() -> onReady() -> onShow()
Open page B on page A: onHide()
Return to page A from page B: onShow()
Back from page A: onBackPress() -> onHide() -> onDestroy()

# Page Launch Mode

You can define how the router manages the page lifecycle.

You can do it either statically, in the manifest, or dynamically with a flag in the router.

# Definition of Page Launch Mode in the Manifest

You can add the launchMode attribute to router.page in the manifest document.

The launchMode member of router's page object is optional and have the following configuration:

Type: string
Value by default: standard
Required: no

The launchMode attribute supports two different values: standard and singleTask.

standard. Using this value, the system creates a new page instance every time a user accesses the page.
singleTask. Using this value, the system opens the existing instance of the page every time a user opens the page. It triggers the refresh event (i.e., onRefresh handler) to remove other pages launched through this page. If it is the first time the page is launched, the system creates one page instance.

Example:

"router": { 
    "entry": "PageA", 
    "pages": { 
        "PageA": { 
            "launchMode": "singleTask", 
            "component": "index" 
        }, 
        "PageB": { 
            "launchMode": "standard", 
            "component": "index" 
        }, 
        "PageC": { 
            "launchMode": "singleTask", 
            "component": "index" 
        } 
    } 
}

To open the sequence of pages PageA, PageB, PageC, PageB, PageC, and PageA, the behavior of the system will be as follows:

[Page Stack is empty]

Open PageA (first time)

Create instance of PageA;
Page Stack: [PageA].

Open PageB

Create instance of PageB;
Display PageB on PageA;
Page Stack: [PageA, PageB].

Open PageC (fist time)

Create instance of PageC;
Display PageC on PageB;
Page Stack: [PageA, PageB, PageC].

Open PageB

Create instance of PageB;
Display PageB on PageC;
Page Stack: [PageA, PageB, PageC, PageB].

Open PageC

Close PageB on top of the stack;
Show the existing instance of PageC and trigger PageC's onRefresh lifecycle event;
Page Stack: [PageA, PageB, PageC].

Open PageA

Close PageC, PageB instances (on top of PageA)
Show the existing instance of PageA and trigger PageA's onRefresh lifecycle event;
Page Stack: [PageA].

# Dynamic Page Launch Mode

You can use two different ways to indicate the launch mode of a page, when working with the router in runtime.

You can either specify the launch flag attribute in the router.push method, or indicate the launch flag attribute as a parameter in the link of the page to opened.

The page launch flag is defined as follows:

Attribute: ___PARAM_LAUNCH_FLAG___
Type: string
Required: no

If this attribute is clearTask, all the pages on the page stack are closed when the target page is opened. If the stack contains multiple instances of target, the system will select the earliest instance and it will trigger the onRefresh lifecycle event on this instance. If there is no instances of the target page, the system will close all pages and creates a new instance for the target page.

Example:

router.push({ 
    uri: '/PageB', 
    params: { 
        ___PARAM_LAUNCH_FLAG___: 'clearTask' 
    } 
})

If the page stack consists of [PageA, PageB, PageC] the logic of the system for opening the PageB is as follows:

Destroy the PageC instance;
Destroy the PageA instance;
Show the existing PageB instance and trigger onRefresh lifecycle event on this instance.

If the page stack consists of [PageA, PageC], the logic of the system for opening the PageB is as follows:

Destroy the PageC instance.
Destroy the PageA instance.
Create a PageB instance and show it.

← Event Handling Internationalization →

# App/Page Lifecycle

# App Lifecycle Events

# onCreate

# onRequest

# onShow

# onHide

# onError

# onPageNotFound

# onDestroy