Data Loading

dhtmlxGantt can take data of 2 formats:

To populate a Gantt chart with data, use parse or load method.

gantt.init("gantt_here");
gantt.load("tasks.json");

Related sample:  Basic initialization

If you pass incorrect data to the Gantt, its tree-like structure becomes cyclic which causes the cyclic reference error.

Loading from Object

To load data from an object, use the parse method:

Loading from an inline data source

var data = {
  tasks:[
     {id:1, text:"Project #1", start_date:"01-04-2020", duration:18},
     {id:2, text:"Task #1", start_date:"02-04-2020", duration:8, parent:1},
     {id:3, text:"Task #2", start_date:"11-04-2020", duration:8, parent:1}
   ]
};
gantt.init("gantt_here");
gantt.parse(data);

Related sample:  Basic initialization

If your data objects contain both "start_date" and "end_date" values and date values contain only date part (i.e. 01-12-2021 and not 01-12-2021 00:00) - you may need extra configuration. Be sure to check this article Task end date display & Inclusive end dates.

Loading from Server

Client side

To load data from a server, use the load method:

gantt.html

gantt.init("gantt_here");
gantt.load("data.json");

The load method will send an AJAX request to the specified url and will expect a response with data in one of the supported formats. For example:

data.json

{
  "tasks":[
     {"id":1, "text":"Project #1", "start_date":"01-04-2020", "duration":18},
     {"id":2, "text":"Task #1", "start_date":"02-04-2020","duration":8, "parent":1},
     {"id":3, "text":"Task #2", "start_date":"11-04-2020","duration":8, "parent":1}
  ],
  "links":[
     {"id":1, "source":1, "target":2, "type":"1"},
     {"id":2, "source":2, "target":3, "type":"0"}
  ]
}

The format is specified in the second argument of the method: "json", "xml" or "oldxml".

gantt.load("data.xml", "xml");

Server side

On the server you can have either a static file with data or a script that will collect data from the data source and write it to the response. The server-side implementation depends on the framework you want to use.

See detailed instructions and code samples for various platforms in the article Server-Side Integration.

For example, in case of Node.js we should add a server route for the URL where Gantt will send an AJAX request for data.

gantt.load("/data");

It will generate a corresponding response in the JSON format.

app.get("/data", function(req, res){
    db.query("SELECT * FROM gantt_tasks", function(err, rows){
        if (err) console.log(err);
        db.query("SELECT * FROM gantt_links", function(err, links){
            if (err) console.log(err);
            for (var i = 0; i < rows.length; i++){
                rows[i].start_date = rows[i].start_date.format("YYYY-MM-DD");
                rows[i].open = true;
            }
 
            res.send({ tasks:rows, links : links });
        });
    });
});

See all supported data formats in the article Exploring Supported Data Formats.

Loading Task Dates

Setting task schedule

There are three ways to define a schedule for a task in the data feed:

  • start_date + duration
  • start date + end_date
  • duration + end_date

The property that is not specified will be calculated based on the ones that are defined in the data object.

Related sample:  Backward planning

The end_date has a higher priority than the duration parameter. If there are 3 parameters specified in the task object, Gantt will ignore the duration parameter and the task will be loaded with a different duration value. For example:

{
    "id":"20", "text":"Project #2", 
    "start_date":"01-04-2025", 
    "duration":3, 
    "end_date":"05-04-2025", 
    "order":10,"progress":0.4, 
    "type": "project", "open": true
}
 
// the task above will be loaded with the duration value calculated in accordance
// with the specified 'start_date' and 'end_date'
{
    "id":"20", "text":"Project #2", 
    "start_date":"01-04-2025", 
    "duration":4, 
    "end_date":"05-04-2025", 
    "order":10,"progress":0.4, 
    "type": "project", "open": true
}

Loading dates in ISO format

You can use ISO date format in Gantt. For this, you need to redefine functions that parse and serialize dates in Gantt:

gantt.templates.parse_date = function(date) { 
    return new Date(date);
};
gantt.templates.format_date = function(date) { 
    return date.toISOString();
};

Task end date display & Inclusive end dates

This section will give you an answer to the question: "How to correctly save and display the end date of the task?".

Firstly, let's consider two possible scenarios you may face when working with task dates:

