# Quick Start Tutorial

## Live example

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

{% hint style="success" %}
[Getting Started](https://demos.dikesoft.com/dk-grid/getting-started) live example.
{% endhint %}

## 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](https://angular.io/guide/setup-local) for Angular development.

{% hint style="warning" %}
The **DkGrid Library** has the following Angular packages as peer dependencies:

* @angular/common
* @angular/core
* @angular/forms
* @angular/cdk
* @angular/material
* rxjs
  {% endhint %}

{% hint style="success" %}
At the time of this writing, we support **Angular v12**, **v13**, and **v14**.
{% endhint %}

## 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](https://material.angular.io/guide/getting-started), 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. 

{% hint style="info" %}
For this tutorial, you can select a [pre-built material design theme](https://material.angular.io/guide/theming#using-a-pre-built-theme).
{% endhint %}

## 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
```

{% hint style="success" %}
If you are using the **Community Edition**, run the following command: 

npm i @dk-grid-community/angular
{% endhint %}

{% hint style="info" %}
Be aware of pulling the correct version according to your Angular version.
{% endhint %}

### Adding the DkGrid Angular module

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

{% code title="app.module.ts" lineNumbers="true" %}

```typescript
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 { }

```

{% endcode %}

{% hint style="warning" %}
If your data set has date fields, do not forget to import the <mark style="color:green;">MatNativeDateModule</mark> or a custom implementation instead.

Internally, the DkGrid uses the native <mark style="color:green;">Date</mark> type. Therefore, your custom implementation must also manage date fields using the native <mark style="color:green;">Date</mark> type.
{% endhint %}

## 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.

<table><thead><tr><th width="338.11648644704013">Theme</th><th width="150">Scheme</th><th>Palettes</th></tr></thead><tbody><tr><td><code>deeppurple-amber.css</code></td><td>Light</td><td>deep-purple, amber, red</td></tr><tr><td><code>indigo-pink.css</code></td><td>Light</td><td>indigo, pink, red</td></tr><tr><td><code>pink-bluegrey.css</code></td><td>Dark</td><td>pink, bluegrey, red</td></tr><tr><td><code>purple-green.css</code></td><td>Dark</td><td>purple, green, red</td></tr></tbody></table>

{% hint style="info" %}
We use a pre-built theme for this tutorial, but you can customize the DkGrid theming.
{% endhint %}

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:

{% code title="styles.scss" lineNumbers="true" %}

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

{% endcode %}

### Adding the CSS file to the styles array

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

{% code title="angular.json" lineNumbers="true" %}

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

{% endcode %}

## 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.

{% tabs %}
{% tab title="app.component.html" %}
{% code lineNumbers="true" %}

```markup
<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>
```

{% endcode %}
{% endtab %}

{% tab title="app.component.ts" %}
{% code lineNumbers="true" %}

```typescript
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: 'dolores.zieme@gmail.com',
        hireDate: new Date(2020, 7, 6)
    }, {
        employeeId: '0f1bc4f3-f746-489a-9c24-eb570a16e556',
        firstName: 'Celia',
        lastName: 'Mertz',
        gender: 'female',
        age: 55,
        email: 'celia.mertz@gmail.com',
        hireDate: new Date(2010, 5, 11)
    }, {
        employeeId: '88acf950-dee5-480a-a67e-1b0419c9a473',
        firstName: 'Jeffery',
        lastName: 'Renner',
        gender: 'male',
        age: 60,
        email: 'jeffery.renner@hotmail.com',
        hireDate: new Date(2016, 11, 22)
    }, {
        employeeId: '03a4e13f-98b4-4998-a40b-b66a832f327e',
        firstName: 'Annette',
        lastName: 'Satterfield',
        gender: 'female',
        age: 37,
        email: 'annette.satterfield@yahoo.com',
        hireDate: new Date(2019, 5, 2)
    }, {
        employeeId: 'a800045a-5127-4a5f-b93f-635f162ad376',
        firstName: 'Geraldine',
        lastName: 'Weimann',
        gender: 'female',
        age: 42,
        email: 'geraldine.weimann@hotmail.com',
        hireDate: new Date(2016, 10, 19)
    }] as Partial<Employee>[];
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

Adding the <mark style="color:red;">`dk-grid`</mark> selector to the `app.component.html` file, we have created a new instance of type <mark style="color:green;">`DkGridComponent`</mark>.

### Column definitions

You can create columns using instances of type <mark style="color:green;">`DkGridColumnComponent`</mark> via templating.

{% hint style="info" %}
You can define columns in code as well
{% endhint %}

