Skip to content

[dev] add dedicated hooks page, add details on new hooks #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlexKlimenkov wants to merge 1 commit into
base: next
Choose a base branch
from
Open

[dev] add dedicated hooks page, add details on new hooks #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 18 additions & 133 deletions docs/integrations/react/configuration-props.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,135 +180,30 @@ The `@dhx/react-gantt` library is designed to be as declarative as possible for

In these cases, you can use two additional approaches to tap into the underlying DHTMLX Gantt functionality:

- **React hooks** specifically provided by the wrapper to bridge Gantt's data stores and scheduling logic
- **[React hooks](integrations/react/hooks.md)** specifically provided by the wrapper to bridge Gantt's data stores and scheduling logic

- **Direct access** to the Gantt instance via a `\ref` if the built-in hooks don't cover all your needs
- **Direct access** to the Gantt instance via a ref if the built-in hooks don't cover all your needs

### Using built-in hooks
### Using built-in hooks

The `@dhx/react-gantt` library exposes a set of optional hooks that connect React components to internal Gantt APIs. These hooks provide a 'bridge' to Gantt's underlying methods and data stores. You can either call these hooks directly in your components or compose them into your own custom hooks for specialized features like resource histograms.
The `@dhx/react-gantt` library provides hooks for event subscriptions, resource management, datastore access, undo/redo, zoom, selection, and work time calculations.

#### useGanttDatastore<T>(ganttRef, storeName)
See the dedicated **[Hooks](integrations/react/hooks.md)** page for the complete reference, including:

The `useGanttDatastore` hook hives a read-only access to a specific Gantt datastore.
The common use is accessing the resource datastore, baseline, or any other built-in or custom store.

It provides the following functions:

- `getItem(id)` - returns a specified item from the datastore

- `getItems()` - returns all items in the specified datastore

- `hasChild(id: string | number)` - checks if an item has children

- `getChildren(id: string | number)` - retrieves child items

~~~js
import { useMemo } from 'react';
import { useGanttDatastore } from '@dhx/react-gantt';

function MyResourceList({ ganttRef }) {
const resourceStore = useGanttDatastore(ganttRef, 'resource');

const resourceIds = resourceStore.getItems().map(item => item.id);

// for demonstration, just log the data
useMemo(() => {
console.log('Resource IDs:', resourceIds);
}, [resourceIds]);

return null;
}
~~~

You can use this hook whenever you need direct low-level data from a specific datastore. For example, checking if a resource is a group vs. an individual.

#### useResourceAssignments(ganttRef)

The `useResourceAssignments` hook exposes Gantt's resource-related methods, such as retrieving assignments for a resource or enumerating which resources are assigned to a given task.

It provides the following functions:

- `getResourceAssignments(resourceId, taskId?)` - bridge to [](api/method/getresourceassignments.md)
- `getTaskResources(taskId)` - bridge to [](api/method/gettaskresources.md)

~~~js
import React from 'react';
import { useResourceAssignments } from '@dhx/react-gantt';

export function ResourceUsage({ ganttRef, taskId }) {
const { getTaskResources } = useResourceAssignments(ganttRef);

const resources = getTaskResources(taskId);
return (
<div>
Task {taskId} assigned to:
{resources.map(r => r.text).join(', ')}
</div>
);
}
~~~

You may need this hook for any custom logic around resource usage, e.g., calculating allocated hours or grouping tasks by owner

#### useWorkTime(ganttRef)

Provides a direct bridge for built-in DHTMLX Gantt worktime functions, such as [](api/method/isworktime.md), [](api/method/calculateenddate.md), [](api/method/calculateduration.md).

You'll need this hook for highlighting working/non-working time according to Gantt work calendar settings, as well as for date operations in accordance to work calendars.

It provides the following functions:

