DevExtreme jQuery/JS - 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" />
    <!-- Links to themes and styles -->
    <!-- Links to the required scripts -->
    <script type="text/javascript" src="/js/jquery-3.1.0.min.js"></script>
    <script type="text/javascript" src="/js/knockout-3.4.0.js"></script>
    <script type="text/javascript" src="/js/dx.mobile.js"></script>
    <!-- Links to layouts -->   
    <script type="text/javascript">
        window.AppNamespace = {};
        $(function () {       
            AppNamespace.app = new DevExpress.framework.html.HtmlApplication({
                namespace: AppNamespace,
                layoutSet: "simple",
                animationSet: "default"
            });
            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' } " >
                <!--View markup-->
            </div>
        </div>
        <div data-options="dxView : { name: 'anotherView', title: 'Another View' } " >
            <div data-options="dxContent : { targetPlaceholder: 'content' } " >
                <!--View markup-->
            </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 DevExtreme zip archive or in the folder where you have installed DevExtreme, which is C:\Program Files (x86)\DevExpress 17.2\DevExtreme\Sources by default.

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" />
        <!-- Styles should be linked here-->
        <!-- Scripts -->
        <script type="text/javascript" src="/js/jquery-3.1.0.min.js"></script>
        <script type="text/javascript" src="/js/knockout-3.4.0.js"></script>
        <script type="text/javascript" src="/js/dx.mobile.js"></script>
        <!-- Layouts should be linked here -->
        <!-- Separated application files should be linked here -->
    </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.

  • jQuery version 2.1 - 2.2 and 3.x
  • Knockout versions 2.2.3 - 2.3.0 and 3.1.0 - 3.4.0
  • dx.mobile or dx.web.

DevExteme does not require the following libraries to be referenced in your application. However, you should reference those libraries whose functionality you are going to use in the application.

  • Globalize version 1.x

    You need to reference Globalize only if your application should support the following functionality.

    1. Non-English locales
    2. Custom message dictionaries
    3. Non-USD currency formatting
    4. Custom date and number formatting

    To learn more about how to use the Globalize library, refer the Localization Using Globalize topic.

  • JSZIP library

    You need to reference the JSZIP library only when exporting data to a file.

NOTE
Reference the DevExtreme scripts (dx.mobile or dx.web) after external scripts.

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-3.1.0.min.js"></script>
<script src="js/knockout-3.4.0.js"></script>
<script src="js/dx.mobile.js"></script>

Learn where you can get these libraries from topics in the Installation section.

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.

To use the jQuery and Knockout libraries, use the Microsoft Ajax CDN or Google CDN.

HTML
<script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.1.0.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/knockout/3.4.0/knockout-min.js"></script>

The DevExpress CDN hosts the dx.mobile and dx.web 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="https://cdn3.devexpress.com/jslib/17.2.18/js/dx.mobile.js"></script>

or ...

HTML
<script type="text/javascript" src="https://cdn3.devexpress.com/jslib/17.2.18/js/dx.web.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. To learn about predefined themes and styles, refer to the Predefined Themes article.

NOTE
Add links to the required themes on the application page before adding links to the product scripts.

Read subsections below to learn two possible ways to provide links to the necessary files.

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

Use Local Themes

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

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="android5.light" href="css/dx.android5.light.css" data-active="true" />
<link rel="dx-theme" data-theme="ios7.default" href="css/dx.ios7.default.css" />
<link rel="dx-theme" data-theme="win10.black" href="css/dx.win10.black.css" data-active="true" />
<link rel="dx-theme" data-theme="win10.white" href="css/dx.win10.white.css" />
<link rel="dx-theme" data-theme="generic.light" href="css/dx.light.css" data-active="true" />
<link rel="dx-theme" data-theme="generic.light.compact" href="css/dx.light.compact.css" />
<link rel="dx-theme" data-theme="generic.dark" href="css/dx.dark.css" />
<link rel="dx-theme" data-theme="generic.dark.compact" href="css/dx.dark.compact.css" />
<link rel="dx-theme" data-theme="generic.contrast" href="css/dx.contrast.css" />
<link rel="dx-theme" data-theme="generic.contrast.compact" href="css/dx.contrast.compact.css" />

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.

All the files with styles are available for you in the DevExtreme zip archive or in the folder where you have installed DevExtreme, which is C:\Program Files (x86)\DevExpress 17.2\DevExtreme\Sources by default.

In the application template project, all the DevExtreme stylesheets are already located within the css folder. Links to these stylesheets are given within the application page.

Use a CDN

It is not always necessary to deliver stylesheets 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 DevExtreme stylesheets and enables you to easily add them to your applications. Links to the required files should be added in the following manner.

HTML
<link rel="stylesheet" type="text/css" href="https://cdn3.devexpress.com/jslib/17.2.18/css/dx.common.css" />
<link rel="stylesheet" type="text/css" href="https://cdn3.devexpress.com/jslib/17.2.18/css/dx.spa.css" />
<link rel="dx-theme" data-theme="ios.default" href="https://cdn3.devexpress.com/jslib/17.2.18/css/dx.ios7.default.css" />
NOTE
Font icons that are linked in CSS themes are also located on CDN.

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 markups. 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",
                onExecute: "#home",
                icon: "home"
            },
            {
                title: "About",
                onExecute: "#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 specified layout set should be contained in the application and referenced in the application page. Read the subsections below to learn two possible ways to provide links to the necessary layout files.

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.

Use Local Layouts

To provide the required layouts for your application, you can put them into the project and give links to them within 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"/>
<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"/>

All the layouts are available for you in the DevExtreme zip archive or in the folder where you have installed DevExtreme, which is C:\Program Files (x86)\DevExpress 17.2\DevExtreme\Sources by default.

The application template project includes the layouts 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.

Use a CDN

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

The DevExpress CDN hosts DevExtreme layouts and enables you to easily add them to your applications. Links to the required files should be added in the following manner.

HTML
<link rel="dx-template" type="text/html" href="https://cdn3.devexpress.com/jslib/17.2.18/layouts/Navbar/NavbarLayout.html"/>    
<script type="text/javascript" src="https://cdn3.devexpress.com/jslib/17.2.18/layouts/Navbar/NavbarLayout.js"></script>
<link rel="text/css" href="https://cdn3.devexpress.com/jslib/17.2.18/layouts/Navbar/NavbarLayout.css"/>
<link rel="dx-template" type="text/html" href="https://cdn3.devexpress.com/jslib/17.2.18/layouts/Simple/SimpleLayout.html"/>    
<script type="text/javascript" src="https://cdn3.devexpress.com/jslib/17.2.18/layouts/Simple/SimpleLayout.js"></script>
<link rel="text/css" href="https://cdn3.devexpress.com/jslib/17.2.18/layouts/Simple/SimpleLayout.css"/>

Animation

To make an application 'live' and attractive, different animations should be applied to different elements in the application. For instance, when you navigate from a view to another view in a mobile application, the content of the new view replaces the content of the old view with a certain animation. The header in a view can be animated differently from the rest of the content on both views. All these animations should be registered as animation presets and collected to the application's animationSet. The framework comes with ready-to-use animation sets. In the application template, the 'default' animation set is used.

JavaScript
window.MyApp = {};
MyApp.$(function() {
    MyApp.app = new DevExpress.framework.html.HtmlApplication({
        namespace: MyApp,        
        animationSet: DevExpress.framework.html.animationSets['default'],
        //...
    });
});

The animations that a predefined animation set includes are used by the predefined layouts to animate transitions between views. In addition, animations from this set can be used to animate list and detail views specifically. For details, refer to the Animation 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.

<!-- HTML -->
<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.