A basic column definition consists of:

<table><thead><tr><th width="198.3097476496784">Property name</th><th width="427.4285714285714">Description</th></tr></thead><tbody><tr><td><code>fieldName</code></td><td>The name of the field in the data source.</td></tr><tr><td><code>headerText</code></td><td>The visible label for the given column.</td></tr><tr><td><code>dataType</code></td><td>Data type could be <mark style="color:red;"><code>Text</code></mark>, <mark style="color:red;"><code>Numeric</code></mark>, <mark style="color:red;"><code>Date</code></mark> or <mark style="color:red;"><code>Binary</code></mark>.</td></tr></tbody></table>

{% hint style="info" %}
If you do not provide the <mark style="color:orange;">`width`</mark> property, as the hire column, the **default** value is **200**.

The <mark style="color:orange;">`width`</mark> value is given in **pixels**.
{% endhint %}

### Binding the Datasource

The DkGrid component defines an input property called <mark style="color:orange;">`datasource`</mark>. The type of the <mark style="color:orange;">`datasource`</mark> property is a union type called <mark style="color:green;">`DkGridDataSourceInput`</mark>.

{% code lineNumbers="true" %}

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

{% endcode %}

According to the <mark style="color:green;">`DkGridDataSourceInput`</mark> definition, a simple array is provided for this tutorial, adding five rows with a shape of a partial <mark style="color:green;">`Employee`</mark> interface.

### Displaying the output

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

![DkGrid - Basic configuration output](https://3888584995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpDxfe6pgRLqBLMQgZ0kG%2Fuploads%2Fihir3w6cEw5oUmCNPvsT%2Fgetting-started-basic-conf.png?alt=media\&token=e8e1641a-c87d-421b-9a29-3cf0b44b09b8)

## 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.&#x20;

{% hint style="info" %}
DkGrid lets you customize both types of filters.
{% endhint %}

{% hint style="success" %}
We have enabled **In-line Filters** for this tutorial.
{% endhint %}

Open the file `app.component.html` and add the property <mark style="color:orange;">`allowRowFiltering`</mark> to the <mark style="color:green;">`DkGridComponent`</mark> instance. For the sake of brevity, we only show the <mark style="color:red;">`dk-grid`</mark> selector.

{% code title="app.component.html" lineNumbers="true" %}

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

{% endcode %}

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](https://3888584995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpDxfe6pgRLqBLMQgZ0kG%2Fuploads%2FR3L16DcnjfLkV6fDs2IC%2Fgetting-started-row-filter.png?alt=media\&token=4f985037-5394-454b-818a-571fa3d29634)

### 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 <mark style="color:red;">`dk-grid`</mark> selector, add the property <mark style="color:orange;">`allowSorting`</mark>.
2. And for every column you want to be sortable, add the property <mark style="color:orange;">`sortable`</mark>.

For the sake of brevity, we only show the <mark style="color:red;">`dk-grid`</mark>, and the target <mark style="color:red;">`dk-grid-column`</mark> selectors.

{% code title="app.component.html" lineNumbers="true" %}

```markup
<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>
```

{% endcode %}

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.

{% hint style="info" %}
Sorting is applied one column at a time.
{% endhint %}

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

![Sorting functionality](https://3888584995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpDxfe6pgRLqBLMQgZ0kG%2Fuploads%2F4ih2R216HZUxXPjxe9Sm%2Fgetting-started-sorting.png?alt=media\&token=d9353f41-f140-4512-8c8c-d6dd6038b52a)

## 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 <mark style="color:orange;">`gridElevation`</mark> and <mark style="color:orange;">`striped`</mark> properties to the <mark style="color:red;">`dk-grid`</mark> selector.

{% code title="app.component.html" lineNumbers="true" %}

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

{% endcode %}

Same as before, we only show the <mark style="color:red;">`dk-grid`</mark> selector for brevity.

Your DkGrid instance will look like the following output:

![Material Elevation and highlighted rows](https://3888584995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpDxfe6pgRLqBLMQgZ0kG%2Fuploads%2F3pPhITP3CgZTn9TrEmd3%2Fgetting-started-ui-features.png?alt=media\&token=b556ff52-8852-4720-b192-4abfd4f8efae)

{% hint style="info" %}
By default, adding the <mark style="color:orange;">`gridElevation`</mark> flag will show an elevation with a value of two.
{% endhint %}

{% hint style="info" %}
You can change the elevation, providing a number between **0** to **24**. You provide this value through a property called <mark style="color:orange;">`gridElevationValue`</mark>.
{% endhint %}

## 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.