Project Templates

To standardize application code in terms of naming and structure and simplify the process of creating applications, DevExtreme comes with application templates integrated into Visual Studio. Using these templates, you will create mobile applications more quickly.

To create a project using one of the DevExtreme templates, select File | New | Project... from the Visual Studio main menu. This will take you to the New Project dialog.

New Project Dialog

In the Projects tree view, select DevExtreme. In the Templates list view, choose a project template, specify a name for it and click OK.

DevExtreme App Project Template

DevExtreme provides several project templates for building applications. These templates have different structure specific to the application purpose. However, all of these templates have a similar set of features characterizing the possessiveness of the templates to DevExtreme.

Project Context Menu

Here is the context menu that is invoked by right-clicking a DevExtreme project.

DevExtreme Project Context Menu

  • Properties
    DevExtreme projects have general application properties. You can set them up within the Properties window. For details, refer to the Specify General Project Properties topic.

  • Manage NuGet Packages...
    DevExtreme projects can be extended by external libraries that are distributed as NuGet packages. For this purpose, use the standard *Manage NuGet Packages... dialog.

  • Build Application Template...
    DevExtreme applications are packed using the PhoneGap Build. For this purpose, DevExtreme applications have a default PhoneGap application template. If you are required to use a custom Cordova version or a custom set of PhoneGap plugins, you should build a custom PhoneGap application template to be used to pack your DevExtreme application. For this purpose, use the Build Application Template... wizard. For details, refer to the Build Custom PhoneGap Application Template topic.

  • Run Theme Builder...
    DevExtreme comes with a set of predefined themes. Each theme is represented by CSS classes that are responsible for giving consistency to an application. You can customize these themes and make them specific to your application(s). For this purpose, use the Theme Builder.

  • Build Native Packages...
    Applications built using the DevExtreme Project Templates can be easily packaged to be deployed to any device. For this purpose, use the Build Native Packages... wizard. For details on packaging, refer to the Packaging Tools article.

Project Specific Files

DevExtreme application projects have the following common files.

  • cordova.js
    Initially, this is an empty file. When building a package, the Package Builder replaces this file with a valid platform specific Cordova library of the required version. For details on the Cordova version, refer to the Set Cordova Version topic.

  • config.xml
    A file that is used by the Build Native Packages... wizard. This file is required to specify core Cordova API features, plugins, and platform-specific settings.

Simulation Tools

Applications built using DevExtreme project templates run in a browser with the help of the DevExtreme Simulator. To read more, refer to the Simulation Tools article.

Linking to Other Projects

You can deploy a DevExtreme project by linking it to another Visual Studio project - ASP.NET, WindowsPhone, Win8, etc. - and then deploy the latter using standard Visual Studio tools. To link a DevExtreme project to another project, use the Link to... dialog. To invoke this dialog, use the Link to... item in a context menu of the DevExtreme project. This menu item appears in the context menu when there is a non-DevExtreme project in the current solution.

For details on linking DevExtreme projects to other projects, refer to the Linking DevExtreme Projects article.

Basic Application

Basic Application is a project template for building an HTML/JS application based on the DevExtreme SPA Framework and DevExtreme widgets.

Watch Video

The Basic Application project has a basic structure that is common for applications based on the DevExtreme framework. This application structure is detailed in the Application Project article.

DevExtreme_BasicProject

The .dxView files are the HTML files that can be opened using the View Designer. To learn more about the View Designer, refer to the Design-Time Features documentation section.

The app.config.js file includes the configuration object used to initialize the application object.

Generally, the basic project template is the minimum requirement for starting to build an application. You can then extend the project as required. This is demonstrated in the Your First Application tutorial.

The application created using the Basic Application template can be built for the desktop or packaged for iOS, Android, WinPhone and PhoneGap. For details, refer to the Packaging Tools documentation section.

Basic Application (Type Script)

Basic Application (Type Script) is the same as the Basic Application project. The only difference is that the TypeScript language is used in the Basic Application (Type Script) and the required Type Script libraries are referenced in it.

Cordova Application

Cordova Application is a project template for building an Appache Cordova HTML/JS application based on the DevExtreme SPA Framework and DevExtreme widgets.

NOTE
The DevExtreme Cordova Application template is available only in Visual Studio 2015 and later vesions.

The Cordova Application project is a Basic Application project wrapped into a Blank App (Appache Cordova) project. The Basic Application files are stored in the "www" folder of the project. For more information of the Blank App (Appache Cordova) project, refer to the Tools for Appache Cordova documentation.

DevExtreme Cordova Application Structure

