addTaskLayer

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

string addTaskLayer(TaskLayerRender | TaskLayerConfig func);
funcTaskLayerRender | TaskLayerConfiga render function or a config object
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 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.

    • task - (Task) - the task object
    • timeline? - (any) - the timeline view
    • config? - (GanttConfigOptions) - the Gantt configuration object
    • viewport? - (LayerViewport) - the viewport object
  • taskLayerConfig - (object) - the configuration object for the additional task layer. Has the following properties:

    • id? - (string | number) - optional, the layer ID
    • renderer - (object) - mandatory, a function that answers for rendering the layer's elements
      • render - (TaskLayerRender) - the function that returns HTML element that should be rendered
      • update? - (Function): void - optional, a function where you can update the rendered HTML elements
        • task - (Task) - the task object
        • node - (HTMLElement) - the container of the rendered node
        • timeline? - (any) - the timeline view
        • config? - (GanttConfigOptions) - the Gantt configuration object
        • viewport? - (LayerViewport) - the viewport object
      • onrender? - (Function): void - optional, this function is called after rendering is complete. You can use it to render native components (for example, using the ReactDOM.render method)
        • task - (Task) - the task object
        • node - (HTMLElement) - the container of the rendered node
        • view? - (any) - the layout cell where the layer is added (timeline, by default)
      • getRectangle? - (Function): { left: number, top: number, height: number, width: number } | void - optional, a function that returns the coordinates of the viewport rectangle
        • task - (Task) - the task object
        • view? - (any) - the layout cell where the layer is added (timeline, by default)
        • config? - (GanttConfigOptions) - the Gantt configuration object
        • gantt? - (GanttStatic) - the Gantt object
      • getVisibleRange - (Function): {start: number, end: number} | undefined | void - a function that returns the object with of the visible range
        • gantt? - (GanttStatic) - the Gantt object
        • view? - (any) - the layout cell where the layer is added (timeline, by default)
        • config? - (GanttConfigOptions) - the Gantt configuration object
        • datastore? - (any) - the task datastore object
        • viewport? - (LayerViewport) - the viewport object
    • container? - (HTMLElement) - optional, a layer's container
    • topmost? - (boolean) - optional, if true, the element will be displayed over the task
    • filter? - (Function): boolean - optional, a function that takes a task object as a parameter. If returns 'false', the 'renderer' function won't be called for a task
      • task - (Task) - the task object

The layer viewport has these properties:

  • viewport - (object) - the layer viewport object

    • x - (number) - the left rectangle position
    • x_end - (number) - the right rectangle position
    • y - (number) - the top rectangle position
    • y_end - (number) - the bottom rectangle position
    • width - (number) - the rectangle width
    • height - (number) - the rectangle height
  • Beware, custom layers will be reset after the next call of gantt.init

  • Calling the gantt.resetLayout() method will also reset custom layers. In order for custom layers to be displayed on a page, you need to redefine the gantt.addTaskLayer method after calling resetLayout.

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. 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.

Rendering visible tasks rows

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
            }
        }
    }
});
  • getVisibleRange - a function that returns an object with the start and end indexes of visible tasks rows. If a task is out of the specified range, an additional layer is not rendered for it.

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.

Element render callback

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.

See also
  • API
  • Articles
  • Back to top