addTaskLayer

displays an additional layer with custom elements for a task in the timeline area

string addTaskLayer(function|object func);

Parameters

funcfunction|objecta render function or a config object

Returns

stringa DOM element that will be displayed in the layer

Available only in PRO Edition

Example

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;
});

Related samples

Details

This functionality is available in the PRO edition only.

  • The argument function takes a task's object as a parameter and must return a DOM element that will be displayed in the layer.
  • The argument can also be an object. In this case, it can have the following properties:
    • renderer - (function|object) a function that answers for rendering the layer's elements (mandatory)
    • container - (HTMLElement) a layer's container (optional)
    • topmost - (boolean) if true, the element will be displayed over the task (optional)
    • filter - (function) a function that takes a task object as a parameter. If returns 'false', the 'renderer' function won't be called for a task (optional)
  • Beware, custom layers will be reset after the next call of gantt.init

Smart rendering for custom layers

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:

  • render - a rendering function
  • getRectangle - a function that returns an object with the coordinates of custom elements
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);
      }
    }
});

Rendering visible parts of custom elements

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};
        }
    }
});
  • update - allows updating an inner html of a custom element, i.e. to hiding cells that are not visible and displaying the visible ones

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.

See also
Back to top