In addition to the Basic Application files, the DevExtreme Cordova Application project includes the "gruntfile.js" file that holds instructions for the task updating DevExtreme libraries. For more information on Grunt, refer to gruntjs.com.

The "bower.json" file contains information on the packages required for the DevExtreme SPA framework. Learn more about Bower at bower.io.

bower.json contents

Multi-Channel Application

Multi-Channel Application is a project template for building an HTML/JS application based on the DevExtreme SPA Framework and DevExtreme widgets. This project template is more helpful than the Basic Application project template in the following cases.

  • Creating a Multi-Channel Solution
    When you need to build different applications for desktop, iOS, Android, WindowsPhone8 and Windows8 using a shared code.

  • Creating an OData Bound Solution
    No matter which platforms you are going to support, the application will be bound to an OData service.

Watch Video

When you select the Multi-Channel Application template in the New Project dialog, the DevExtreme Project Wizard runs. Using this wizard, you can create both a multi-channel solution and generate views for the entities from the specified OData service.

On the first page of the DevExtreme Project Wizard, choose the "channels" to be supported by the application by checking corresponding items.

DevExtreme Project Wizard First Page

In the image above, the Web and Mobile "channels" are chosen. The Win items are disabled when you don't work on Windows8 or higher. The WinPhone item is disabled when you don't work on Windows8 or higher and don't have the Windows Phone 8.0 Developer Tools SDK installed.

NOTE
If you cannot create the WinPhone project because the required environment is not available, use the Mobile project template to get an application for WinPhone. Just develop the application using the corresponding styles and layouts, and then pack it for the WinPhone platform. For details, refer to the Package for WinPhone topic.

The next Choose Layout step in the wizard allows you to choose the navigation layout to be used in the created applications by default.

DevExtreme Project Wizard First Page

After making the choice, click Next. You will go to the Choose Entities To Generate Views step. If you do not have an OData service for your applications, you can click Finish without specifying anything. In this instance a multi-channel solution will be generated with sample views.

If you are going to bind the application to an OData service and generate application views for entities, specify your OData Service by entering its URL or choosing the one that is already added to the current solution (if you add a DevExtreme project to a solution). Click Discover. A list of entities exposed by your service will be displayed. Check the entities for which you want to generate views.

DevExtreme Project Wizard Third Page

Press Finish.

The following projects are created for the corresponding "channels" selected in the wizard.

DevExtreme Project Structure

Shared Project Desktop Project Mobile Project Windows Phone 8 Project Windows8 Project Zip for PhoneGap Build Package for Android
Package for iOS Package for Windows Phone 8

These projects have the structure of a basic project template. If you specified an OData service to be used as a data source, views will be generated for the entities. View Models will be located in the db folder of the Shared project. Views and ViewModels are the .dxView and JavaScript files that will be added to the Views folder of the generated projects. The .dxView file is the HTML file that can be opened using the View Designer.

Shared Project

This project is always created, regardless of the "channel(s)" you chose in the DevExtreme Project Wizard. This project is referenced in all other projects because it contains shared code. For instance, if you have more than one project in your solution (e.g., mobile and win8 projects), the views that are intended for all of these projects can be defined once - within the Shared project. At the same time, you can modify a file in any project that references the Shared project. In this instance, the customized version will be used in the running project.

In the data folder, you can find the db.js file. In this file, a template for creating an ODataContext is realized. The ODataContext instance is created to communicate with an OData service. ODataContext creates a set of ODataStore objects inside to communicate with each entity provided by the OData service. To specify a URL to the required service and list the entities required for the application, a configuration object is passed as a parameter to the ODataContext constructor.

JavaScript
Application1.db = new DevExpress.data.ODataContext(serviceConfig.db);

In the project template, a configuration object is accessed as the object provided by the db field of the serviceConfig object. If you need to create an OData context for an additional OData service, add one more field to the serviceConfig object.

JavaScript
{
    db: {
        url: endpointSelector.urlFor("db"),
        "entities": {},
        errorHandler: handleServiceError
    }
}

To get the required URL - for local or productional use - the urlFor("db") method of the endpointSelector object is called. This method returns a local URL if the application runs on a local host, otherwise a productional URL is returned. The possible URLs for the "db" service are specified in the endpointSelector's configuration object.

JavaScript
var endpointSelector = new DevExpress.EndpointSelector(Application1.config.endpoints);

//see the application1.shared.config.js file
"endpoints": {
    "db": {
        "local": "",
        "production": ""
    }
},

If you specify a certain OData service and choose the required entities in the Project Wizard, the service URL and entities will be specified in the created project and the created ODataContext will be ready to use. Otherwise, an empty template for ODataContext will be created so that you can configure it manually.