Scenario 1

  • When task duration is measured in whole days (duration_unit="day")
  • When task data objects contain start and end dates in the format of "%Y-%m-%d" or "%d-%m-%Y" (i.e. without hour-minute part)

Due to the details of how dhtmlxGantt interprets and stores end dates of tasks, the result dates may have values that are not expected.

Take a look at the following example:

gantt.parse({ tasks: [
    { 
        id: 1,
        text: "Task 1",
        start_date: "22-12-2021",
        end_date: "22-12-2021"
    }
]}, links:[]);
 
console.log(gantt.getTask(1).end_date);
// 22 December 2021 00:00:00
 
console.log(gantt.getTask(1).duration);
// 0

In this example, both start and end dates will refer to the same point of time and the task duration will be 0.

Scenario 2

  • When the End Date of a task is displayed in the Grid
  • And the format of the end date doesn't include the hour-minute part
gantt.config.columns = [
    {name: "text", label: "Name", tree: true, width: 200, resize: true},
    {name: "duration", label: "Duration", width:80, align: "center", resize: true},
    {name: "start_date", label: "Start", width:80, align: "center", resize: true},
    {name: "end_date", label: "Finish", width:80, align: "center", resize: true}
];
 
gantt.init("gantt_here");
 
gantt.parse({ tasks: [
    { 
        id: 1,
        text: "Task 1",
        start_date: "02-04-2020",
        end_date: "02-04-2020"
    }
]}, links:[]);

In this example, the Finish date (end_date of the task) is specified as April 3, while the task itself ends at the end of April 2.

We will explain the details on how Gantt stores end dates below.

How does Gantt store end dates?

Even if you don't specify the hour-minute part for the task date (duration_unit = "day"), dhtmlxGantt always saves it as JS Date, which has the hour-minute-second-millisecond part, on the client side.

The current format of the end dates is the following:

  • the second and millisecond parts of the date is always 0, Gantt does not support units less than 1 minute
  • the end date of the task is specified as beginning of the day ("day-hour-minute") following the last busy day ("day-hour-minute"). That is:
    • the task that starts on the 2nd of April and lasts for 1 day will have the following start and end dates: "02-04-2022 00:00:00 - 03-04-2022 00:00:00". The end date will match the date of the beginning of the day following the 2nd of April
    • the task which starts on the 2nd of April at 13:00 and lasts for 1 hour will have the following start and end dates: "02-04-2022 13:00:00 - 02-04-2022 14:00:00". The end date will match the date of the beginning of the next hour

If we show the end date of the task on the screen without setting an hour-minute part, the result may be misleading. In the example from scenario 2, the start and end dates will look like "02-04-2022 - 03-04-2022". This will make you think that the task lasts not 1 day but 2 (from the 2nd to the 3rd of April).

This is the default behavior and it may confuse you but there is the ability to fix it via configuration. In the following part we will show you several ways on how you can deal with it.

How to change the default behavior?

1) The first thing you should not do is to change the actual task dates which are stored in the gantt.

You may also want to modify the task dates which are loaded into the gantt, i.e. to specify end dates as 02-04-2022 23:59:59. But you'd better not do this because such decision may conflict with the calculation of the duration of tasks and auto-scheduling.

Instead, we recommend that you use the following methods:

2a) To change the format of the end dates of tasks in the gantt (i.e. to include the end date in the duration of the tasks), you can redefine the task_end_date template.

Let's take a task that starts on April 2nd, 2020 and lasts for one day and consider how the template can change the end date.

By default, the end date of this task should be displayed as April 3rd, 2020 (03-04-2020 00:00:00):

But if you apply the task_end_date template, the same task will be finished on April 2nd, 2020:

The code looks like:

// override the columns config
gantt.config.columns = [
  {name: "wbs", label: "#", width: 60, align: "center", template: gantt.getWBSCode},
  {name: "text", label: "Name", tree: true, width: 200, resize: true},
  {name: "start_date", label: "Start", width:80, align: "center", resize: true},
  {name: "end_date", label: "Finish", width:80, align: "center", resize: true}, 
  {name:"add"}
];
 
// redefine the template
gantt.templates.task_end_date = function(date){
   return gantt.templates.task_date(new Date(date.valueOf() - 1)); 
};
 
