Set Up Your Environment

Learn how to prepare your environment to start working with PhoneJS.

Download PhoneJS

You can download PhoneJS now - using the Download link in the topmost menu.

PhoneJS is distributed as a ZIP file. Unzip the downloaded archive to a directory where you wish to store PhoneJS files. Note that this is not a temporary folder - no further installation or unpacking is required. However, if you need to change PhoneJS files to a different directory, simply move them to the new location.

The PhoneJS folder contains the following subfolders.

  • Application Template
    A template for PhoneJS application projects. Use this template to start developing an PhoneJS application quickly.

  • Demos
    A source code for all the demos that are presented on the site.

  • Eula
    Familiarize yourself with the End-User License Agreement that comes with PhoneJS, as well as with the licenses of the Globalize, jQuery and Knockout libraries that are used in PhoneJS applications.

  • Lib
    The libraries that must be included into PhoneJS applications.
    - css - Style sheets for styling PhoneJS applications for different platforms.
    - js - The PhoneJS library together with the Globalize, jQuery and Knockout libraries that are used in PhoneJS applications as well.
    - layouts - Predefined layout templates for application views.

NOTE: When adding a link to the PhoneJS library, set it last - after links to Globalize, jQuery and Knockout libraries.

Prerequisites

To develop PhoneJS applications, use any code editor you are used to.

PhoneJS is a framework that is based on JavaScript, HTML5 and CSS3. When developing PhoneJS applications, you will need to use only JavaScript, HTML and CSS. In addition, you will need basic knowledge of Knockout and jQuery.

Optionally, you can use TypeScript when developing PhoneJS applications. You can download a .ts file with TypeScript definitions from GitHub. Copy this file to your project. In your TypeScript file, add a reference to this file and the .ts files that include TypeScript definitions for the jQuery, Knockout and globalize libraries.

/// <reference path="TypeScript/dx.phonejs.d.ts" />

Add Libraries

When developing an application using PhoneJS, the following libraries must be referenced.

NOTE: Reference the libraries in the same order as they are listed above.

There are three possible ways to provide links to the necessary files.

Use Manually Installed Libraries

Place the contents of the Lib folder to the folder with your application. In this instance, the links you have to add to your application will be the following.

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

Use a CDN

It is not always necessary to deliver libraries with a published application. There are times when it is best to use a link to these libraries from a Content Delivery Network (CDN). This can improve the performance of your applications.

The DevExpress CDN hosts the PhoneJS library and enables you to easily add it to your applications. A link to this library should be added in the following manner.

HTML
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/dx.phonejs.js"></script>

In addition, you can access all resources that come with PhoneJS:

HTML
<link rel="text/css" href="http://cdn3.devexpress.com/jslib/13.2.13/css/dx.ios.default.css" />
<!--PhoneJS culture dictionaries-->
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/localization/dx.phonejs.de.js"></script>
<!--Predefined layouts for views-->
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/layouts/Navbar/NavbarLayout.js"></script>
<link rel="text/css" href="http://cdn3.devexpress.com/jslib/13.2.13/layouts/Navbar/NavbarLayout.css"/>

To use the jQuery, Knockout and globalize libraries in the same manner as the PhoneJS library, use the Microsoft Ajax CDN or Google CDN.

HTML
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/knockout/knockout-3.0.0.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/globalize/0.1.1/globalize.min.js"></script>

To add the globalize library for all cultures, use the globalize.cultures.js file. To add a library for a specific culture, replace {culture-code} with the desired culture code in the globalize.culture.{culture-code}.js file. For instance, you can add Spanish localization using the globalize.culture.es-MX.js file.

HTML
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/globalize/0.1.1/globalize.culture.es-MX.js"></script>

Use a NuGet Package

When using Visual Studio for developing, you can easily add the PhoneJS library to your ASP.NET project (WebForms, MVC) or Windows Store JavaScript application using the PhoneJS NuGet package. To do this, follow the steps below.

  1. Right-click your project in the Solution Explorer window and choose Manage NuGet Packages... in the context menu.

    NuGetVS

  2. Choose Online in the right column of the appeared window.

    NuGetVS

    Make sure that you have nuget.org as your online source. Then, type PhoneJS within the Search Online text box.

  3. When the search is complete, click the Install button of the found item.

    NuGetVS

After the successful install of the PhoneJS NuGet package, you will find it in the list of installed packages along with the Globalize, jQuery and Knockout packages on which the PhoneJS library depends.

NuGetVS

Once you have installed the PhoneJS NuGet package, you will be able to update the PhoneJS library to the newest version from the Updates section of the Manage NuGet Packages window.

Now, to use the PhoneJS library, you have to provide links to the library and its dependencies. Add the following code to your application.

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

You can find more information about the PhoneJS NuGet package in the NuGet Gallery. To learn how to install NuGet, refer to the Installing NuGet article.

Run and Debug

To run a PhoneJS application locally, use any web server (Apache HTTP Server, IIS or any other).

As an HTML-JavaScript application, a PhoneJS application is run by a browser. The following desktop browsers are supported.

  • Internet Explorer Internet Explorer 8+

  • Safari Safari 5+

  • Firefox Firefox Latest Version

  • Google Chrome Google Chrome Latest Version

  • Opera Opera Latest Version

The browsers integrated in the following mobile OS are supported.

  • Android Android 2.3+

  • iOS Safari iOS 5+

  • IE Windows Phone Windows Phone 8

  • Tizen Tizen 2.2

Generally, a PhoneJS application can run on any device whose browser is supported. However, the corresponding style sheets must be applied so that the application looks native on this device. PhoneJS comes with the following predefined themes.

  • Android Holo Light and Android Holo Dark

  • iOS

  • Windows 8 and Windows Phone 8

  • Tizen Black and Tizen White

  • Generic

To test how your PhoneJS application looks and how it behaves on different devices, use one of the following options.

  • When your application is running in a browser, choose the required browser using the user agent switcher that is built into the browser.

  • In the index.js file of your application project, set the target device using the devExpress.devices.current(deviceName) function before the HtmlApplication object creation. In this instance, the application will run in your browser with the styles corresponding to the device you specified. This approach is helpful when testing URLs that are generated during navigation between views.

  • Use third-party device simulators, such as Ripple or PhoneGap Emulator.

To inspect and debug JavaScript errors in your application, use the browser's developer tools, since all browsers hide JavaScript errors from end users.

Deploy

Although PhoneJS applications can just be deployed to a web server, they are also ready to be compiled by Apache Cordova (PhoneGap) into a native package that can then be submitted to app stores. If you follow this route, PhoneGap also gives you libraries to access your device’s built-in functionality such as camera, accelerometer or contact list.