displays an additional layer with custom elements for a task in the timeline area
| func | TaskLayerRender | TaskLayerConfig | a render function or a config object |
| string | a DOM element that will be displayed in the layer |
Available only in PRO Edition
gantt.init("gantt_here");
gantt.addTaskLayer(function draw_deadline(task) {
if (task.deadline) {
var el = document.createElement('div');
el.className = 'deadline';
var sizes = gantt.getTaskPosition(task, task.deadline);
el.style.left = sizes.left + 'px';
el.style.top = sizes.top + 'px';
el.setAttribute('title', gantt.templates.task_date(task.deadline));
return el;
}
return false;
});
This functionality is available in the PRO edition only.
The argument can have these types:
taskLayerRender (task, timeline, config, viewport): HTMLElement|boolean|void - a function takes a task's object as a parameter and must return a DOM element that will be displayed in the layer.
taskLayerConfig - (object) - the configuration object for the additional task layer. Has the following properties:
ReactDOM.render method)
The layer viewport has these properties:
viewport - (object) - the layer viewport object
Beware, custom layers will be reset after the next call of gantt.init
Smart rendering tries to display only those HTML elements that are currently visible to the user and not hidden under horizontal and vertical scroll bars.
However, in the case of custom layers, Gantt doesn't know where custom elements are located, since it's completely up to the implementation of the custom rendering function.
As a solution, smart rendering assumes that a custom element is located in the same row where its related task is. Custom elements are added to the page markup when rows of their related tasks are rendered on the screen. In this mode Gantt doesn't take the position of horizontal scrollbar into consideration, a custom element will be rendered in the markup but won't be visible on the page because of the horizontal scroll.
Most of the time it's good enough, but if you have many layers, you may want to optimize the rendering a bit further by providing Gantt with information on position of custom elements.
To do that, you need to use the object parameter of the addTaskLayer() method, and provide the renderer object with the following methods:
gantt.addTaskLayer({
renderer: {
render: function(task, timeline, viewport){
...
return HTMLElement
},
getRectangle: function(task, view){
....
return {left, top, height, width};
}
}
});
The logic of rendering custom elements is the following:
1. When the position of horizontal scroll is changed, the smart render gets new coordinates of the area visible on the screen at the moment.
2. dhtmlxGantt calls the getRectangle function for each task/link to get the exact coordinates of a custom element.
3. If the getRectangle function returns null value, the render function won't be called and the custom element won't be displayed.
4. If the getRectangle function returns an object with the coordinates of a task/link and the received coordinates fall in the current viewport, then the render function will be called to display a task/link.
gantt.addTaskLayer({
renderer: {
render: function draw_planned(task) {
if (task.planned_start && task.planned_end) {
var sizes = gantt.getTaskPosition(task,task.planned_start,task.planned_end);
var el = document.createElement('div');
el.className = 'baseline';
el.style.left = sizes.left + 'px';
el.style.width = sizes.width + 'px';
el.style.top = sizes.top + gantt.config.task_height + 13 + 'px';
return el;
}
return false;
},
// define getRectangle in order to hook layer with the smart rendering
getRectangle: function(task, view){
return gantt.getTaskPosition(task, task.planned_start, task.planned_end);
}
}
});
The renderer object of the addTaskLayer() method provides a possibility to update the node markup of a custom element and display the visible content in the current viewport via the update method:
gantt.addTaskLayer({
renderer: {
render: function(task, timeline, viewport){
...
return HTMLElement
},
update: function(task, node, timeline, viewport){
...
// put the currently visible part of the element into node inner html
},
getRectangle: function(task, view){
....
return {left, top, height, width};
}
}
});
The update method is called after the onGanttScroll event is fired. It provides a task node (created by the render method initially) and a current viewport.
Since v7.1.8 the renderer object of the addTaskLayer() method allows getting a visible range of tasks rows with the getVisibleRange function:
gantt.addTaskLayer({
renderer: {
render: function(task, timeline, viewport){
...
return HTMLElement
},
getVisibleRange: function(){
...
return {
start: indexStart,
end: indexEnd
}
}
}
});
If the getVisibleRange function returns false instead of an object, Gantt supposes that all the range of tasks is used and an additional layer will be rendered even if a task is not visible on the screen.
The renderer object of the addTaskLayer() method provides the onrender callback:
gantt.addTaskLayer({
renderer: {
render: function(task, timeline, viewport){
...
return HTMLElement
},
onrender: function(item, node, view){
console.log("render", item, node)
}
}
});
The onrender function is called whenever the data item of the layer is rendered to DOM. The arguments give you access to the data item that has been rendered, the result DOM element and the view object which called the render (grid or timeline).
The callback can be used either to modify DOM elements after they are rendered to DOM, or to initialize the 3rd party widgets inside the rendered elements.