- `isWorkTime({ date:Date, unit?: string, task?:Task })` - bridge to [](api/method/isworktime.md)
- `calculateEndDate({start:Date, duration:number, unit?: string, task?: Task})` - bridge to [](api/method/calculateenddate.md)
- `calculateDuration({start:Date, end:Date, task?: Task})` - bridge to [](api/method/calculateduration.md)
- `getClosestWorkTime({ date:Date, unit?: string, task?: Task, dir?: "past"|"future" })` - bridge to [](api/method/getclosestworktime.md)


~~~js
import { useEffect, useRef, useState } from 'react';
import ReactGantt, {GanttTemplates, useWorkTime} from "@dhx/react-gantt";
import "@dhx/react-gantt/dist/react-gantt.css";

export default function GanttTemplatesDemo() {
const ganttRef = useRef<ReactGanttRef>(null);

const { isWorkTime }= useWorkTime(ganttRef);
...
const templates: GanttTemplates = {
timeline_cell_class: (task: Task, date: Date) => {
return isWorkTime({date, task}) ? "" : "weekend";
}
};
...
~~~

#### Composing hooks into your own custom hooks

A great practice is to build your own domain or project-specific hooks using these fundamental bridging hooks. For instance, if you want to create a resource histogram, you might create a custom hook that caches capacity values, sums resource usage, etc.:

~~~js
import { useMemo } from 'react';
import { useGanttDatastore, useResourceAssignments } from '@dhx/react-gantt';

export function useResourceHistogram(ganttRef) {
const resourceStore = useGanttDatastore(ganttRef, 'resource');
const { getResourceAssignments } = useResourceAssignments(ganttRef);

// Custom logic: capacity caching, group detection, etc.
// ...
return {
// e.g. getCapacity, getAllocatedValue
};
}
~~~
- [useGanttEvent](integrations/react/hooks.md#useganttEvent) — event subscriptions with lifecycle management
- [useResourceAssignments](integrations/react/hooks.md#useresourceassignments) — resource assignment queries and mutations
- [useGanttDatastore](integrations/react/hooks.md#useganttdatastore) — read-only datastore access
- [useUndoRedo](integrations/react/hooks.md#useundoredo) — undo/redo state and actions
- [useZoom](integrations/react/hooks.md#usezoom) — zoom control and state
- [useSelection](integrations/react/hooks.md#useselection) — task selection tracking
- [useWorkTime](integrations/react/hooks.md#useworktime) — work time calculations

### Direct access to Gantt instance with ref

While these hooks handle most advanced needs, you might still want direct access to the entire Gantt instance. For that, the ref approach remains available:
While hooks handle most advanced needs, you might still want direct access to the entire Gantt instance. For that, the ref approach remains available:

~~~jsx
import React, { useRef, useEffect } from 'react';
~~~tsx
import { useRef, useEffect } from 'react';
import ReactGantt, { ReactGanttRef } from '@dhx/react-gantt';

export function DirectRefExample({ tasks, links }) {
Expand All @@ -317,26 +212,16 @@ export function DirectRefExample({ tasks, links }) {
useEffect(() => {
const gantt = ganttRef.current?.instance;
if (!gantt) return;

// here you can call ANY Gantt API method
console.log('All tasks:', gantt.getTaskByTime());
gantt.showDate(new Date());
}, []);

return (
<ReactGantt
ref={ganttRef}
tasks={tasks}
links={links}
/>
);
return <ReactGantt ref={ganttRef} tasks={tasks} links={links} />;
}
~~~

:::note
info Be mindful that if you alter tasks/links in the direct Gantt instance while also feeding them as React props,
you should keep them in sync or re-parse the data. Otherwise, the next React re-rendering may overwrite your manual changes.
If you alter tasks or links via the direct Gantt instance while also feeding them as React props, keep them in sync. Otherwise, the next React re-render may overwrite your manual changes.
:::

If you want to do something not exposed by a prop, you can still call gantt methods directly. See [Accessing the Underlying Gantt API](integrations/react/overview.md#accessingtheunderlyingganttapi) for more details.
See [Accessing the Underlying Gantt API](integrations/react/overview.md#accessingtheunderlyingganttapi) for more details.

Loading