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: the Basic Application and Multi-Channel Application templates. 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.

Basic Application

When you choose Basic Application in the New Project dialog, a solution with a DevExtreme application project is created. This project has a basic structure that is common for applications based on the DevExtreme framework. To learn more, refer to the Application Project article.

DevExtreme_BasicProject

This application structure is detailed in the Application Project article. The only difference is that the following files are added to the VS DevExtreme application.

  • data - a folder containing everything that is related to data, e.g., variables to which data is loaded/stored;

  • app.config.js - a file that includes the configuration object used to initialize the application.

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 desktop or packaged for iOS, Android, Win8Phone, Tizen and PhoneGap. For details, refer to the Packaging documentation section.

Basic Application (Type Script)

When you choose Basic Application (Type Script) in the New Project dialog, a Type Script solution with a DevExtreme application project is created. This project is the same as the Basic Application project, but the Type Script language is used in it and the required Type Script libraries are referenced in it.

Multi-Channel Application

Use the Multi-Channel Application project template in the following cases.

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.

Create a Multi-Channel Solution

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 Win8 items are disabled when you don't work on Windows8. The WinPhone8 item is disabled when you don't work on Windows8 and don't have the Windows Phone 8.0 Developer Tools SDK installed.

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

The next step in the wizard allows you to choose the navigation layout to be used in the created applications by default. After making the choice, click Next to bind the applications to an OData service and generate views for entities. This will be detailed below. If you do not have an OData service for your applications, finish the wizard by clicking 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
Package for Tizen

  • Shared Project
    This project is always created, regardless of the "channel(s)" you chose in the DevExtreme Project Wizard. This project is also 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.

    The Shared project includes the About view. You can modify it so that it displays information about your application and you can customize it (the view) in one of your projects. In this instance, the customized version will be used in the running project. This principle is valid for all files in the Shared project. They can be overridden in any project that references the Shared 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 Desktop project.

    NOTE: In the Desktop project, a configuration object for the application object gets values for some options from the config.js file. Do not change this behavior, because the information contained in the 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, tizen and win8 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, Tizen and PhoneGap. To learn how to do this, refer to the Packaging section.

    NOTE: The mobile project includes the navigation.html view, which is required for building a native Win8Phone application where navigation must be represented by the start-up view.

  • Win8Phone Project
    This project is created when you choose WinPhone8 in the DevExtreme Project Wizard and is intended for building mobile applications for the Win8Phone platform. This project is created using a standard template for Win8Phone 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 Win8Phone, but build the Win8Phone project for deployment to the device.

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

  • Win8 Project
    When choosing Win8 in the DevExtreme Project Wizard, a project for the Windows 8 platform is created. This project has a standard template for Win8 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 8.

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

Create an OData-Bound Solution

If you are going to bind your application to an OData service, move to the next step of the DevExtreme Project Wizard once you choose the platforms and the default navigation layout.

DevExtreme Project Wizard Third Page

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. The framework that will run the application supports the Model-View-ViewModel (MVVM) pattern. So, the views that will be created from your service's entities will be represented by their Model, View and ViewModel.

Click Finish. The projects that will be added to the solution will have the structure of a basic project template. Generated, 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. To learn more about the View Designer, refer to the Design-Time Features documentation section.

To work with your OData service, an ODataContext object based on the URL you specified will be created. See Shared project description for details.

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

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 or Multi-Channel 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.

Extend Your Solution

While developing an application created using one of the DevExtreme templates, you may be required to add an additional project specific to a particular device(s). For instance, when you have an application created using the Multi-Channel Application template, you may need to add a new project that will use the code implemented in your Shared project. DevExtreme solutions are easily extensible. Read below to learn how to add new DevExtreme projects to a solution.

In addition, the set of views that was generated by the DevExtreme Project Wizard can be extended any time when you need to add a new view. This relates to the views that were created for the entities of your OData service as well. Read below to learn how to do this.

Add a DevExtreme Project

Follow the steps below to add a DevExtreme project to your solution.

  • Right-click the solution and choose Add | New Project.... The Add New Project dialog will be invoked.

  • In the Projects tree view, select DevExtreme. In the Templates list view, choose the Basic Application project template. Specify a name for the project and click OK.

    Add New Project

  • If you have the Shared project in your solution and want to use it in the newly added project, add a reference to it.

  • To make the newly added project specific to a certain device(s), use the DevExpress.devices.current() method passing the required device as a parameter.

A DevExtreme project can be built for the desktop or packaged for iOS, Android, Windows8Phone, Tizen and PhoneGap. For details, refer to the Packaging documentation section.

Add a Win8Phone Project

Follow these steps to add a DevExtreme Win8Phone project to your solution.

  • Download a project template for the Win8Phone from the PhoneGap site.

  • Right-click your solution and choose Add | New Project.... The Add New Project dialog will be invoked.

  • In the Templates list view, choose the downloaded Win8Phone template. Specify a name for the project and click OK.

  • Find the www folder and remove the index.html file from it, if any.

  • Right-click the project (most likely the Mobile project) that you want to link to the Win8Phone project. Choose Link To in the invoked context menu. Within the suggested project, choose the newly added Win8Phone project's www folder. Links to all the files of the linked project and the files of the projects that are referenced in the linked project will be added to the Win8Phone project.

Add a Win8 Project

Follow the steps below to add a DevExtreme Win8 project to your solution.

  • Right-click your solution and choose Add | New Project.... The Add New Project dialog will be invoked.

  • Choose the JavaScript language, the Windows Store category and the required template. Specify a name for the project and click OK.

  • Remove the index.html file from the added project, if any.

  • Right-click the project (most likely the Shared project) that you want to link to the Win8 project. Choose Link To in the invoked context menu. Within the suggested project, choose the newly added Win8 project. Links to all the files of the linked project and the files of the projects that are referenced in the linked project will be added to the Win8 project.

Add a View

Follow these steps to add a view to your project.

  • Right-click a project in the DevExtreme solution and choose Add | New Item... The Add New Item dialog will be invoked.

    Add New Item

  • Select the View template, give it a name and press Add. The .dxView, .js and .css files will be added to the project and links to them will be added to the application page (see the index.html file). The .dxView file is an HTML file that can be opened using a Designer.

    If you use an OData service in your project, the View Creation Wizard will run after you press Add in the Add New Item dialog.

    View Creation Wizard

    As you can see, you can choose to create an empty view or generate a view for an entity from your OData service. In the latter case, the wizard will help you choose an entity and view type.

    View Creation Wizard

  • Make the newly added view specific to a certain device(s) (optionally). To learn how to do this, refer to the Device Specific Markup article.

Set a Custom Namespace

To change the namespace of the 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