Extensions

React tutorial

How to use our JavaScript based Gantt chart components in a React app using next.js framework.

Introduction

DlhSoft has developed Gantt Chart Hyper Library using pure JavaScript (and has also introduced TypeScript definitions for its components later.) That means the components can also be used when building Web apps using higher level frameworks, such as React (at the time of writing this text — version 16), and we have defined wrapper components to help you out reaching this goal.

A small part of this tutorial (hosting the Web app for local testing) assumes that you are fine with having Node.js, next.js, pnpm, and other Web tools installed on your system. If you're running even newer versions of the referrenced software (that may have been recently published), don't worry, most probably all the commands will continue to run with very little or no changes at all. Also note that commands presented in this tutorial are for Windows based development systems, but macOS and Linux can also be used (and differences are indicated wherever they matter.)

Setting up your React app

In this tutorial we'll show how you can create a React app and then integrate DlhSoft Gantt chart components in its code. If you already have a React app and experience with the tools, see technical documentation instead.

Note that a React app can be created using a npx command (npx create-react-app my-app), but here we'll simply create an app folder and some files in a more manual way.

  • Create the next.js app

    Ensure you have npm and npx installed, then run the following commands (with elevated access) to set up pnpm (used to host the dev environment), and create your next.js based React app:

    
    npm install -g pnpm
    npx create-next-app@latest
    

    The last command (create-next-app) will ask you a few questions. Answer them according to your project needs; for the purpose of our tutorial, we have provided these answrers:

    
    name: my-app
    TypeScript? no
    ESlint? no
    Tailwind CSS? no
    'src' directory? no
    App Router (recommended)? yes
    customize default import alias? no
    
  • Host and test the app

    Start pnpm hosting using this command (after you navigate into your app's folder), then navigate to http://localhost:3000 in your browser to check that it works:

    
    cd my-app
    pnpm dev
    

Get DlhSoft components

Our pure JavaScript components are not enclosed in a high level package — but they are available for download as .zip or .tar files. This means that they will not update automatically, but this is, in our opinion, a more generic approach. You can surely download the most up to date archive file whenever you need to use a more recent build, however, and we encourage you to subscribe to our core product news feed to know when new features arrive.

  • Download libraries

    You can either download DlhSoft components directly as a .zip file (as stated above) and extract it yourself wherever you'd like (to be saved for further reference), or you can use npm to get them into an node_modules subfolder as you may be doing with your other packages. The difference is that you point npm to an URL rather than a package name.

    
    npm install @dlhsoft/ganttcharthyperlibrary
    
  • Determine which scripts you need

    Open the extracted folder. In Windows, you can use explorer command, while on macOS and Linux open command should be used to view the contents of the destination folder. (Alternatively, you can run dir or ls commands to view the results directly in your Command Prompt or Terminal window; note that on macOS and Linux you should use slash / character to separate path parts, rather than backslash \.)

    On Windows:

    
    dir "node_modules/@dlhsoft/ganttcharthyperlibrary"
    

    On macOS and Linux:

    
    ls node_modules/@dlhsoft/ganttcharthyperlibrary
    

    The files below are available for you to use in your React app. The appropriate core .js (and optionally .d.ts - TypeScript definition) files are needed for the React extension components to work. Other files are also available inside the folder, but you can safely ignore them.

    Category Details Files
    Core JavaScript components Gantt chart, schedule chart, load chart
    PERT chart, network diagram
    DlhSoft.ProjectData.GanttChart.HTML.Controls.js, .d.ts
    DlhSoft.ProjectData.PertChart.HTML.Controls.js, .d.ts
    Optional UI enhancers Date-time picker, multi-selector combo box DlhSoft.Data.HTML.Controls.js, .d.ts
    Optional XML import/export Project serializer DlhSoft.ProjectData.GanttChart.HTML.Controls.Extras.js, .d.ts
    React extensions Gantt chart, schedule chart, load chart
    PERT chart, network diagram
    DlhSoft.ProjectData.GanttChart.React.Components.js
    DlhSoft.ProjectData.PertChart.React.Components.js
  • Copy the necessary files

    The files in extracted folder may not be immediately available to use in your React app. You need to copy the files you need into the public directory of your app, first.

    Copy the files using either Explorer or Finder, or at the command line prompt.

    On Windows:

    
    mkdir public
    copy node_modules\@DlhSoft\GanttChartHyperLibrary\DlhSoft.ProjectData.GanttChart.HTML.Controls.js .\public\
    copy node_modules\@DlhSoft\GanttChartHyperLibrary\DlhSoft.ProjectData.PertChart.HTML.Controls.js .\public\
    copy node_modules\@DlhSoft\GanttChartHyperLibrary\DlhSoft.Data.HTML.Controls.js .\public\
    copy node_modules\@DlhSoft\GanttChartHyperLibrary\DlhSoft.ProjectData.GanttChart.React.Components.js .\public\
    copy node_modules\@DlhSoft\GanttChartHyperLibrary\DlhSoft.ProjectData.PertChart.React.Components.js .\public\
    

    On macOS and Linux:

    
    mkdir public
    cp node_modules/@dlhsoft/ganttcharthyperlibrary/DlhSoft.ProjectData.GanttChart.HTML.Controls.js ./public/
    cp node_modules/@dlhsoft/ganttcharthyperlibrary/DlhSoft.ProjectData.PertChart.HTML.Controls.js ./public/
    cp node_modules/@dlhsoft/ganttcharthyperlibrary/DlhSoft.Data.HTML.Controls.js ./public/
    cp node_modules/@dlhsoft/ganttcharthyperlibrary/DlhSoft.ProjectData.GanttChart.React.Components.js ./public/
    cp node_modules/@dlhsoft/ganttcharthyperlibrary/DlhSoft.ProjectData.PertChart.React.Components.js ./public/
    
  • Use DlhSoft components in your markup

    To use Dlhsoft React components you simply need to place appropriately named elements in your markup/script files (defining the user interface of your screens), and set up the properties — items, settings, license, change — to the data you will also need to prepare for them in code. For example, update the Home function in page.js file (within app folder) to include a GanttChartView instance:

    
    function Home() {
      …
      return (
        …
        <GanttChartView items={items} settings={settings} license={license}
                        change={onItemChanged} style={{width: '960px', height: '350px'}}
                        path={'./'}>
          …
        </GanttChartView>
        …
      );
    }
    

    Note: path property is optional; it would actually be needed only if you placed the scripts in a different subdirectory under public directory.

    The elements that can be used are listed below, mapped to the specific components they reference.

    Component Element Details
    GanttChartView GanttChartView Singe bar per row, e.g. project with tasks
    ScheduleChartView ScheduleChartView Multiple bars per row, e.g. tasks assigned to resources
    LoadChartView LoadChartView Allocations over time, e.g. resource load percents
    PertChartView PertChartView PERT diagram, e.g. tasks displayed as arrows
    NetworkDiagramView NetworkDiagramView Network diagram, e.g. PERT methodology
  • Set up data

    As mentioned in the previous step, you will need to also set up data for the component's properties in your code, e.g. as App function's preparation steps (or similarly, in the code of any other container component in your project.) To set up the items and settings, use the fields supported by the core component, as detailed in core product's technical reference.

    
    function Home() {
      …
      const date = new Date(), year = date.getFullYear(), month = date.getMonth();
      const tasks = [
        { content: 'Planning', label: 'Planning', isExpanded: false },
        { content: 'Analysis', indentation: 1, start: new Date(year, month, 2, 8, 0, 0), finish: new Date(year, month, 3, 16, 0, 0), assignmentsContent: 'Clarissa Candelaria [50%]' },
        …
      ];
      const [items, setItems] = useState(tasks);
      var settings = { … };
      var license = "…"; // upon purchasing a product license from DlhSoft
      function onItemChanged(item, propertyName, isDirect, isFinal) {
        console.log(propertyName + ' changed for ' + item.content + '.');
      }
      return …;
    }
    

    Note: to be able to call useState you will need this line at the top of the page.js file:

    
    import { useState } from 'react';
    

    Properties that you may provide values for (applying to all components) are listed below.

    Property Details
    items Actual data to be presented (e.g. task or resource items, depending on the specific component, see technical reference)
    settings Customizations for the appearance and behavior of the component (see technical reference)
    license String value generated by DlhSoft License Manager tool upon purchasing a product license (to remove nag screens)
    change Function that would be called upon client side changes

TypeScript considerations

If you use TypeScript (such as by having created your project using npx create-react-app my-app --template typescript) you can use DlhSoft React component extensions by following these steps:

  1. Define Props interfaces for each component you need to use;
  2. Create props objects of appropriate Props type for each component instance you need to setup;
  3. Use {...props} syntax to initialize component instances in markup.

interface GanttChartViewProps extends RefAttributes {
  items: any; settings: any;
  license?: any;
  change?: any; style?: any;
  children?: any;
  path?: any;
}
…
var props: GanttChartViewProps = { 
  items: items, settings: settings,
  style: { width: '960px', height: '350px' }
};
return <GanttChartView {...props}>…</GanttChartView>