var gridDateToStr = gantt.date.date_to_str("%Y-%m-%d");
gantt.templates.grid_date_format = function(date, column){
   if(column === "end_date"){
     return gridDateToStr(new Date(date.valueOf() - 1)); 
   }else{
     return gridDateToStr(date); 
   }
}
gantt.init("gantt_here");

This way lets you change the task end date shown in the grid, header of the lightbox, and any other places where you need to show the end date.

If you are using the format for inclusive end dates of tasks and want to make it work correctly with inline editing in the grid, you have to create a special editor for editing inclusive end dates of tasks, as in:

// inclusive editor for end dates
// use the default editor, but override the set_value/get_value methods
var dateEditor = gantt.config.editor_types.date;
gantt.config.editor_types.end_date = gantt.mixin({
    set_value: function(value, id, column, node){
        var correctedValue = gantt.date.add(value, -1, "day");
        return dateEditor.set_value.apply(this, [correctedValue, id, column, node]);
    },
    get_value: function(id, column, node) {
        var selectedValue = dateEditor.get_value.apply(this, [id, column, node]);
        return gantt.date.add(selectedValue, 1, "day");
    },
}, dateEditor);
 
var textEditor = {type: "text", map_to: "text"};
var startDateEditor = {type: "date", map_to: "start_date"};
var endDateEditor = {type: "end_date", map_to: "end_date"};
var durationEditor = {type: "number", map_to: "duration", min:0, max: 100};
 
gantt.config.columns = [
    {name: "text", label: "Name", tree: true, width: 200, editor: textEditor, 
        resize: true},
    {name: "duration", label: "Duration", width:80, align: "center", 
        editor: durationEditor, resize: true},
    {name: "start_date", label: "Start", width:140, align: "center", 
        editor: startDateEditor, resize: true},
    {name: "end_date", label: "Finish", width:140, align: "center", 
        editor: endDateEditor, resize: true}
];
 
// change lightbox and grid templates to display dates of tasks in an inclusive format
gantt.templates.task_end_date = function(date){
    return gantt.templates.task_date(new Date(date.valueOf() - 1)); 
};
 
var gridDateToStr = gantt.date.date_to_str("%Y-%m-%d");
gantt.templates.grid_date_format = function(date, column){
    if(column === "end_date"){
        return gridDateToStr(new Date(date.valueOf() - 1)); 
    }else{
        return gridDateToStr(date); 
    }
}

Related sample:  Inclusive end date editor

2b) If other parts of the application require the end dates to be stored in the "inclusive" format - i.e. a task that starts on April 2nd, 2020 and lasts for one day needs to be stored with the start_date: "02-04-2022", end_date: "02-04-2022" - you have to implement additional processing of the end dates, namely:

  • to add one day to the end dates before loading data into the gantt
  • to subtract one day from the end dates before saving the changes received from the gantt back to the data storage

Data Properties

A data source for the Gantt chart is an object that stores 2 types of information:

  • tasks - the items of tasks.
  • links - the items of dependency links.

Properties of a task object

  • Mandatory properties - these properties will always be defined on the client, they must be provided by the datasource in order for gantt to operate correctly.
    • text - ( string ) the task text.
    • start_date - ( Date|string ) the date when a task is scheduled to begin. Must match date_format format if provided as a string.
    • duration - ( number ) the task duration. Can be replaced with the 'end_date' property.
    • id - ( string|number ) the task id.
  • Optional properties - these properties may or may not be defined. The default logic and templates of gantt will use these properties if they are defined.
    • type - (string) the task type. The available values are stored in the types object:
      • "task" - a regular task (default value).
      • "project" - a task that starts, when its earliest child task starts, and ends, when its latest child ends. The start_date, end_date, duration properties are ignored for such tasks.
      • "milestone" - a zero-duration task that is used to mark out important dates of the project. The duration, progress, end_date properties are ignored for such tasks.
    • parent - ( string|number ) the id of the parent task. The id of the root task is specified by the root_id config.
    • progress - ( number from 0 to 1 ) the task progress.
    • open - ( boolean ) specifies whether the task branch will be opened initially (to show child tasks).
    • end_date - ( Date|string ) the date when a task is scheduled to be completed. Used as an alternative to the duration property for setting the duration of a task. Must match date_format format if provided as a string.
    • row_height - ( number ) sets the default height for rows of the table
    • bar_height - ( number,string ) sets the height of task bars in the timeline area
    • readonly-(boolean) can mark task as readonly.
    • editable-(boolean) can mark task as editable.
    • rollup-(boolean) specifies whether a task (type:"task") or milestone (type:"milestone") should appear on the parent projects.
    • hide_bar-(boolean) defines whether a task (type:"task") or milestone (type:"milestone") should be hidden in the timeline area.
  • Dynamic properties - are created on the client and represent the current state of a task or a link. They shouldn't be saved to the database, gantt will ignore these properties if they are specified in your JSON/XML.

