Quick Start Tutorial

This section summarizes all the essentials you need to know to start with DkGrid. Here you can find how to create a DkGrid instance, add some columns, and enable some features.

Live example

After completing this tutorial, you will get something similar to the live example.

Getting Started live example.

Creating an Angular app

Before using the DkGrid Library, you must create an Angular app. Then, follow the steps described in the Angular official docs to set up your local environment for Angular development.

The DkGrid Library has the following Angular packages as peer dependencies:

• @angular/common

• @angular/core

• @angular/forms

• @angular/cdk

• @angular/material

• rxjs

At the time of this writing, we support Angular v12, v13, and v14.

Adding Angular Material

Since the DkGrid Library uses some CDK packages and many Angular Material components, you must install the Angular Material package.

Following the Angular Material official docs, in the root of your Angular app, open a terminal and run the following command:

ng add @angular/material

The ng-add command will install Angular Material, the Component Dev Kit (CDK), and Angular Animations. During the installation process, some questions will be prompted.

For this tutorial, you can select a pre-built material design theme.

Adding DkGrid to your project

Installing the NPM package

We distribute the DkGrid Library as NPM package. Once you have set up your Angular environment, you can add the DkGrid Library to your project.

At the root of your project, open a terminal and run the following command:

npm i @dk-grid-standard/angular

If you are using the Community Edition, run the following command:

npm i @dk-grid-community/angular

Be aware of pulling the correct version according to your Angular version.

Adding the DkGrid Angular module

After installing the corresponding DkGrid NPM package in your development environment, add the DkGrid module to the app module.

app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { MatNativeDateModule } from '@angular/material/core';
import { DkDataGridModule } from '@dk-grid-standard/angular';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    MatNativeDateModule,
    
    DkDataGridModule
  ],
  providers: [ ],
  bootstrap: [AppComponent],
})
export class AppModule { }

If your data set has date fields, do not forget to import the MatNativeDateModule or a custom implementation instead.

Internally, the DkGrid uses the native Date type. Therefore, your custom implementation must also manage date fields using the native Date type.

Adding the DkGrid Styles

The DkGrid package comes with four pre-built theme CSS files. Each of them uses the same palettes as Angular Material pre-built themes. Indeed the file names are the same.

Theme	Scheme	Palettes
deeppurple-amber.css	Light	deep-purple, amber, red
indigo-pink.css	Light	indigo, pink, red
pink-bluegrey.css	Dark	pink, bluegrey, red
purple-green.css	Dark	purple, green, red

We use a pre-built theme for this tutorial, but you can customize the DkGrid theming.

You can add the DkGrid styles in two ways: importing the CSS file directly in the styles.scss file or adding the entry in the styles array from the angular.json file.

Importing the CSS file

Open the styles.scss file and add the following line:

styles.scss

@import "@dk-grid-standard/angular/prebuilt-themes/indigo-pink.css";

Adding the CSS file to the styles array

Open the angular.json file and add the following entry to the styles array:

angular.json

"styles": [
   "node_modules/@dk-grid-standard/angular/prebuilt-themes/indigo-pink.css",
   "src/styles.scss"
]

DkGrid basic configuration

The next step is declaring a basic configuration to display some columns. Then, add the following code to app.component.html and app.component.ts files and remove the scaffolding code.

app.component.html

<dk-grid id="basic-conf-grid" height="500px"
  [datasource]="dkgDataSource">

    <dk-grid-column
        fieldName="employeeId"
        headerText="Employee Id"
        dataType="Text"
        width="350">
    </dk-grid-column>
    
    <dk-grid-column
        fieldName="firstName"
        headerText="Name"
        dataType="Text"
        width="150">
    </dk-grid-column>

    <dk-grid-column
        fieldName="lastName"
        headerText="Surname"
        dataType="Text"
        width="150">
    </dk-grid-column>

    <dk-grid-column
        fieldName="gender"
        headerText="Gender"
        dataType="Binary"
        width="110">
    </dk-grid-column>

    <dk-grid-column
        fieldName="age"
        headerText="Age"
        dataType="Numeric"
        contentAlign="center"
        width="85">
    </dk-grid-column>

    <dk-grid-column
        fieldName="email"
        headerText="Email"
        dataType="Text"
        width="300">
    </dk-grid-column>

    <dk-grid-column
        fieldName="hireDate"
        headerText="Hire Date"
        dataType="Date">
    </dk-grid-column>

</dk-grid>

app.component.ts

import { Component, OnInit } from '@angular/core';
import { DkGridDataSourceInput } from '@dk-grid-standard/angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {

  dkgDataSource: DkGridDataSourceInput<Partial<Employee>>;

  constructor() { }

  ngOnInit(): void {
    this.dkgDataSource = [{
        employeeId: '43c8a235-a95d-4e3e-bc30-f31ff33d490d',
        firstName: 'Dolores',
        lastName: 'Zieme',
        gender: 'female',
        age: 51,
        email: '[e-mail]',
        hireDate: new Date(2020, 7, 6)
    }, {
        employeeId: '0f1bc4f3-f746-489a-9c24-eb570a16e556',
        firstName: 'Celia',
        lastName: 'Mertz',
        gender: 'female',
        age: 55,
        email: '[e-mail]',
        hireDate: new Date(2010, 5, 11)
    }, {
        employeeId: '88acf950-dee5-480a-a67e-1b0419c9a473',
        firstName: 'Jeffery',
        lastName: 'Renner',
        gender: 'male',
        age: 60,
        email: '[e-mail]',
        hireDate: new Date(2016, 11, 22)
    }, {
        employeeId: '03a4e13f-98b4-4998-a40b-b66a832f327e',
        firstName: 'Annette',
        lastName: 'Satterfield',
        gender: 'female',
        age: 37,
        email: '[e-mail]',
        hireDate: new Date(2019, 5, 2)
    }, {
        employeeId: 'a800045a-5127-4a5f-b93f-635f162ad376',
        firstName: 'Geraldine',
        lastName: 'Weimann',
        gender: 'female',
        age: 42,
        email: '[e-mail]',
        hireDate: new Date(2016, 10, 19)
    }] as Partial<Employee>[];
  }
}

