Zoom Extension

You can read details about the Zoom extension in the Zooming article. The current article provides the API reference of the zoom object:

Zoom Levels

The Zoom extension uses a set of the scale settings and allows quickly switching between them.

ZoomLevel is an object that contains the scale settings. It has the following properties:

• name - (string) - the name of the level
• scale_height? - (number) - the height of the scale
• height? - (number) - the height of the scale
• min_column_width? - (number) - the minimal width of a column. It has a higher priority than minColumnWidth and maxColumnWidth
• scales - (Scales) - an array of scales to switch between while zooming in/out on this level

Methods

• init(zoomConfig): void - initializes the extension with the provided configuration.
  • zoomConfig? - (object) - an object with configuration settings that contains the levels array of zooming levels and a number of additional properties:
    • levels? - (ZoomLevel[]) - an array of zooming levels. Optional - when omitted, a set of default named levels ("hour", "day", "week", "month", "year") is used
    • handler? - (Function): void - allows specifying a custom handler of the mouse wheel to work with zooming manually
      • e - (Event) - a native event object.
    • startDate? - (Date) - the start value of the time scale zooming
    • endDate? - (Date) - the end value of the time scale zooming
    • activeLevelIndex? - (number) - the number of the default active level
    • widthStep? - (number) - the step of increasing/decreasing the width of scale while switching to the next/previous zooming level
    • minColumnWidth? - (number) - the minimal width of a column that allows switching to the previous zooming level
    • maxColumnWidth? - (number) - the maximal width of a column that allows switching to the next zooming level
    • useKey? - (string) - the key that enables zooming by scrolling the mouse wheel:"ctrlKey" | "altKey" | "shiftKey"
    • trigger? - (string | null | undefined) - the trigger of zooming: "wheel" | null | undefined
    • element? - (HTMLElement | Function): HTMLElement - a DOM element over which zooming is triggered or a function that returns a DOM element
    • fit? - (object) - the default zoom-to-fit settings. Along with the zoomToFit options listed below, it accepts levels (a dedicated set of scales used only for fitting) and handler (a function that overrides the level selection)

These are two examples of setting the zoom configuration:

const zoomConfig = {
    levels: [
        {
            name: "day",
            scale_height: 27,
            min_column_width: 80,
            scales: [{ unit: "day", step: 1, format: "%d %M" }]
        },
        {
            name: "week",
            scale_height: 50,
            min_column_width: 50,
            scales: [
                {
                    unit: "week",
                    step: 1,
                    format: (date) => {
                        const dateToStr = gantt.date.date_to_str("%d %M");
                        const endDate = gantt.date.add(date, 6, "day");
                        const weekNumber = gantt.date.date_to_str("%W")(date);

                        return `#${weekNumber}, ${dateToStr(date)} - ${dateToStr(endDate)}`;
                    }
                },
                { unit: "day", step: 1, format: "%j %D" }
            ]
        },
        {
            name: "month",
            scale_height: 50,
            min_column_width: 120,
            scales: [{ unit: "month", format: "%F, %Y" }, { unit: "week", format: "Week #%W" }]
        },
        {
            name: "quarter",
            height: 50,
            min_column_width: 90,
            scales: [
                { unit: "month", step: 1, format: "%M" },
                {
                    unit: "quarter",
                    step: 1,
                    format: (date) => {
                        const dateToStr = gantt.date.date_to_str("%M");
                        const endDate = gantt.date.add(gantt.date.add(date, 3, "month"), -1, "day");

                        return `${dateToStr(date)} - ${dateToStr(endDate)}`;
                    }
                }
            ]
        },
        {
            name: "year",
            scale_height: 50,
            min_column_width: 30,
            scales: [{ unit: "year", step: 1, format: "%Y" }]
        }
    ]
};

gantt.ext.zoom.init(zoomConfig);


// or, in a more simple way levels can be presented as scale arrays
const hourToStr = gantt.date.date_to_str("%H:%i");
const hourRangeFormat = (step) => {
    return (date) => {
        const intervalEnd = new Date(gantt.date.add(date, step, "hour") - 1);

        return `${hourToStr(date)} - ${hourToStr(intervalEnd)}`;
    };
};
const simpleZoomConfig = {
    levels: [
        [
            { unit: "month", format: "%M %Y", step: 1 }
        ],
        [
            { unit: "month", format: "%M %Y", step: 1 },
            { unit: "day", format: "%d %M", step: 1 }
        ],
        [
            { unit: "day", format: "%d %M", step: 1 },
            { unit: "hour", format: hourRangeFormat(12), step: 12 }
        ],
        [
            { unit: "day", format: "%d %M", step: 1 },
            { unit: "hour", format: hourRangeFormat(6), step: 6 }
        ],
        [
            { unit: "day", format: "%d %M", step: 1 },
            { unit: "hour", format: "%H:%i", step: 1 }
        ]
    ]
};

