Gantt Chart V2 Widget
Important
Overview
The Gantt Chart V2 widget provides an interactive, timeline-based view of tasks and resources, enabling users to plan, schedule, and monitor activities effectively. Tasks (jobs) appear as horizontal bars along a time axis and are organized vertically by resource (such as machines, operators, or vehicles). Each bar reflects a task’s start time and duration, making it easy to review, compare, and adjust schedules directly from within the AIMMS WebUI. This widget is particularly well suited for project management, production planning, workforce scheduling, and other resource allocation scenarios.
Built on Highcharts Gantt
The Gantt Chart V2 widget is built on top of the Highcharts Gantt library, developed by Highsoft AS, , the creators of the Highcharts visualization platform. For more details, refer to the official Highcharts Gantt documentation.
By leveraging Highcharts Gantt, AIMMS WebUI offers a rich and highly interactive environment for visualizing and managing time-based data. This integration enables advanced capabilities such as timeline zooming, drag-and-drop task manipulation, multi-level time axes, and flexible date and time formatting, all seamlessly embedded within the AIMMS WebUI framework.
In the example Gantt Chart shown above, several key features of the widget are illustrated:
- Pivoting of indices
Based on the configured pivot, the indices in the resources pivot order appear as rows. The corresponding tasks (jobs) are rendered as bars with their associated start and duration values.
- Clear representation of overlapping tasks
When tasks overlap, partially or fully, the chart renders them in a way that makes the overlap unambiguous and easy to see.
- Default or custom tooltips
Hovering over a task displays a tooltip (either default or customized) containing detailed task information.
- Text displayed inside task bars
Additional inline text can be shown inside bars to clarify task information. Long text will be clipped if it does not fit within the task’s width.
- Adaptive top X-axis
The top time axis automatically selects appropriate time units based on the visible time range. For shorter durations, it may show hours; for longer horizons, it will switch to days, weeks, or months.
- Contextual bottom X-axis
The bottom axis always shows the overall start and end dates of the chart. This helps users interpret the hours or more granular units shown on the top axis.
Note
This widget is optimized to handle large datasets efficiently by loading only sparse, and non-zero data. In practice, this means that only tasks with a positive (non-zero, non-negative) duration are rendered in the chart. This approach significantly improves performance and responsiveness when working with large or complex Gantt chart data.
Gantt chart Settings
Contents
The Gantt chart requires Start and Duration values for each task. In the Contents tab of the widget options editor, you can specify the identifiers that provide this Start and Duration data. Within the same tab, you can also configure the Display Domains for both, which determines which tasks or data points are included in the chart, similar to other widget types.
The following requirements apply:
The Start and Duration identifiers in your model must share the same index domain, which should include at least one task index.
The Start identifier must represent the number of hours relative to the Gantt Chart Reference Time.
The Duration identifier must represent the duration in hours of each corresponding task.
To support vertical dragging (moving tasks between resources), the Duration identifier in the AIMMS model must be updatable.
To support both vertical dragging and task modification (resizing), the Start and Duration identifiers must be updatable.
Important
display-domain option, please ensure it is configured thoughtfully. If no domain conditions are applied, the underlying identifiers may still process very large datasets, which can negatively affect the performance and responsiveness of the Gantt chart.MyDisplayDomainIdentifier(index1, index2) | JobDuration(index1, index2)Gantt Chart Settings
Along with specifying each task’s Start and Duration values, the Gantt Chart includes several additional configuration options available in the Gantt Chart Settings tab of the widget options editor.
The available Gantt Chart settings are described below:
- Reference time (required)
- Sets the reference point from which each task’s Start time is calculated.This can be specified using either a literal date/time value or a scalar string parameter.Accepted formats are
%c%y-%m-%dand%c%y-%m-%d %H:%M:%S.Examples:2025-01-312025-06-05 09:00:00Note: Do not use quotes when entering a literal date value.
- Time resolution in hours (required)
- Determines the smallest time increment for dragging or resizing tasks.Examples:A value of
1→ drag/resize in steps of one hourA value of0.25→ drag/resize in steps of 15 minutesNote: Must be a positive number greater than 0.This value defines the final position and duration of tasks when adjusted.
- Non-Overlapping Jobs (optional)
- By default, overlapping tasks within the same resource are displayed on top of each other.Enabling this option moves overlapping tasks to separate rows within the same resource, improving readability.This setting be configured via a literal binary switch or a scalar parameter.
Viewport Settings
- Viewport start time (optional)
- Specifies the leftmost visible time in the chart. Typically used with Viewport end time to define a display window.Can be set using a literal date value or a scalar string parameter.Accepted formats are the same as for Reference time.If left unset, the option appears empty, but internally the chart determines an appropriate start time to ensure all tasks are visible.
- Viewport end time (optional)
- Specifies the rightmost visible time in the chart. Typically used with Viewport start time to define a display window.Can be set using a literal date value or a scalar string parameter.Accepted formats are the same as for Reference time.If left unset, the option appears empty, but internally the chart determines an appropriate end time to ensure all tasks are visible.
- X-Axis (optional)
- By default, the chart automatically determines appropriate X-axis time intervals based on the tasks’ Start and Duration data, as well as the Viewport settings, ensuring an optimal, readable timeline display.For scenarios requiring custom control over the X-axis, the X-Axis option lets you define multiple time buckets and specify the format in which these intervals are displayed. Refer to this section for more details.
Pivoting
Index Settings and Store Focus
Select, Hover and Tooltips
When the user interacts with a job (task), by selecting/clicking it, horizontally dragging it or vertically dragging it, the corresponding job (horizontal bar) is visually highlighted, while all other jobs become slightly transparent. This makes the job interacted with stand out clearly.
When hovering over overlapping jobs, the job under the cursor is brought to the front. The hovered job retains full opacity, while the others are slightly faded, making inspection easier.
Hovering over a job also displays a tooltip. The tooltip may be:
the default tooltip, which shows detailed information about the job, or
a custom tooltip, defined using a
webui::TooltipIdentifierannotation on the Duration identifier configured in the Contents tab of the widget options editor.
Even when a job is selected, the user may hover over another job and view its tooltip. Hover behavior works the same way regardless of whether a job is currently selected.
Note
A selected job can be unselected by clicking on it again. In this case, the visual highlight is removed, but the stored focus value is not cleared or reset.
Inline Text
By default, no inline text is shown for jobs. Although default or custom tooltips show relevant information when hovering over a job on the chart, it is often more intuitive to display key information directly within the job’s horizontal bar.
By specifying a webui::ItemTextIdentifier annotation, as explained in the Identifier Annotations section for the Duration identifier configured in the Contents tab, you can configure the text to appear inline within the corresponding jobs.
Vertical Scrolling
The chart automatically adjusts the height of the jobs to display all resources and jobs within the available widget area.
A default minimum height is used for the jobs. When the Non-Overlapping Jobs option is enabled, or when there are many jobs that require a height greater than the minimum, the chart automatically enables vertical scrolling.
Custom Styling
By specifying a webui::AnnotationsIdentifier annotation, as described in the Identifier Annotations section, and by applying the techniques outlined in Custom Styling, you can define custom visual styles for jobs in the chart.
For example, in the current sample application, jobs with a duration greater than 5 days (120 hours) can be styled differently. An illustration of this modelling and styling is shown below:
.chart-item.annotation-RedFlag{
stroke: black !important;
stroke-width: 2px !Important;
stroke-dasharray: 5,3; /* dotted or dashed */
stroke-linecap: round; /* optional, makes dots rounded */
fill: red;
}
Widget Extensions
In the Widget Extensions tab of the widget options editor, you can add the string parameters associated with the Widget Actions. Once these parameters are set, the corresponding widget actions become accessible via the icon displayed in the widget header.
Miscellaneous
In the Miscellaneous tab of the widget options editor, several additional options can be configured. These include:
the Title of the widget, which appears in the widget header, and
a Visible option, which determines whether the widget is displayed on the page.
Both of these settings may be specified directly as literals or through model identifiers.
Customizing X-Axis Intervals
Adding and Configuring X-Axis Intervals
Time Interval (optional)
- You can select one of the predefined time intervals:
Year
Quarter
Month
Week
Day
Hour
Alternatively, you can provide a string parameter whose value matches (case-insensitive) one of the supported options.
Important
You can use either the default interval or custom intervals, but not both simultaneously.
Multiple custom intervals with the same interval type are supported.
When other custom intervals are configured, leaving this option unset in a pair causes that pair to be ignored.
If a string parameter does not match any supported interval, an error message will appear, and the X-axis interval will be ignored.
Label Format (optional)
By default, labels are automatically determined based on the selected Time Interval and available space. The Label Format option allows you to customize how time intervals are displayed on the X-axis.You can provide either a literal string or a scalar string parameter, which can include static text and specific format keywords that are replaced with corresponding values.Examples of format usage:%d %b→12 Nov%b %y→Nov 2025
Supported Time Interval Label Formats
Key |
Description |
Locale Notes |
|---|---|---|
%q |
Quarter number |
|
%W |
Week number |
|
%A |
Full weekday name (e.g., “Monday”) |
|
%a |
Abbreviated weekday name (e.g., “Mon”) |
|
%E |
Narrow weekday (single letter) |
|
%d |
Two-digit day (01–31) |
|
%e |
Day (1–31) |
|
%w |
Day of the week (0–6) |
N/A |
%b |
Abbreviated month name (e.g., “Jan”) |
|
%B |
Full month name (e.g., “January”) |
|
%m |
Two-digit month (01–12) |
|
%o |
Month number (1–12) |
|
%y |
Two-digit year (e.g., “25” for 2025) |
|
%Y |
Four-digit year (e.g., “2025”) |
|
%H |
Hour (00–23) |
Locale may display in 12-hour format |
%k |
Hour (0–23) |
Locale may display in 12-hour format |
%I |
Hour (00–11, 12-hour format) |
N/A |
%l |
Hour (1–12, 12-hour format) |
N/A |
%M |
Minutes (00–59) |
|
%p |
Uppercase AM/PM |
Locale-dependent |
%P |
Lowercase am/pm |
Locale-dependent |
%S |
Seconds (00–59) |
|
%L |
Milliseconds |
Example Label Formats
You can combine multiple format keys to fully customize the X-axis label appearance. Formatting follows standard C-style conventions and supports locale-aware names for weekdays, months, and time indicators.
Format String |
Example Output |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Important
The chart automatically adjusts the time interval labels to fit within the widget’s width.
If a label is too wide to fit within its allocated space, it may not be displayed.
Adding, Deleting and Modifying Tasks
Adding Task
Adding a task directly on the Gantt chart is not supported.
Deleting Task
Deleting a task directly from the chart is not supported.
Tip
- You can use modern workflow features to create a smoother user experience when creating, modifying, or deleting tasks. For example:
Create - Open a dialog page using Gantt Chart widget actions or page actions.
Modify - Use an item action (possibly opening a dialog page).
Delete - Use an item action (possibly opening a dialog page).
Modifying a task
Horizontal Dragging
Vertical Dragging
the Duration identifier must be editable.
when a task is dragged to a resource that already contains a task with the same index combination, the existing task is replaced, and the newly dragged task is retained.
if the last remaining task in a row is moved away, the original row will disappear, because WebUI displays data sparsely.
Snapping to time resolution while dragging
During both horizontal and vertical dragging, the time resolution defined in the widget properties is respected. Tasks will “snap” to the nearest configured time unit.
Restricting Tasks Movement
All Tasks Read-Only
To make the task start and duration values read-only, remove the corresponding identifiers from the built-in AIMMS set CurrentInputs:
CurrentInputs := CurrentInputs - 'TaskStart' - 'TaskDuration';
where TaskDuration and TaskStart are your task duration parameter and your task start parameter respectively. Obviously, start or duration parameters with a definition in AIMMS are also read-only.
Cherry-Picking Read-Only Tasks
By specifying a webui::FlagsIdentifier annotation, as explained in webui::FlagsIdentifier for the Start and Duration identifiers configured in the Contents tab, you can make specific task properties read-only.
If the task’s Start property is read-only, the task cannot be moved horizontally, but its duration can still be modified using horizontal dragging.
If the task’s Duration property is read-only, the task cannot be resized.
If both the Start and Duration properties are read-only, the task cannot be moved or resized, and the drag handles will not be displayed when hovering over the task.
Custom Horizontal Scrolling or Zooming Behavior
You can implement custom scrolling or zooming behavior in the Gantt chart by using AIMMS string parameters to specify the viewport start time and viewport end time.
Typically, a procedure will convert the string into a moment, perform arithmetic on the moment, and then convert it back into a string. The following example demonstrates identifiers and procedures that allow scrolling the Gantt chart to the left or right.
StringParameter ViewportStart;
StringParameter ViewportEnd;
Procedure MoveDate {
Arguments: (dateString, numHours);
Body: {
moment := StringToMoment("%m-%d-%c%y %H:%M", [hour], "2016-01-01 00:00", dateString);
moment += numHours;
dateString := MomentToString("%m-%d-%c%y %H:%M", [hour], "2016-01-01 00:00", moment);
}
StringParameter dateString {
Property: InOut;
}
Parameter numHours {
Unit: hour;
Property: Input;
}
Parameter moment {
Unit: hour;
}
}
Procedure ScrollViewport {
Arguments: (numHours);
Body: {
MoveDate(ViewportStart, numHours);
MoveDate(ViewportEnd, numHours);
}
Parameter numHours {
Unit: hour;
Property: Input;
}
}
Procedure ViewportScrollToTheRight {
Body: {
ScrollViewport(1[hour]);
}
}
Procedure ViewportScrollToTheLeft {
Body: {
ScrollViewport(-1[hour]);
}
}
Note
The AIMMS function StringToMoment is used to convert a date string into a numeric moment, which allows easy date arithmetic. After calculations, the number is converted back into a date string using MomentToString.
Developer Settings: Adjusting the Tasks Count Threshold
Important
This widget has been optimized to efficiently handle large datasets by selectively loading only sparse, non-zero data. By default, it will process and fetch up to 1,500 tasks (jobs). If this limit is exceeded, an error message similar to the one below will be displayed:
MainProject\WebUI\resources\javascript\webui-options.js. If this file does not already exist in the resources subfolder, it will be automatically created when WebUI is launched in developer mode.webui_ganttchart_jobs_overload_threshold key to the desired value./* Configure the Gantt Chart widget's task overload threshold */
webui_ganttchart_jobs_overload_threshold = 2000;
The setting shown in the example above means that any Gantt chart in the WebUI will display a maximum of 2,000 tasks in it.
Guidelines and Recommendations
While the Gantt chart may display only a few tasks, it might still be processing a large amount of data in the background. This can negatively impact the chart’s performance and responsiveness. When using the
display-domainoption, we recommend applying domain conditions on the display domain identifier to limit the amount of data being processed. For example, including the Duration identifier as a domain condition ensures that only jobs likely to appear on the chart are considered, improving overall efficiency.Similarly, for identifiers used in tooltips, inline text, annotations, and other chart elements, we recommend including the Duration identifier as a domain condition. This ensures that only relevant data is evaluated and helps maintain efficient data modelling.
Avoid adding highly granular X-axis intervals when the viewport spans a large time range (for example, a full year or multiple years). Defining intervals at a very fine resolution, such as minutes or days over such a wide range can significantly degrade chart performance.
To prevent a job from being added outside a specific time range, apply the appropriate index domain condition on the Start and/or Duration identifier. This ensures that the job can only take values within the allowed range.