Page API

The Page API is used to provide the page functionality to your app. Through this page API, you can navigate multiple pages and handle functionalities such as navigation through different pieces of content and pages within your app, page events used by your application, and page lifecycle activities.

For example, when using your app, a user might stop working on a page or content and switch to another app. When the user returns to your app, it automatically allows the user to resume working on the same page or content. In other words, the callback allows your app to perform specific work that appropriates to a given change of state. The Page API methods and events make your app robust and performant as it can do the right work at the right time and handle transitions properly. The Page API is supported on Android, iOS, and Web platforms. Specific methods or events which are part of the Page API may be available only in a single platform.

The following are some of the main functions handled by Page API:

Signal to your app that the page is loaded and ready to access.
Handle up and back actions correctly
Handle navigation across, into, and back out of different pieces of content or different pages.
Open and close specific pages.
Pass content to the next specified page.

Your app will generally navigate through multiple pages, and data exchange between the pages is one of the primary requirements. You can use the following ways to share data between the pages:

Preferences: Data that needs to be shared between pages can be stored into preferences. But this might lead to a huge drain on the device memory as preferences get persisted.
Page Data and Result: The following page methods can be used to share data between pages. The advantages of using these methods are they don’t persist the data and hence are suitable for any transient data.
- open: Opne a page and pass data to the child page.
- setResult: Return data to the parent page or between pages.

But you should be careful about the size of the result passed back to the parent page or between pages should be less, as moving huge amount of data would consume process timing and device memory which would lead to degradation in user experience.

Methods

open
close

Events

onResult
deviceready
pause
resume
backbutton
menubutton
searchbutton
startcallbutton
endcallbutton
volumedownbutton
volumeupbutton

open

Use this method to open the specified URL and load it to the page. You can also tag it with the data that needs to pass to the page. The method also checks if any page is available with the specified URL and if it finds one, it brings that page to the foreground.

Syntax

$m.open(URL, Data);

Parameters

URL: (String). Refers to the URL of the page that is present in the pack or system file. Possible values are,

• Relative URL - URL relative to the app folder. The URL should start with the pack name of the page.

• Absolute URL - Any external URL or internal files.

Data: (object/string/number/boolean). The data to be passed to the page.

Example

$m.open($m.documentsDirectory+filepath' "{test:test1}");

close

Use this method to close the current page and releases the memory heap associated with it. The setResult method will be executed before the page closes to pass the result data to the parent page.

Syntax

$m.close();

Parameters

Not applicable

Example

$m.close();

onResult

Use this method to registers a function to execute when a child page has sent a result.

Syntax

$m.onResult(function(event_object){});

Parameters

function: Function to execute when a child page has sent a result. The function receives an eventObject which contains the following property:

result: (object/string/number/boolean). Result that is sent by the child page.

Example

$m.onResult(function(eventObject) {
// Result coming from eventObject.page
});

Events

Your app can use the events listed here as part of page lifecycle activity. The event object functions can be implemented for any pages. The event object functions are automatically triggered based on the state of the page in the page lifecycle.

The following table lists the events and the supported platforms:

Events	Android	iOS	Windows
`deviceready`	Yes	Yes	Yes
`pause`	Yes	Yes	Yes
`resume`	Yes	Yes	Yes
`backbutton`	Yes	No	Yes
`menubutton`	Yes	No	No
`searchbutton`	Yes	No	No
`startcallbutton`	No	No	No
`endcallbutton`	No	No	No
`volumedownbutton`	Yes	No	No
`volumeupbotton`	Yes	No	No

deviceready

This is an event that fires when your app is fully loaded and ready to access. This event is essential to your app. After the event fires, you can safely make calls to your other APIs.

Syntax

document.addEventListener("deviceready", yourCallbackFunction, false);

Example

document.addEventListener("deviceready", onDeviceReady, false);    
function onDeviceReady() {      
// Do something 
 }

pause

This is an event that fires when the native platform puts the app into the background, typically when the user moves to a different app.

Syntax

document.addEventListener("pause", yourCallbackFunction, false);

Example

document.addEventListener("pause", onResume, false);   
function onResume() {      
// Do something 
 }

resume

This is an event that fires when the native platform pulls the app out from the background.

Syntax

document.addEventListener("resume", yourCallbackFunction, false);

Example

document.addEventListener("resume", onResume, false);   
function onResume() {      
// Do something 
 }

backbutton

This is an event that fires when the user selects the back button. To override the default back-button behavior, register an event listener for the backbutton event.

Syntax

document.addEventListener("backbutton", yourCallbackFunction, false);

Example

document.addEventListener("backbutton", onbackKeyDown, false);   
function onbackKeyDown() {      
// Do something 
 }

menubutton

This is an event that fires when the user selects the menu button. You can apply a event handler to override the default menu button behavior.

Syntax

document.addEventListener("menubutton", yourCallbackFunction, false);

Example

document.addEventListener("menubutton", onMenuKeyDown, false);   
function onMenuKeyDown() {      
// Do something 
 }

searchbutton

This is an event that fires when the user selects the search button.

Syntax

document.addEventListener("searchbutton", yourCallbackFunction, false);

Example

document.addEventListener("searchbutton", onSearchKeyDown, false);   
function onSearchKeyDown() {      
// Do something 
 }

startcallbutton

This is an event that fires when the user selects the start call button.

Syntax

document.addEventListener("startcallbutton", yourCallbackFunction, false);

Example

document.addEventListener("startcallbutton", onStartCallKeyDown, false);   
function onStartCallKeyDown() {      
// Do something 
 }

endcallbutton

This is an event that fires when the user selects the end call button. This event overrides the default end call behavior.

Syntax

document.addEventListener("endcallbutton", yourCallbackFunction, false);

Example

document.addEventListener("endcallbutton", onEndCallKeyDown, false);   
function onEndCallKeyDown() {      
// Do something 
 }

volumedownbutton

This is an event that fires when the user selects the volume down button.

Syntax

document.addEventListener("volumedownbutton", yourCallbackFunction, false);

Example

document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);   
function onVolumeDownKeyDown() {      
// Do something 
 }

volumeupbutton

This is an event that fires when the user selects the volume up button.

Syntax

document.addEventListener("volumeupbutton", yourCallbackFunction, false);

Example

document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);   
function onVolumeUpKeyDown() {      
// Do something 
 }