Application Project

Applications created using the DevExtreme framework are single-page applications (SPA). Here is the page markup for a simple DevExtreme application with two views.

HTML
<!DOCTYPE html>
<head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="/js/jquery-2.1.1.min.js"></script>
    <script type="text/javascript" src="/js/knockout-3.1.0.js"></script>
    <script type="text/javascript" src="/js/globalize.min.js"></script>
    <script type="text/javascript" src="/js/dx.phonejs.js"></script>
   
    <script type="text/javascript">
        window.AppNamespace = {};
        $(function () {       
            AppNamespace.app = new DevExpress.framework.html.HtmlApplication({
                namespace: AppNamespace,
                layoutSet: "simple"
            });
            AppNamespace.app.router.register(":view/:name", { view: "home", name: '' });
            AppNamespace.app.navigate();
        });
        AppNamespace.home = function () {
            var viewModel = {
                //ViewModel Fields
            };
            return viewModel;
        };
        AppNamespace.anotherView = function (params) {
            var viewModel = {
                //ViewModel Fields
            };
            return viewModel;
        };
    </script>
</head>
<body>
    <div class="dx-viewport">
        <div data-options="dxView : { name: 'home', title: 'Home' } " >
            <div data-options="dxContent : { targetPlaceholder: 'content' } " >
            </div>
        </div>
        <div data-options="dxView : { name: 'anotherView', title: 'Another View' } " >
            <div data-options="dxContent : { targetPlaceholder: 'content' } " >
            </div>
        </div>
    </div>
</body>
</html>

It is possible to organize everything on one page, but it will be difficult to support this page in a real application. You can split up JavaScript functions, HTML markup and CSS styles into separate files. To make application development easier, we recommend that you use the DevExtreme application template, which includes the following.

  • css - a folder with the styles for supported devices

  • js - a folder with the required JavaScript libraries

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

  • views - a folder with two sample views;

  • index.js - a file where the HTMLApplication object 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

This project template is available to you out-of-the-box. It contains view samples, as well as all included and referenced resources. You can find this template in the following locations.

  • DevExtreme Mobile/DevExtreme Web
    The Application Template folder of the DevExtreme zip archive.

  • DevExtreme Complete
    Basic and multi-channel project templates available within the Visual Studio project templates.

Read below to learn about the different parts of a DevExtreme application project.

Application Page

According to the DevExtreme application template, an application page includes links to required resources only. Here is how it looks.

HTML
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <script type="text/javascript" src="/js/jquery-2.1.1.min.js"></script>
        <script type="text/javascript" src="/js/knockout-3.1.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 within the "view port", the single-page application is turned into a multi-screen application.

Scripts

When developing a DevExtreme application, the following libraries must be referenced in the application page.

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

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

Use Local Scripts

To provide the required scripts for your application, you can put them into the project and give links to them within the application page.

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

These libraries are available for you within the following folder.

  • DevExtreme Mobile/DevExtreme Web
    The lib/js folder of the product's zip archive.
  • DevExtreme Complete
    The DevExtreme/sources/lib/js folder.

In the application template project, all the framework scripts and the scripts that are used by the framework are already located within the js folder. Links to these scripts are given within the application page.

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 and WebAppJS libraries and enables you to easily add them to your applications. Links to these libraries should be added in the following manner.

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

In addition, you can access all the resources that come with DevExtreme.

HTML
<link rel="text/css" href="http://cdn3.devexpress.com/jslib/14.1.13/css/dx.ios.default.js" />
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/14.1.13/js/localization/dx.phonejs.de.js"></script>
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/14.1.13/layouts/Navbar/NavbarLayout.js"></script>
<link rel="text/css" href="http://cdn3.devexpress.com/jslib/14.1.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.1.1.min.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/knockout/knockout-3.1.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>

Themes and Styles

To make your DevExtreme application appear native on the device it is running, a specific theme must be applied. DevExtreme includes a set of themes that are specific to different devices. The generic "light" and "dark" themes are also available. These themes are not specific to a particular device, but make an application look consistent on any device. Add links to the required themes on the application page before adding links to the product scripts.

