Introduction

Each page in the mobile application has several stages during navigation process (opening, closing, unloading, returning to page, etc.). The time passed from loading a page, to unloading it from the mobile device memory is called a page life cycle.

For each stage of page life cycle provided the corresponding page event. Use page events to expand functionality. Main page events:

• initialization of the view
• completion of class initialization
• page loading
• data uploading
• page closing.

Understanding the page life cycle stages enables you to enlarge the logic of the pages.

Life cycle stages

ATTENTION Only one page can be displayed on the mobile phone screen. Tablet PC can display one page in a portrait orientation and two pages in a landscape orientation. Due to this, the page life cycle differs for the phone and the tablet.

Page opening

At first opening of the page, all scripts necessary for the work of the page are being loaded. After that the controller is being initialized and the view is created.

Sequence of page opening event generation:

1. initializeView – view initialization.

2. pageLoadComplete – event of completion of the page loading.

3. launch – initiates data loading.

Page closing

When the page is closed, it’s view is deleted from the document object model (DOM) and controller is being deleted from the device memory.

Page is closed in the following cases:

• The [Back] button is pressed. In this case the last page is being deleted.
• New section was opened. In this case all pages that were opened before are being deleted.

pageUnloadComplete – the event of page closing completion.

Page unloading

Unloading is performed after the passing to another page in the same section. The current page becomes inactive. It can stay visible on the device screen. For example, if you open a view page from the list on the tablet PC, the list page will stay visible. In the same case on the phone, the list page will not be visible but will stay in the memory. This is the difference between unloading and closing a page.

pageUnloadComplete – the event of page unload (coincides with the event of the page closing).

Return to the page

Return to the unloaded page is performed by pressing the [Back] button.

pageLoadComplete – returning to the page event.

ATTENTION Only one instance of the page can be used in the application. If you consistently open two identical pages and return to the first page, the launch event handler will be executed again. This should be taken into account in the development.

Life cycle event handlers

Page controller classes are inherited from the Terrasoft.controller.BaseConfigurationPage class that provides methods of handling the life cycle events.

initializeView(view)

Method is called after the page view in the DOM is being created (but was not rendered). On this stage you can subscribe to the events of the view classes and perform additional actions with DOM.

pageLoadComplete(isLaunch)

Provides extension of the logic that is executed at the page load and return. The true value of the isLaunch parameter indicates that the page is being loaded for the first time.

launch()

Called only when the page is opened. The method initiates the loading of data. If you need to load additional data, use the launch() method.

pageUnloadComplete()

Provides extension of the logic that is executed at the page unload and closure.

Page navigation

The Terrasoft.PageNavigator class manages the life cycle of the pages. The class enables opening and closing of the pages, updating of the irrelevant data and storing the page history.

forward(openingPageConfig)

Method opens page according to the properties of the openingPageConfig configuration parameter object. Main properties of this object are listed in the Table 1.

Table 1. The openingPageConfig object properties

backward()

The method is closing the page.

markPreviousPagesAsDirty(operationConfig)

Method marks all previous pages as irrelevant. After returning to previous pages, the refreshDirtyData() method is called for each page. The method re-loads the data or updates the data basing on the operationConfig object.

refreshPreviousPages(operationConfig, currentPageHistoryItem)

Method re-loads data for all previous pages and updates the data basing on the operationConfig object. If the value is set for the currentPageHistoryItem parameter, the method performs the same actions for the previous pages.

refreshAllPages(operationConfig, excludedPageHistoryItems)

Method re-loads data for all pages or updates the data basing on the operationConfig object. If the excludedPageHistoryItems parameter is set, the method does not update the specified pages.

Navigation with routes

Routing

Routing is used for managing visual components: pages, pickers, etc. The route has 3 states:

1. Load – opens a current route.

2. Unload – closes current route on return.

3. Reload – restores the previous route on return.

The Terrasoft.Router class is used for routing and it’s main methods are add(), route() and back().

add(name, config)

Adds a route. Parameters:

• name – Unique name of the route. In case of re-adding, the latest route will override the previous one.

