Application Overview

PhoneJS allows you to create applications that meet the needs of your ever changing enterprise and the BYOD world. Using the power of HTML5, CSS3 and JavaScript, you can deliver a line of business solutions that look, feel and behave just like native apps, without learning multiple languages or frameworks.

Single-Page Application

Applications created using PhoneJS are single-page applications (SPA). This means that the application logic and markup are delivered to the client (web browser) at the first load. Then, data (in the form of JSON objects) can be loaded by request. This eliminates round-trips to the web server to get the page markup each time, thus allowing your app to be responsive.

Here is the HTML markup of a typical PhoneJS application page.

HTML
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>My App</title>
        <script type="text/javascript" src="/js/jquery-2.0.3.min.js"></script>
        <script type="text/javascript" src="/js/knockout-3.0.0.js"></script>
        <script type="text/javascript" src="/js/globalize.min.js"></script>
        <script type="text/javascript" src="/js/dx.phonejs.js"></script>
    </head>
    <body>
        //Here is the div to which the application's views are rendered
        <div class="dx-viewport"></div>
    </body>
</html>

As you can see in the code above, the page's body contains a div element accompanied by the dx-viewport class. This element is used to insert a view. There can be several views. When replacing these views one by another within the "view port", the single-page application is turned into a multi-screen application.

The framework's runtime takes care of navigation between views. You just specify the URL to which the framework navigates, defining routing rules beforehand. When a view is navigated to and rendered, it is made visible using the specified animation or transition. The framework also adds the Back button if needed. Read more about navigation and routing here.

Views in PhoneJS applications are based on the MVVM (Model-View-ViewModel) pattern. A Model is a JavaScript object that either represents data or receives data from a storage (local storage or remote server). A View is an HTML template with bindings and CSS rules. The ViewModel is a JavaScript object that prepares data for the View by adding new fields, calculating other ones or picking data form multiple Models. To learn more about views, refer to the Views and Layouts article.

Application Structure

Application Template

Single-page applications do not necessarily consist of a single file. You can split up JavaScript functions, HTML markup and css styles into separate files. Moreover, you can make a project template for your PhoneJS applications, since these applications have much in common in their structure.

PhoneJS provides a project template that you can use to accelerate your building of a PhoneJS application. This template contains view samples and all the included and referenced resources. Here is what the template includes structurally:

  • css - a folder with the styles for supported devices;

  • js - a folder with required JavaScript libraries;

  • layouts - a folder with predefined layouts that are most often used in mobile applications;

  • views - a folder with two sample views;

  • index.js - a file where the HTMLApplication instance is created and configured;

  • index.html - an application page where all the resources are referenced;

  • index.css - a file where application style classes are defined.

The project template is located in the root Application Template folder of the PhoneJS zip archive.

Application Object

To configure the application and then control its life cycle, an HtmlApplication object must be created using the document.ready event or the jQuery "$()" function. There is an index.js file in the application template supplied with PhoneJS. In this file, the HTMLApplication object is created.

    window.MyApp = {};
    MyApp.$(function() {
        MyApp.app = new DevExpress.framework.html.HtmlApplication({
            namespace: MyApp,        
            defaultLayout: "navbar",
            navigation: [
              {
                title: "Home",
                action: "#home",
                icon: "home"
              },
              {
                title: "About",
                action: "#about",
                icon: "info"
              }
            ]
        });
    });

The parameter of the HTMLApplication's constructor is the configuration object that is used to set up the application options. Specify the required options within the configuration object.

Using the HTMLApplication object, register a routing rule for the application, and navigate to a starting view.

JavaScript
$(function() {
    MyApp.app = new DevExpress.framework.html.HtmlApplication({
        //...
    });
    MyApp.app.router.register(":view", { view: "home"});
    MyApp.app.navigate();
});

For a full list of options and members of the HTMLApplication object, refer to the Reference documentation section.

Link Application Resources

To include resources in your application, use one of the following approaches:

  • include the resources in the markup of the application page;
  • place the resources in separate files and link to them from the application page (in the index.html file).

Here are possible link variants:

HTML
<!-- Link a JavaScript file -->
<script type="text/javascript" src="views/home.js"></script>
<!-- Link a CSS file -->
<link rel="stylesheet" type="text/css" href="views/home.css"/>
<!-- Link an HTML file -->
<link rel="dx-template" type="text/html" href="views/home.html"/>

For instance, jQuery, Knockout, globalize and PhoneJS libraires must be linked in the application page, as well as the index.js file where the HTMLApplication object is created and configured.

HTML
<script type="text/javascript" src="jquery-2.0.3.min.js"></script>
<script type="text/javascript" src="knockout-3.0.0.js"></script>
<script type="text/javascript" src="globalize.min.js"></script>
<script type="text/javascript" src="dx.phonejs.js"></script>

<script type="text/javascript" src="App.js"></script>

Layouts and views must be also linked in the application page.

HTML
<!-- Layouts -->
<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"/>

<!-- App views -->
<link rel="stylesheet" type="text/css" href="views/home.css" />
<script type="text/javascript" src="views/home.js"></script>
<link rel="dx-template" type="text/html" href="views/home.html"/>
<link rel="dx-template" type="text/html" href="views/about.html"/>

Predefined Themes

PhoneJS comes with five predefined themes - one theme for each major hardware platform. Each predefined theme is defined by a CSS class.

  • Android - "dx-theme-android"

  • iOS - "dx-theme-ios"

  • Windows 8 - "dx-theme-win8"

  • Windows Phone 8 - "dx-theme-win8phone"

  • Tizen - "dx-theme-tizen"

  • Desktop - "dx-theme-desktop"

When running, a PhoneJS application retrieves information about the platform from the browser. A corresponding theme class is applied to the root element of the page - the one that is accompanied by the dx-viewport class. This provides a native look and behavior for the application on the current device.

You can, however, build a platform-specific application supplying resources for a particular platform only. In this case, you can expect that your application will have this platform's native look and behavior wherever it runs. To set the target platform for an application, specify the application platform via the DevExpress.devices.current method. Define the target platform before creating the application object.

JavaScript
$(function() {
    DevExpress.devices.current({
        phone: true,
        platform: 'ios'
    });
    app = new DevExpress.framework.html.HtmlApplication({});
});

Use the New iOS7 Theme

PhoneJS applications can look and behave native on devices with the recently released iOS7 platform. For this purpose, a new dx-theme-iOS7 theme has been introduced. Currently, this theme is supported in a beta version and cannot be applied automatically to an application. To switch to the iOS7 theme in code, do the following:

  • After the HTMLApplication object is created, ensure that the application is running on an iOS device;

  • Remove the dx-theme-ios theme class from the dx-viewport element. This class was automatically applied when the iOS platform was detected on the device;

  • Add the dx-theme-ios7 theme class to the dx-viewport element.

The following code demonstrates how to implement this.

JavaScript
MyApp.app = new DevExpress.framework.html.HtmlApplication({
    namespace: MyApp,
    defaultLayout: "default"
});

//Switch to the iOS theme
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");
}