Adding the dk-grid selector to the app.component.html file, we have created a new instance of type DkGridComponent.

Column definitions

You can create columns using instances of type DkGridColumnComponent via templating.

You can define columns in code as well

A basic column definition consists of:

Property name	Description
fieldName	The name of the field in the data source.
headerText	The visible label for the given column.
dataType	Data type could be Text, Numeric, Date or Binary.

If you do not provide the width property, as the hire column, the default value is 200.

The width value is given in pixels.

Binding the Datasource

The DkGrid component defines an input property called datasource. The type of the datasource property is a union type called DkGridDataSourceInput.

// DkGridDataSourceInput definition:
type DkGridDataSourceInput<T extends object> = DataSource<T> | 
    DkDataSource<T> | DkGridDataSource<T> | 
    Observable<ReadonlyArray<T> | T[]> | 
    ReadonlyArray<T> | T[];

According to the DkGridDataSourceInput definition, a simple array is provided for this tutorial, adding five rows with a shape of a partial Employee interface.

Displaying the output

If everything goes well, you will see an output similar to the following screenshot:

DkGrid - Basic configuration output

Exploring more functionalities

So far, we have provided the minimum number of properties. Now it is time to explore more functionalities and how easy it is to enable them.

Enabling In-line Filters

The set of rows for this tutorial is minimal, but you probably load hundreds or even thousands of rows in an actual application.

Filtering rows is a must-have for any enterprise application. The DkGrid allows two types of filters:

1. In-line Filters. It displays a row under the column headers, allowing the user to type the search term for each column.

2. Column Filters. It will enable the user to enter more than one condition for each column.

DkGrid lets you customize both types of filters.

We have enabled In-line Filters for this tutorial.

Open the file app.component.html and add the property allowRowFiltering to the DkGridComponent instance. For the sake of brevity, we only show the dk-grid selector.

app.component.html

<dk-grid id="basic-conf-grid" height="500px"
   allowRowFiltering
   [datasource]="dkgDataSource">
</dk-grid>

The following screenshot shows the result of allowing the row filter. We have highlighted the row under the headers with a red square. Moreover, we typed the letter d as a filter.

Enabling In-line Filters

Enabling Sorting

For allowing the sort function for every desired column, you should enable sorting at the grid level, then at the column level.

Open the file app.component.html and add the following:

1. For the dk-grid selector, add the property allowSorting.

2. And for every column you want to be sortable, add the property sortable.

For the sake of brevity, we only show the dk-grid, and the target dk-grid-column selectors.

app.component.html

<dk-grid id="basic-conf-grid" height="500px"
    allowRowFiltering
    allowSorting
    [datasource]="dkgDataSource">

    <dk-grid-column
        fieldName="employeeId"
        headerText="Employee Id"
        dataType="Text"
        width="350"
        sortable>
    </dk-grid-column>

    <dk-grid-column
        fieldName="firstName"
        headerText="Name"
        dataType="Text"
        width="150"
        sortable>
    </dk-grid-column>
</dk-grid>

When you hover the mouse over the column header, you will see an arrow indicating that you can sort the DkGrid rows through this column.

If you click on the column header, you sort the DkGrid rows, and a white arrow indicates the sorting operation.

If you click more than one time:

1. The first click will order the data set in ascending way.

2. The second click will invert the order meaning that the data set is ordered in descending mode.

3. With the third click, the data set will not be ordered through the given column anymore.

Sorting is applied one column at a time.

After applying the sorting properties, you will get something that looks like the following:

Sorting functionality

Other features

You can customize more features using a DkGrid component. In this section, we explore two more features regarding the UI.

Material Elevation / Highlighting the odd rows

Since we base the DkGrid definition on Angular Material, you can add elevation to the DkGrid component.

When the user is working with a large data set, it is helpful to distinguish one row from the other. To accomplish it, add a flag at the level of the grid.

Open the file app.component.html and add the gridElevation and striped properties to the dk-grid selector.

app.component.html

<dk-grid id="basic-conf-grid" height="500px"
    allowRowFiltering
    allowSorting
    striped
    gridElevation
    [datasource]="dkgDataSource">
</dk-grid>

Same as before, we only show the dk-grid selector for brevity.

Your DkGrid instance will look like the following output:

Material Elevation and highlighted rows

By default, adding the gridElevation flag will show an elevation with a value of two.

You can change the elevation, providing a number between 0 to 24. You provide this value through a property called gridElevationValue.

Summary

In this tutorial, we learned how to define columns and bind some data for displaying it using a DkGrid instance. In addition, we have managed grid filtering and sorting and some UI features, including grid styling. But, of course, the best thing is how easy it is to enable these features.