Skip to content

Commit

Permalink
Update Angular, Vue and React integration guides
Browse files Browse the repository at this point in the history
  • Loading branch information
@serhiipylypchuk1991
serhiipylypchuk1991 committed Aug 13, 2024
1 parent 2c388df commit 2d4f170
Show file tree
Hide file tree
Showing 3 changed files with 172 additions and 73 deletions.
228 changes: 159 additions & 69 deletions docs/guides/integration_with_angular.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,17 +24,17 @@ Create a new **my-angular-kanban-app** project using Angular CLI. Run the follow
ng new my-angular-kanban-app
~~~

The command above installs all the necessary tools and dependencies, so you don't need to run any additional commands.
The command above installs all the necessary tools, so you don't need to run any additional commands.

### Installation of dependencies

Go to the app directory:
Go to the new created app directory:

~~~json
cd my-angular-kanban-app
~~~

Run the app with the following commands:
Install dependencies and start the dev server. For this, use the [**yarn**](https://yarnpkg.com/) package manager:

~~~json
yarn install
Expand All @@ -53,69 +53,76 @@ Download the [**trial Kanban package**](/how_to_start/#installing-kanban-via-npm

### Step 2. Component creation

Now you need to create a component, to add a Kanban into the application. Create the **kanban** folder in the **src/app/** directory, add a new file into it and name it **kanban.component.ts**. Then complete the steps described below.
Now you need to create an Angular component, to add a Kanban with Toolbar into the application. Create the **kanban** folder in the **src/app/** directory, add a new file into it and name it **kanban.component.ts**.

#### Importing source files
#### Import source files

Open the file and import Kanban source files. Note that:
Open the **todo.component.ts** file and import Kanban source files. Note that:

- if you use PRO version and install the Kanban package from a local folder, the imported paths look like this:
- if you use PRO version and install the Kanban package from a local folder, the imported path look like this:

~~~jsx
import { Kanban } from 'dhx-kanban-package';
import { Kanban, Toolbar } from 'dhx-kanban-package';
~~~

- if you use the trial version of Kanban, specify the following paths:
- if you use the trial version of Kanban, specify the following path:

~~~jsx
import { Kanban } from '@dhx/trial-kanban';
import { Kanban, Toolbar } from '@dhx/trial-kanban';
~~~

In this tutorial you can see how to configure the **trial** version of Kanban.

#### Setting the container and adding Kanban
#### Set containers and initialize the Kanban with Toolbar

To display Kanban on the page, you need to set the container to render the component inside. Use the code below:
To display Kanban with Toolbar on the page, you need to set containers for Kanban and Toolbar, and initialize these components using the corresponding constructors:

~~~jsx title="kanban.component.ts"
import { Kanban } from '@dhx/trial-kanban';
import { Component, ElementRef, OnInit, ViewChild, OnDestroy} from '@angular/core';
~~~jsx {1,8-11,15-18,24-31} title="kanban.component.ts"
import { Kanban, Toolbar } from '@dhx/trial-kanban';
import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation} from '@angular/core';

@Component({
selector: 'kanban',
template: '<div #container></div>'
encapsulation: ViewEncapsulation.None,
selector: "kanban", // a template name used in the "app.component.ts" file as <kanban />
styleUrls: ["./kanban.component.css"],
template: `<div class="component_container">
<div #toolbar_container></div>
<div #kanban_container style="height: calc(100% - 56px);"></div>
</div>`
})
export class KanbanComponent implements OnInit {
@ViewChild('container', { static: true }) container!: ElementRef;
}
~~~

Then you need to render our Kanban in the container. To do that, use the `ngOnInit()` method of Angular:

~~~jsx {6-9} title="kanban.component.ts"
export class KanbanComponent implements OnInit, OnDestroy {
@ViewChild('container', { static: true }) container!: ElementRef;
// initialize container for Toolbar
@ViewChild("toolbar_container", { static: true }) toolbar_container!: ElementRef;
// initialize container for Kanban
@ViewChild("kanban_container", { static: true }) kanban_container!: ElementRef;

private _board!: any;
private _kanban!: Kanban;
private _toolbar!: Toolbar;

ngOnInit() {
const board = new Kanban(this.container.nativeElement,{});
this._board = board;
// initialize the Kanban component
this._kanban = new Kanban(this.kanban_container.nativeElement, {});

// initialize the Toolbar component
this._toolbar = new Toolbar(this.toolbar_container.nativeElement, {
api: this._kanban.api,
// other configuration properties
});
}

ngOnDestroy() {
this._board.destructor();
ngOnDestroy(): void {
this._kanban.destructor(); // destruct Kanban
this._toolbar.destructor(); // destruct Toolbar
}
}
~~~

In the above code you also specified the `ngOnDestroy()` method that contains the `_board.destructor()` expression to clear the component when it is no longer needed.

#### Loading data

To add data into Kanban, you need to provide a data set. You can create the **data.ts** file in the **src/app/kanban/** directory and add some data into it:

~~~jsx title="data.ts"
~~~jsx {2,14,37,48} title="data.ts"
export function getData() {
const columns = [
{
Expand All @@ -138,7 +145,7 @@ export function getData() {
start_date: new Date("01/07/2021"),
users: [3, 2],
column: "backlog",
type: "feature"
type: "feature",
},
{
label: "Archive the cards/boards ",
Expand All @@ -147,73 +154,157 @@ export function getData() {
users: [4],
progress: 1,
column: "backlog",
type: "feature"
type: "feature",
},
// ...
];

return {
columns,
cards
};
const rows = [
{
label: "Feature",
id: "feature",
},
{
label: "Task",
id: "task",
}
];

return { columns, cards, rows };
}
~~~

Then open the ***kanban.component.ts*** file. Import the file with data and specify the corresponding data properties to the configuration object of Kanban within the `ngOnInit()` method, as shown below.
Then open the ***kanban.component.ts*** file. Import the file with data and specify the corresponding data properties to the configuration object of Kanban within the `ngOnInit()` method, as shown below:

~~~jsx {2,6-9} title="kanban.component.ts"
// importing the data file
import { getData } from './data';
~~~jsx {2,23,25-27} title="kanban.component.ts"
import { Kanban, Toolbar } from '@dhx/trial-kanban';
import { getData } from "./data"; // import data
import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation} from '@angular/core';

ngOnInit() {
const { cards, columns } = getData();
const board = new Kanban(this.container.nativeElement, {
columns,
cards
});
@Component({
encapsulation: ViewEncapsulation.None,
selector: "kanban", // a template name used in the "app.component.ts" file as <kanban />
styleUrls: ["./kanban.component.css"],
template: `<div class="component_container">
<div #toolbar_container></div>
<div #kanban_container style="height: calc(100% - 56px);"></div>
</div>`
})

export class KanbanComponent implements OnInit, OnDestroy {
@ViewChild("toolbar_container", { static: true }) toolbar_container!: ElementRef;
@ViewChild("kanban_container", { static: true }) kanban_container!: ElementRef;

private _kanban!: Kanban;
private _toolbar!: Toolbar;

ngOnInit() {
const { cards, columns, rows } = getData();
this._kanban = new Kanban(this.kanban_container.nativeElement, {
columns, // apply column data
cards, // apply card data
rows, // apply row data
rowKey: "type",
// other configuration properties
});

this._toolbar = new Toolbar(this.toolbar_container.nativeElement, {
api: this._kanban.api,
// other configuration properties
});
}

ngOnDestroy(): void {
this._kanban.destructor();
this._toolbar.destructor();
}
}
~~~

You can also use the [`parse()`](/api/methods/js_kanban_parse_method/) method inside the `ngOnInit()` method of Angular to load data into Kanban. It will reload data on each applied change.
You can also use the [`parse()`](/api/methods/js_kanban_parse_method/) method inside the `ngOnInit()` method of Angular to load data into Kanban.

~~~jsx {11} title="kanban.component.ts"
// importing the data file
import { getData } from './data';
~~~jsx {2,23,37-42} title="kanban.component.ts"
import { Kanban, Toolbar } from '@dhx/trial-kanban';
import { getData } from "./data"; // import data
import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation} from '@angular/core';

ngOnInit() {
const { cards, columns } = getData();
const board = new Kanban(this.container.nativeElement, {
columns: [],
cards: []
});
@Component({
encapsulation: ViewEncapsulation.None,
selector: "kanban", // a template name used in the "app.component.ts" file as <kanban />
styleUrls: ["./kanban.component.css"],
template: `<div class="component_container">
<div #toolbar_container></div>
<div #kanban_container style="height: calc(100% - 56px);"></div>
</div>`
})

export class KanbanComponent implements OnInit, OnDestroy {
@ViewChild("toolbar_container", { static: true }) toolbar_container!: ElementRef;
@ViewChild("kanban_container", { static: true }) kanban_container!: ElementRef;

board.parse({ columns, cards });
private _kanban!: Kanban;
private _toolbar!: Toolbar;

ngOnInit() {
const { cards, columns, rows } = getData();
this._kanban = new Kanban(this.kanban_container.nativeElement, {
columns: [],
cards: [],
rows: [],
rowKey: "type",
// other configuration properties
});

this._toolbar = new Toolbar(this.toolbar_container.nativeElement, {
api: this._kanban.api,
// other configuration properties
});

// apply the data via the parse() method
this._kanban.parse({
columns,
cards,
rows
});
}

ngOnDestroy(): void {
this._kanban.destructor();
this._toolbar.destructor();
}
}
~~~

The `this._kanban.parse(data)` method provides data reloading on each applied change.

Now the Kanban component is ready. When the element will be added to the page, it will initialize the Kanban object with data. You can provide necessary configuration settings as well. Visit our [Kanban API docs](/api/overview/properties_overview/) to check the full list of available properties.

#### Handling events

When a user makes some action in the Kanban, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events_overview/).

Open the **kanban.component.ts** file and complete the `ngOnInit()` method as in:
Open the **kanban.component.ts** file and complete the `ngOnInit()` method in the following way:

~~~jsx {4-6} title="kanban.component.ts"
~~~jsx {5-7} title="kanban.component.ts"
// ...
ngOnInit() {
const board = new Kanban(this.container.nativeElement,{ /*...*/ });
this._kanban = new Kanban(this.kanban_container.nativeElement, {});

