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.

JavaScript
window.MyApp = {};
    MyApp.$(function() {
        MyApp.app = new DevExpress.framework.html.HtmlApplication({
            <span class="description-tooltip" data-name="namespace-description">namespace</span>: MyApp,        
            <span class="description-tooltip" data-name="defaultLayout-description">navigationType</span>: "navbar",
            <span class="description-tooltip" data-name="navigation-description">navigation</span>: [
              {
                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 a set of predefined CSS classes that define basic styles for different mobile platforms.

  • Android - "dx-theme-android"
  • iOS - "dx-theme-ios"
  • Windows 8 and Windows Phone 8 - "dx-theme-win8"
  • Tizen - "dx-theme-tizen"
  • generic - "dx-theme-generic"

When running, a PhoneJS application retrieves information about the platform from the browser. A corresponding CSS class is applied to the root element of the page - the element that is accompanied by the "dx-viewport" class. If a style specific for the required platform is not found, the generic theme is applied.

In addition to the basic styles for mobile platforms, there is a capability to stylize an application according to a device form. For instance, different classes - ".dx-theme-ios.dx-device-phone" and ".dx-theme-ios.dx-device-tablet" - are introduced for iPhone and iPad devices.

Finally, specific styles can be applied for different major versions of a device platform. For instance, different styles are introduced for the iOS6 and iOS7 versions within the ".dx-theme-ios.dx-version-major-6" and ".dx-theme-ios.dx-version-major-7" classes.

All the predefined CSS classes are grouped into so-called themes - a set of styles for a particular platform, device form and version. For some of the platforms, themes are introduced in several color schemes. For instance, both light and dark themes are supplied for Android devices.

You can find the predefined CSS classes in the lib/css folder in the PhoneJS zip archive. There are the following files in this folder.

  • dx.android.holo-dark.css
    Dark themes for all Android devices.

  • dx.android.holo-light.css
    Light themes for all Android devices.

  • dx.ios.default.css
    Themes for all iOS devices.

  • dx.win8.black.css
    Black themes for all Windows 8 devices.

  • dx.win8.white.css
    White themes for all Windows 8 devices.

  • dx.tizen.black.css
    Black themes for all Tizen devices.

  • dx.tizen.white.css
    White themes for all Tizen devices.

  • dx.generic.light.css
    Platform-agnostic themes for any device. These themes are automatically applied when there is no appropriate theme for the device on which the application runs. In addition, a generic theme can be applied explicitly so that the application looks and behaves similarly on all devices.

  • dx.common.css
    A set of common CSS classes that do not depend on the current circumstances. This file should be referenced first in the list of themes provided for the application.

When building an application, add references to these files in the index.html file. When running, the application will apply an appropriate theme.

HTML
<link rel="stylesheet" type="text/css" href="css/dx.common.css"/>
<link rel="stylesheet" type="text/css" href="css/dx.ios.default.css"/>
<!--...-->

You can build a platform-specific application supplying resources for a specific 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
window.MyApp = {};
$(function() {
    DevExpress.devices.current({
        phone: true,
        platform: 'generic'
    });
    MyApp.app = new DevExpress.framework.html.HtmlApplication({namespace: MyApp});
});