DevExtreme Angular - Create a DevExtreme Application
If you are starting a project from scratch, use the DevExtreme Angular Template. It is a simple application with a navigation menu and several sample views in a responsive layout (see live preview).
You can generate the application with the DevExtreme CLI:
npx -p devextreme-cli devextreme new angular-app app-name cd app-name npm run start
The application already contains the DataGrid and Form UI components. You can find their configurations in the src\pages\display-data\display-data.component.html
and src\pages\profile\profile.component.html
files correspondingly. The following instructions show how to employ any other DevExtreme UI component using the Button UI component as an example:
Import the DevExtreme UI component's module in the
NgModule
where you are going to use it. Open thesrc\app\app-routing.module.ts
file and add the following code:app-routing.module.ts// ... import { ..., DxButtonModule } from 'devextreme-angular'; @NgModule({ imports: [ ..., DxButtonModule ], // ... }) export class AppModule { }
Configure the DevExtreme UI component in the markup. Add the following code to the
src\app\pages\home\home.component.html
file:home.component.html<!-- ... --> <dx-button text="Click me" (onClick)="helloWorld()"> </dx-button> <!-- ... -->
Declare callback functions, event handlers, and binding properties in the application class. In this example, we declare the onClick event handler in the
src\app\pages\home\home.component.ts
file:home.component.ts// ... export class AppComponent { helloWorld() { alert('Hello world!'); } }
If you go to the Home view in the browser, you should see the Button.
For further information about DevExtreme Angular components, refer to the following resources:
For more information about the structure and contents of the DevExtreme Angular Template, continue reading this article.
Layouts
The application includes two layouts. The only difference between them is where the toolbar is located.
Outer Toolbar (default)
Inner Toolbar
To generate a new application with an inner toolbar, set the --layout
flag to side-nav-inner-toolbar
:
npx devextreme-cli new angular-app app-name --layout=side-nav-inner-toolbar
To switch to another layout after the application is created, open the src\app\app.component.html
file and replace the app-side-nav-outer-toolbar
element with app-side-nav-inner-toolbar
:
<app-side-nav-inner-toolbar title="{{appInfo.title}}"> <!-- Layout content is here --> </app-side-nav-inner-toolbar>
Add a New View
Run the following command to add a new view. --icon
specifies an icon from the DevExtreme icon library.
npx devextreme add view view-name [--icon=IconName]
You can find the added view under the src\app\pages
folder. This command also creates a navigation menu item for the added view in the src\app\app-navigation.ts
file.
Configure Menu Items
Edit the src\app\app-navigation.ts
file to configure navigation menu items. Each item configuration can have the following fields:
text - the item's text
icon - the item's icon
path - a navigation path associated with the item
items - child items
{ text: 'Category', icon: 'folder', items: [{ text: 'About', path: '/about' }] }
Hide the Menu in the Closed State
In the closed state, the navigation menu is partially visible because it displays item icons. If the items do not have icons, you can hide the menu. To do this, open the SideNavOuterToolbarComponent
or SideNavInnerToolbarComponent
(depending on the layout) and change the updateDrawer()
function as follows:
// ... export class SideNavInnerToolbarComponent implements OnInit { // ... updateDrawer() { // ... this.minMenuSize = 0; } }
Add a Custom Toolbar Item
The application template uses the DevExtreme Toolbar component. The Toolbar is part of the HeaderComponent
whose configuration is in the src\app\shared\components\header
directory. To add a custom toolbar item, open the header.component.html
file in this directory and add a dxi-item
element inside dx-toolbar
. Refer to the items help section for information on dxi-item
attributes.
The following code adds a search button to the toolbar:
<header> <dx-toolbar class="header-toolbar"> <!-- ... --> <dxi-item location="after" widget="dxButton" [options]="{ icon: 'search', onClick: startSearch }"> </dxi-item> <!-- ... --> </dx-toolbar> </header>
export class HeaderComponent { // ... @Output() search = new EventEmitter<void>(); startSearch = () => { this.search.emit(); } }
<app-header ... (search)="search()"> </app-header> <!-- ... -->
export class SideNavOuterToolbarComponent implements OnInit { // ... search() { console.log("search"); } }
In the code above, the button click handler is declared in the SideNavOuterToolbarComponent
. This component is applied when the outer toolbar layout is used. If the application uses the inner toolbar layout, add the same code to the SideNavInnerToolbarComponent
.
Switch the Theme
The DevExtreme Angular Template uses a main theme for the view content and an additional theme (color swatch) for the navigation menu. To switch to another theme, open the src\themes\metadata.base.json
or src\themes\metadata.additional.json
file and assign a theme name to the baseTheme
field:
{ // ... "baseTheme": "material.blue.light", // ... }
You can find all theme names in the Predefined Themes help topic.
Run the following command to rebuild themes:
npm run build-themes
Create a Custom Theme
You can use the DevExtreme ThemeBuilder to create custom themes based on predefined themes. Follow the steps below:
Import
src\themes\metadata.base.json
orsrc\themes\metadata.additional.json
to the ThemeBuilder.Export theme metadata to the initial file (see Postpone Customization).
Run the following command to rebuild themes:
npm run build-themes
Apply a Color Swatch
Color swatches are secondary color schemes used alongside a primary color scheme.
In the DevExtreme Angular Template, a color swatch is applied to the navigation menu and is configured in the src\themes\metadata.additional.json
file. To apply this color swatch to an element, add the dx-swatch-additional
class to this element:
<div class="dx-swatch-additional"> <!-- Your content here --> </div>
Apply Theme Variables to Custom Elements
Theme variables are defined in the src\themes\generated\variables.base.scss
and src\themes\generated\variables.additional.scss
files. Apply them to custom elements, so that the elements have a uniform appearance with the rest of the application.
The following code applies the $base-accent
variable as the background-color
of my-element
:
// Your SCSS file @import "../../../themes/generated/variables.base.scss"; #my-element { background-color: $base-accent; }
Internet Explorer 11 Support
To make the generated application work in Internet Explorer 11, do the following:
Install and enable polyfills
npm install --save classlist.js core-js
src/polyfills.ts// ... import 'core-js/es/array'; import 'classlist.js'; // ...
Include IE 11 as a supported browser
Open the .browserslistrc file and changenot IE 11
toIE 11
.Modify the
start
andbuild
commandspackage.json{ // ... "scripts": { // ... // "start": "ng serve", // "build": "ng build", "start": "node --max_old_space_size=4096 node_modules/@angular/cli/bin/ng serve --prod", "build": "node --max_old_space_size=4096 node_modules/@angular/cli/bin/ng build --prod", // ... } }
Lower the target ECMAScript version
tsconfig.json{ // ... // "target": "es2015", "target": "es5", // ... }
If you have technical questions, please create a support ticket in the DevExpress Support Center.