HTML
<link rel="stylesheet" type="text/css" href="css/dx.common.css" />
<link rel="stylesheet" type="text/css" href="css/dx.spa.css" />
<link rel="dx-theme" data-theme="android.holo-dark" href="css/dx.android.holo-dark.css" data-active="true" />
<link rel="dx-theme" data-theme="android.holo-light" href="css/dx.android.holo-light.css*" data-active="false" />
<link rel="dx-theme" data-theme="ios.default" href="css/dx.ios.default.css" />
<link rel="dx-theme" data-theme="ios7.default" href="css/dx.ios7.default.css" />
<link rel="dx-theme" data-theme="win8.black" href="css/dx.win8.black.css" data-active="true" />
<link rel="dx-theme" data-theme="win8.white" href="css/dx.win8.white.css" data-active="false" />
<link rel="dx-theme" data-theme="tizen.black" href="css/dx.tizen.black.css" data-active="true" />
<link rel="dx-theme" data-theme="tizen.white" href="css/dx.tizen.white.css" data-active="false"/>
<link rel="dx-theme" data-theme="generic.light" href="css/dx.light.css" data-active="true" />
<link rel="dx-theme" data-theme="generic.dark" href="css/dx.dark.css" data-active="false" />

The dx.common.css and dx.spa.css files include styles that are required for DevExtreme applications, with no relationship to the device on which the application is running.

To learn about predefined themes and styles, refer to the Predefined Themes article.

In addition to the predefined styles, you may need to define the styles that are specific to a particular application. These styles should be collected within the app.css file. This file should be referenced within the application page.

HTML
<link rel="stylesheet" type="text/css" href="app.css"/>

The app.css file and the predefined themes are added to the application template project and referenced in the application page.

Application Object

To configure the application and control its life cycle, an HtmlApplication object must be created using the document.ready event or the jQuery "$()" function. There should be an index.js file within the application project. The HTMLApplication object should be created in this file.

JavaScript
window.MyApp = {};
MyApp.$(function() {
    MyApp.app = new DevExpress.framework.html.HtmlApplication({
        namespace: MyApp
    });
});

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

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

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

The index.js file must be linked in the application page.

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

The application template project includes this file and has a reference to it within the application page.

Layouts

According to the framework's Views and Layouts concept, a screen is a combination of view and layout markup. Each screen has a common element such as a navigation bar or a toolbar. These elements are added to the layout markup, which is then applied to each displayed view. Since several different layouts can be used in an application, a layout set should be specified as an array assigned to the layoutSet configuration option of the application object. The framework comes with ready-to-use layout sets that are based on predefined layouts.

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

In the code above, the navigation option is specified. The array assigned to this option will be used by the 'navbar' predefined layout to create navigation items on the navbar widget.

The predefined layouts that are used in the speciified layout set should be contained in the application and referenced in the application page.

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/Simple/Simple.js"></script>
<link rel="stylesheet" type="text/css" href="layouts/Simple/Simple.css" />
<link rel="dx-template" type="text/html" href="layouts/Simple/Simple.html"/>

The application template project includes a folder with all the predefined layouts. The 'navbar' layout set is specified for the application, and the corresponding layouts are referenced in the application page.

To learn more about view and layout concepts, refer to the Views and Layouts article.

To learn about layout sets and predefined layouts, refer to the Built-in Layouts article.

Views

A view is defined by a piece of HTML markup that forms the view template. This view template can optionally contain JavaScript code and associated style sheets, used to customize the look and feel. The view template, JavaScript code and styles should be implemented in separate files. As a result, a view will be represented by the following files.

  • viewName.html
  • viewName.js
  • viewName.css

Place these files in the application's Views folder, so that you have a separate folder with views. Link view files within the application page.

<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"/>

The application template project includes the Views folder with three sample views. The files where these views are implemented are referenced in the application page.

To learn more about views, refer to the Views and Layouts article.