If you are going to use a data service of another type, simply remove the default content from the db.js and application1.shared.config.js files. Learn how to provide data using the DevExtreme data layer in the Data Layer documentation section.

Desktop Project

This project is created when you choose Web in the DevExtreme Project Wizard and is intended to create an application for a desktop. For this purpose, it includes the Desktop built-in layout (see the Layouts folder), a generic light/dark predefined theme (see the css folder) and has a "webSite" application mode.

Generally, the Desktop project has the same structure as the basic project template. In addition, it references the Shared project, so the files (e.g., Views) from the Shared project are copied to the Desktop project. If the same files are found, the files from the Desktop project overwrite the files from the Shared project.

NOTE
In the Desktop project, a configuration object for the application object gets values for some options from the app.config.js file. Do not change this behavior, because the information contained in the app.config.js file is used when a view is displayed in the View Designer.

Mobile Project

This project is created when you choose Mobile in the DevExtreme Project Wizard and is intended to create an application for mobile devices. For this purpose, it includes predefined layouts that are designed for Android, iOS and Win8Phone platforms, along with style sheets that are required for different mobile devices to give an application its native looks. You can define different views for different platforms and device forms. To learn how to do this, refer to the Views and Layouts article.

The application created using the Mobile project can be packaged for iOS, Android, Win8Phone and PhoneGap. To learn how to do this, refer to the Packaging Tools section.

WinPhone Project

This project is created when you choose WinPhone in the DevExtreme Project Wizard and is intended for building mobile applications for the WinPhone platform. This project is created using a standard template for WinPhone applications. The Mobile project, however, is linked to its www folder. All the files in this folder represent links to corresponding files in the Mobile project. Use the Mobile project to create an application for WinPhone, but build the WinPhone project for deployment to the device.

To package an application created using the Win8Phone project, use procedures standard for WinPhone VS projects Packaging your Windows Store app using Visual Studio 2012).

Win Project

When choosing Win in the DevExtreme Project Wizard, a project for the Windows platform is created. This project has a standard template for Win applications. In addition, this project has links to files from the Shared project. This makes it possible for you to develop a DevExtreme application for Windows.

To package an application created using the Win project, use standard procedures (see Packaging your Windows Store app using Visual Studio 2012).

ASP.NET MVC Application

To create an ASP.NET MVC application that involves DevExtreme widgets, use the ASP.NET MVC 5 Application project template. It allows you to employ DevExtreme ASP.NET MVC Wrappers for configuring DevExtreme widgets.

Folders in this project template have a structure typical for an ASP.NET MVC application. Their standard contents are extended by scripts, libraries and stylesheets required by DevExtreme ASP.NET MVC Wrappers and DevExtreme itself.

WCF OData Service

To create a WCF OData Service, use the template that is provided by DevExtreme. When choosing the DevExtreme WCF OData Service template in the New Project dialog, a standard Entity Data Model Wizard runs. The project that is generated by this wizard is extended by CORS and JSONP support.

After you are finished with the OData service project, add a DevExtreme project to the solution using the Basic Application or Multi-Channel Application template. In the DevExtreme Multi-Channel Application project wizard, you will be able to choose the OData service from the current solution and generate views for the entities exposed by this service.

Web API OData Service

To create a Web API OData Service, use the appropriate template provided by DevExtreme. When choosing the DevExtreme Web API OData Service template in the New Project dialog, a standard Entity Data Model Wizard runs. The project that is generated by this wizard is extended by CORS and JSONP support.

After you are finished with the OData service project, add a DevExtreme project to the solution using the Basic Application or Multi-Channel Application template. In the DevExtreme Project Wizard, you will be able to choose the OData service from the current solution and generate views for the entities exposed by this service.

Set a Custom Namespace

When you use a project template for an application, the application's namespace is generated automatically. You may need to use a custom namespace. In this topic, you will learn specific notes on how to set a custom namespace for the DevExtreme SPA Framework-based applications created using the Basic Application or Multi-Channel Application project templates.

To change the namespace of an application project on the stage on which the project has certain implemented content, do the following.

  • Change the application namespace.
    Set the namespace option of the HtmlApplication project to the new namespace name.

  • Change the namespace of the functions implemented in the project.
    In particular, pay attention to the functions that return ViewModel objects.

  • Set the new namespace for the views that will be added by the Add | New Item... dialog further.
    The template that is used by the Add | New Item... dialog for creating views has a JavaScript file. In this file, there is a function that returns a ViewModel for the view. The namespace for this function is the project name by default. To change the default namespace to a custom one, use the Root namespace property of the application project.

    Root Namespace