The default date format for JSON and XML data is "%d-%m-%Y %H:%i" (see the date format specification).
To change it, use the date_format configuration option.

gantt.config.date_format="%Y-%m-%d";
gantt.init("gantt_here");

Once loaded into Gantt, the start_date and end_date properties will be parsed into the Date type.

Date formats that are not supported by the date_format config can be parsed manually via the parse_date template.

  • Mandatory properties
    • id - ( string|number ) the link id.
    • source - ( number ) the id of a task that the dependency will start from.
    • target - ( number ) the id of a task that the dependency will end with.
    • type - (string) the dependency type. The available values are stored in the links object. By default, they are:
      • "0" - 'finish_to_start'.
      • "1" - 'start_to_start'.
      • "2" - 'finish_to_finish'.
      • "3" - 'start_to_finish'.
      If you want to store the dependency types in some way other than the default values('0','1','2'), you may change values of the related properties of the links object. For example:
      gantt.config.links.start_to_start = "start2start";
      Note, these values affect only the way the dependency type is stored, not the behaviour of visualization.
  • Optional properties
    • lag-(number) optional, task lag.
    • readonly-(boolean) optional, can mark link as readonly.
    • editable-(boolean) optional, can mark link as editable.

Custom properties

You are not limited to the mandatory properties listed above and can add any custom ones to data items. Extra data properties will be parsed as strings and loaded to the client side where you can use them according to your needs.

See examples of data with custom properties here.

Database Structure

If you use a database, we recommend to have 2 separate tables to store data: one for tasks and one for links.

The structure of a standard database to load tasks and links to the Gantt chart is:

  • gantt_tasks table - specifies the gantt tasks
    • id - (string,number) the event id.
    • start_date - (Date) the date when a task is scheduled to begin.
    • text - (string) the task's description.
    • progress - (number) a number from 0 to 1 that shows what percent of the task is complete.
    • duration - (number) the task duration in the units of the current time scale.
    • parent - (number) the id of the parent task.
    • type - (string) optional, the type of the task.
    • readonly - (boolean) optional, can mark task as readonly.
    • editable - (boolean) optional, can mark task as editable.
  • gantt_links table - specifies the gantt dependency links
    • id - (string,number) the event id.
    • source - (number) the id of the source task.
    • target - (number) the id of the target task.
    • type - (string) the type of the dependency:
      • 0 - 'finish_to_start'
      • 1 - 'start_to_start'
      • 2 - 'finish_to_finish'
      • 3 - 'start_to_finish'
    • lag - (number) optional, task lag.
    • readonly - (boolean) optional, can mark link as readonly.
    • editable - (boolean) optional, can mark link as editable.

Use the following SQL statement to create a database with 2 mentioned tables:

CREATE TABLE `gantt_links` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `source` int(11) NOT NULL,
  `target` int(11) NOT NULL,
  `type` varchar(1) NOT NULL,
  PRIMARY KEY (`id`)
)
CREATE TABLE `gantt_tasks` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `text` varchar(255) NOT NULL,
  `start_date` datetime NOT NULL,
  `duration` int(11) NOT NULL,
  `progress` float NOT NULL,
  `sortorder` int(11) NOT NULL,
  `parent` int(11) NOT NULL,
  PRIMARY KEY (`id`)
)

Events Flow

Loading-related methods have the following events flow:

gantt.parse():

gantt.load()

gantt.refreshData():

gantt.render():

Back to top