• config – describes names of the functions that handle route states. Handlers of the route states are set in the handlers property.

Use case:

Terrasoft.Router.add("record", {
  handlers: {
     load: "loadPage",
     reload: "reloadPage",
     unload: "unloadLastPage"
  }
});

route(name, scope, args, config)

Starts the route. Parameters:

• name – name of the route.

• scope – context of the function of the state handlers.

• args – parameters of the functions of the state handlers.

• aonfig – additional route parameters.

Use case:

var mainPageController = Terrasoft.util.getMainController();
Terrasoft.Router.route("record", mainPageController, [{pageSchemaName: "MobileActivityGridPage"}]);

back()

Closes current route and restores previous.

Routing of user pages of the Custom type

Application has four types of pages: Grid, Preview, Edit и Custom. For the first three types the record base route is used. For the user page of the Custom type you need to add a new route.

For this you need to create classes of the page and controller:

Ext.define("Terrasoft.configuration.view.MyPage", {
    extend: "Terrasoft.view.BaseConfigurationPage",
    xtype: "mypage",
    config: {
        id: "MyPage",
        pageType: Terrasoft.PageTypes.Custom,
        navigationPanel: {
            backButton: true
        }
    }
});

Ext.define("Terrasoft.configuration.controller.MyPage", {
    extend: "Terrasoft.controller.BaseConfigurationPage",
    config: {
        refs: {
            view: "#MyPage"
        }
    },
    statics: {
        Model: Contact
    },
    initializeView: function() {
        this.callParent(arguments);
        //Initializing the page title.
        this.initializeNavigationTitle();
    },
    getTitle: function() {
        return "My page";
    },
    pageLoadComplete: function() {
        this.callParent(arguments);
        var pageHistoryItem = this.getPageHistoryItem();
        var config = pageHistoryItem.getRawConfig();
        var view = this.getView();
        //Displaying User Data in a View.
        view.add({
            xtype: "label",
            html: config.customData
        });
    }
});

The receiving of the customData data from the PageHistory is performed in the pageLoadComplete() method. Then the data is displayed in the view.

ATTENTION When developing a mobile application, all source code should be added to the shemas of the “Module” type. The parent schema is not specified and the standard inheritance/replacing mechanism does not work. The created schemas should be specified in the CustomSchemas array of the mobile application manifest (see “Mobile application manifest”). If you need to extend of override existing class, you should use the “extend” and “override” basic mechanisms of the Ext.js framework (see "Basic OOP / Class-Based Programming Concepts").

After that add a route of user page in the router and specify route state handlers:

Terrasoft.Router.add("myPage", {
    handlers: {
        load: "loadMyPage",
        unload: "unloadMyPage"
    }
});

After that create a class that provides methods of handling the route states:

Ext.define("Terrasoft.configuration.MyPageUtils", {
    singleton: true,
    getPageData: function() {
        //Page settings.
        return {
            controllerName: "Terrasoft.configuration.controller.MyPage",
            pageSchemaName: "MyPageSchemaName",
            viewXType: "mypage"
        };
    },

    loadMyPage: function(data) {
        var pageData = this.getPageData();
        // Adding User Data.
        pageData.customData = data;
        // Opening a page using PageNavigator.
        Terrasoft.PageNavigator.forward(pageData);
    },

    unloadMyPage: function() {
        //Closing a page using PageNavigator.
        Terrasoft.PageNavigator.backward();
    }
});

After that add the page to the cache:

Terrasoft.PageCache.addItem("MyPageSchemaName",Terrasoft.configuration.MyPageUtils.getPageData());

Noe the route is configured for the MyPage page. To open the route you need to perform the following command:

Terrasoft.Router.route("myPage", Terrasoft.configuration.MyPageUtils, ["My page data"]);

The user page will be opened after execution of the command (Fig. 1).

Fig. 1. User page

NOTE The call wrap-up page is an example of this functions implementation (see the MobilePhoneCallLogPage schema with specified controller page and a view page with three fields). And the utility singleton class that enables to call the page (see the MobilePhoneCallLogUtils schema). An example of the page call can be found in the MobileAccountPreviewPage schema.