gantt.ext.zoom.init(simpleZoomConfig);

• getCurrentLevel(): number - returns the number (index) of the current zooming level

gantt.ext.zoom.getCurrentLevel();

• setLevel(level): void - switches to the specified zooming level.
  • level - (number | string) - The level is defined either by a string (the name of the level from the config, e.g. "year"), or by its number in the array of levels

gantt.ext.zoom.setLevel("year");
// or 
gantt.ext.zoom.setLevel(5);

• getLevels(): ZoomLevel[] - allows getting all zooming levels

gantt.ext.zoom.getLevels();

Returns an array of zooming levels (ZoomLevels[]) passed to init(), which initializes the extension.

• zoomIn(): void - increases the current zooming level

gantt.ext.zoom.zoomIn();

For the same purpose you can also use:

gantt.ext.zoom.setLevel(gantt.ext.zoom.getCurrentLevel() - 1);

• zoomOut(): void - decreases the current zooming level

gantt.ext.zoom.zoomOut();

For the same purpose you can also use:

gantt.ext.zoom.setLevel(gantt.ext.zoom.getCurrentLevel() + 1);

• zoomToFit(options?): boolean - picks the most detailed zoom level at which the target tasks fit into the timeline width without horizontal scrolling, and applies it. See Zoom to fit for the list of options. The method is idempotent and returns true when a fitting level was applied, false otherwise.

gantt.ext.zoom.zoomToFit();
// or fit only the currently visible (expanded) rows
gantt.ext.zoom.zoomToFit({ scope: "visible" });

• resetZoom(): boolean - restores the zoom level and time scale that were active before the first zoomToFit() call. Returns true when a saved scale was restored, false when there is nothing to restore.

gantt.ext.zoom.resetZoom();

• attachEvent(name, handler): string - attaches an event handler

  • name - (string) - the name of the event handler
  • handler - (Function) - the function that will be called when the event fires

• detachEvent(id): void - detaches a handler from an event

  • id - (string) - the id of the attached event handler

• callEvent(name, params): boolean - calls an inner event

  • name - (string) - the event's name, case-insensitive
  • params - (Array<any>) - optional, an array of the event-related data

• checkEvent(name): boolean - checks whether an event has some handler(s) specified

  • name - (string) - the event's name

Returns true, if some handler is specified for the event.

Zoom to fit

zoomToFit(options) and the fit setting of init() accept the following options:

• scope? - ("all" | "visible") - which tasks to fit: "all" (default) fits every loaded task, including tasks under collapsed branches; "visible" fits only the currently expanded rows
• taskId? - (string | number) - fits a single task together with its subtree
• range? - (object) - fits an explicit date range with the start_date and end_date (Date) properties
• rangeMode? - ("auto" | "preserve" | "target") - whether to overwrite the displayed start_date/end_date with the fitted range. "target" always sets the fitted range, "preserve" keeps the current bounds, "auto" (default) preserves explicit bounds when they are set and sets the fitted range otherwise
• padding? - (number) - the number of extra columns added before the first and after the last fitted date. Default: 1
• minLevel? - (string | number) - the most detailed zoom level that zoomToFit is allowed to pick
• maxLevel? - (string | number) - the most coarse zoom level that zoomToFit is allowed to pick

When set via the fit property of init(), the configuration additionally accepts:

• levels? - (ZoomLevel[]) - a dedicated set of zoom levels considered only by zoomToFit. When omitted, the interactive zoom levels are used
• handler? - (Function): string | number | boolean | void - overrides the level selection. It receives a context object and should return a level name/index to apply, false to abort the fit, or nothing to keep the computed level
  • context - (object) - an object { range, viewportWidth, levels, padding, defaultLevel }, where defaultLevel is the level index the built-in algorithm picked

Options passed directly to zoomToFit() override the defaults set via init({ fit }).

gantt.ext.zoom.init({
    fit: {
        scope: "all",
        // a dedicated set of scales used only for fitting
        levels: [
            { name: "weeks", scale_height: 50, scales: [{ unit: "week", step: 1, format: "Week #%W" }] },
            { name: "months", scale_height: 50, scales: [{ unit: "month", step: 1, format: "%F, %Y" }] }
        ],
        handler: (context) => {
            // return a level name/index, false to abort, or nothing to keep the default
            return context.defaultLevel;
        }
    }
});

gantt.ext.zoom.zoomToFit();

Related sample: Zoom to fit

Events

• onAfterZoom - fires during switching of the zooming level. The arguments are:

• level - (number | string) - the number of the level
• config - (ZoomLevel) - the config of the level

gantt.ext.zoom.attachEvent("onAfterZoom", (level, config) => {
    document.querySelector(`.gantt_radio[value='${config.name}']`).checked = true;
});