3.5 - Dateline

<schedule-date-line [gantt]="gantt"></schedule-date-line>

The dateline requires a reference to the gantt element to operate. Date units are calculated using the node package js-joda under the hood. One of the reasons to use this library is its compatibility with Java Instant. The js-joda library is required by ScheduleJS and you could also use it to apprehend time units in your project. More info on this library can be found here in the js-joda documentation.

Introduction

The dateline displays the actual dates (Mo, Tu, We, ...) in cells that are placed on one or more rows. The dateline is timezone aware, keeps track of currently selected time intervals and the current hover time interval. It also fires events whenever the visible time range changes (e.g. after scrolling left or right). You can access the dateline using the following method this.gantt.getTimeline().getDateline().

Scale Resolutions

The dateline can display one to five rows. Each row is called a "dateline scale" and each one of these scales displays a "resolution". A resolution is comprised of a temporal unit (e.g. day, week, month), a pattern for formatting, and a quantity. The quantity is needed to specify resolutions like "5 minutes", "15 minutes", and so on. The entire list of resolutions that are currently shown by the dateline can be retrieved by calling dateline.getScaleResolutions(). 

One example for a use of this method is given by the system layer GridLinesLayer. It calls this method in order to use the resolutions to calculate the locations of the vertical grid lines. For this the Resolution class offers the methods truncate() to go to the beginning of a unit (e.g. the beginning of a day) and increment() to go to the next unit (e.g. the next day). For more information on Resolution please go to the dateline model documentation.

Primary Temporal Unit

A dateline with three scales could for example display the resolutions "month", "week", and "day". The smallest resolution "day" gets displayed at the bottom of the dateline. The temporal unit ChronoUnit.DAYS that is used by this resolution is also called "primary temporal unit".  You can access the current value of this unit by calling the method dateline.getPrimaryTemporalUnit(). The value of this property is used when querying activities from activity repositories. This way the repository can decide how fine-grained the result of its invocation will be or if certain activities will not be shown at all.

One example for a good use of the primary temporal unit is the WeekendCalendar class. It implements Calendars, which is an extension of ActivityRepository. The purpose of the WeekendCalendar is to return the weekend days (Saturday, Sunday) for a given time interval. When it gets invoked it will not return anything if the primary temporal unit is too large or too small. It makes no sense to return weekend information if the user is currently looking at minutes or decades.

Timezone

The dateline needs to know for which timezone it is displaying the dates (e.g. EST or GMT). Hence it features the property zoneId. It is writable and can be set via dateline.setZoneId().

Selection Model

The dateline allows the user to perform selection of time interval by clicking the primary mouse button and then dragging over the desired time interval.

So if the dateline is currently showing weeks and days then the user can only select an entire weeks or entire days. This list of selected intervals can be retrieved by calling dateline.getSelectedTimeIntervals(). 

Hover Time Interval

When the mouse cursor hovers over the dateline it also implies that it is hovering over a time interval. Depending on the resolution shown in the dateline row / scale at the given mouse location the interval might be an entire week or a single day. Whatever it is, the interval is accessible by calling dateline.getHoverTimeInterval().

Events

Applications can listen to scrolling events fired by the dateline when they need to react to any changes in the currently visible time range. This is done by subscribing to an observable using the Transactional Abstract Component subscribe API: 

this.subscribe(this.gantt.getGraphics().getTimelineModelChangeObs(), (event) => console.log(event));