Migrate to the New Version

Once you decide to use the new version (13.2) of PhoneJS, the applications that were built using the previous version (13.1) must be updated. This document will guide you through the upgrade process.

If you face any issues while migrating, please contact us using our support center.

Navigation Strategy

In the previous version of PhoneJS, you could set a default layout for your application using the defaultLayout option of the HtmlApplication object. To set a specific layout for a particular view, you used the layout option of the corresponding dxView markup component. In our newest release of PhoneJS, however, layouts are applied to application views according to the specified navigation strategy based on the current navigation context. The following changes on your application projects are now required.

  • Replace the application's defaultLayout option with the navigationType option.
    The navigationType option specifies a navigation strategy for the application. You can use one of the predefined strategies.

    JavaScript
    window.MyApp = {};
    $(function() {
        MyApp.app = new DevExpress.framework.html.HtmlApplication({
            navigationType: 'navbar',
            namespace: MyApp
        });
        //...
    });
  • Add the layouts that are used in the specified navigation strategy.
    Ensure that all the required layouts are added to the application and referenced in the index.html file (main page). For instance, the "Navbar" navigation strategy implies the use of the Navbar layout for root views and Simple layout for other views. In addition, the Pivot layout is used for root views on the Windows Phone 8 platform. Thus, if you use the predefined "Navbar" navigation strategy, add all these predefined layouts to your project.

    HTML
    <script type="text/javascript" src="layouts/NavBar/NavbarLayout.js"></script>
    <link rel="stylesheet" type="text/css" href="layouts/NavBar/NavbarLayout.css" />
    <link rel="dx-template" type="text/html" href="layouts/NavBar/NavbarLayout.html"/>
    <script type="text/javascript" src="layouts/Pivot/PivotLayout.js"></script>
    <link rel="stylesheet" type="text/css" href="layouts/Pivot/PivotLayout.css" />
    <link rel="dx-template" type="text/html" href="layouts/Pivot/PivotLayout.html"/>
    <script type="text/javascript" src="layouts/Simple/SimpleLayout.js"></script>
    <link rel="stylesheet" type="text/css" href="layouts/Simple/SimpleLayout.css" />
    <link rel="dx-template" type="text/html" href="layouts/Simple/SimpleLayout.html"/>
  • Register custom layout controllers.
    In previous versions of this software, you registered custom layout controllers in the following manner.

    JavaScript
    //Before
    DevExpress.framework.html.layoutControllers.myController = new MyLayoutController();

    When using our latest release, specify the navigation strategy and other circumstances in which the registered layout controllers must be used.

    JavaScript
    //Now
    DevExpress.framework.html.layoutControllers.push({ navigationType: 'myController', controller: new MyLayoutController() });

    For details, refer to the Navigation Strategy topic.

  • Remove the layout option specification for the dxView markup component.
    If the layout that you set for a particular view using the layout option of the dxView markup component is included in the navigation strategy, just remove the specification of this option. Otherwise, use the resolveLayoutController event of the HtmlApplication object instead. For details, refer to the Override Navigation Strategy topic.

    JavaScript
    var myController = new MyLayoutController();
    MyApp.app.resolveLayoutController.add(function(args) {
        var viewName = args.viewInfo.viewName;
        if(viewName === "myview") {
            args.layoutController = myController;
        }
    });

Command Mapping

The next step is to set the target command container for a command explicitly. For this purpose, perform the following changes in your application.

  • Specify the id option within the dxCommand markup component configuration object.
    The id option is now required to be set for commands.

    HTML
    <div data-bind="dxCommand: { id: 'myCommand', title: 'My command' }"></div>
  • Define command mapping.
    Now, command containers do not specify locations for commands. And the id option is now the only option specified for command containers.

    HTML
    <div data-options="dxCommandContainer: { id: 'my-container' }"></div>

    To specify the command containers in which your commands must be displayed, define command mapping using the commandMapping option of the HtmlApplication object.

    JavaScript
    MyApp.app = new DevExpress.framework.HtmlApplication({
    commandMapping: {
        'my-container': {
            defaults: {
                'showIcon':false, 
                'location':'left'
            },
            commands: [
                {
                    id: 'myCommand',
                    location: 'right' // container defaults can be overridden
                }
            ]
        }
    }
    });

    If you use predefined layouts in your application, learn which command containers they include in the Built-in Layouts topic.

Markup Related Changes

Visible view jQuery selector

Change the active view selectors like $('.dx-viewport .my-selector') to $('.dx-active-view .my-selector').

The ViewModel is not bound to the whole layout markup

If you have your layout markup customized, make sure that all the data-bind attributes are inside the elements with the dxContentPlaceholder or dxTransition markup components. Otherwise, they will not be applied. If you have certain static options outside the mentioned components, replace the data-bind attribute with the data-options attribute.

iOS7 Theme Usage

iOS7 Theme is applied automatically

To use our iOS7 theme in your applications based on PhoneJS version 13.1, you had to write a special code that applied this theme to the app. Now, remove this code since this theme is applied automatically.

JavaScript
//Remove this code
var devices = DevExpress.devices,
    iosVersion = devices.iosVersion();
if(devices.current().platform === "ios" && iosVersion && iosVersion[0] === 7)  {
    $(".dx-viewport")
        .removeClass("dx-theme-ios")
        .addClass("dx-theme-ios7");
}