board.api.on("add-card", (obj) => {
this._kanban.api.on("add-card", (obj) => {
console.log(obj.columnId);
});
}

ngOnDestroy(): void {
this._kanban.destructor();
}
~~~

### Step 3. Adding Kanban into the app

Now it's time to add the component into your app. Open ***src/app/app.component.ts*** and use *KanbanComponent* instead of the default content by inserting the code below:
To add the ***KanabnComponent*** component into your app, open the ***src/app/app.component.ts*** file and replace the default code with the following one:

~~~jsx title="app.component.ts"
~~~jsx {5} title="app.component.ts"
import { Component } from "@angular/core";

@Component({
Expand All @@ -225,9 +316,9 @@ export class AppComponent {
}
~~~

Then create the ***app.module.ts*** file in the ***src/app/*** directory and insert the *KanbanComponent* as provided below:
Then create the ***app.module.ts*** file in the ***src/app/*** directory and specify the *KanbanComponent* as shown below:

~~~jsx title="app.module.ts"
~~~jsx {4-5,8} title="app.module.ts"
import { NgModule } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";

Expand All @@ -237,7 +328,6 @@ import { KanbanComponent } from "./kanban/kanban.component";
@NgModule({
declarations: [AppComponent, KanbanComponent],
imports: [BrowserModule],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule {}
Expand Down
10 changes: 8 additions & 2 deletions docs/guides/integration_with_react.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ export default function KanbanComponent(props) {

You can also use the [`parse()`](/api/methods/js_board_parse_method/) method inside the `useEffect()` method of React to load data into Kanban:

~~~jsx {9-10,20} title="Kanban.jsx"
~~~jsx {9-10,27} title="Kanban.jsx"
import { useEffect, useRef } from "react";
import { Kanban, Toolbar } from "@dhx/trial-kanban";
import "@dhx/trial-kanban/dist/kanban.css";
Expand All @@ -244,7 +244,13 @@ export default function KanbanComponent(props) {
let rows = props.rows; // data for rows

useEffect(() => {
const kanban = new Kanban(kanban_container.current, {});
const kanban = new Kanban(kanban_container.current, {
columns: [],
cards: [],
rows: [],
rowKey: "type",
// other configuration properties
});

const toolbar = new Toolbar(toolbar_container.current, {
api: kanban.api,
Expand Down
7 changes: 5 additions & 2 deletions docs/guides/integration_with_vue.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ export default {

You can also use the [`parse()`](/api/methods/js_kanban_parse_method/) method inside the `mounted()` method of Vue to load data into Kanban:

~~~html {6,19-23} title="Kanban.vue"
~~~html {6,22-26} title="Kanban.vue"
<script>
import { Kanban, Toolbar } from "@dhx/trial-kanban";
import "@dhx/trial-kanban/dist/kanban.css";
Expand All @@ -261,6 +261,9 @@ export default {
mounted() {
this.kanban = new ToDo(this.$refs.kanban_container, {
columns: [],
cards: [],
rows: [],
rowKey: "type",
// other configuration properties
});
Expand Down Expand Up @@ -321,7 +324,7 @@ export default {
}
</script>

<!--...-->
// ...
~~~

### Step 3. Adding Kanban into the app
Expand Down

0 comments on commit 2d4f170

Please sign in to comment.