Version: 1.0.0

Time zones

The TimeZone module manages date/time conversion, formatting, and rendering offsets. It provides standard APIs to register custom timezones, fetch formatting components, and toggle timezones on active charts.

TimeZone Registry & API

The core engine registers global timezones via the window.TimeZone interface. This registry matches client-friendly display labels with official IANA timezone identifiers:

TimeZone Module API Methods

TimeZone.registerTimezone(label, tz)
Registers a display label (e.g. New York) mapping to a timezone identifier (e.g. America/New_York). It also accepts local to adapt to the user's browser runtime environment.
TimeZone.getTimezones()
Returns an array of registered timezone definitions: { label: string, tz: string }[].
TimeZone.getDateParts(chart, date)
Resolves the chart's current active timezone using chart.getTimezone() and parses the supplied date (timestamp or object) using Intl.DateTimeFormat. Returns a key-value dictionary of string subdivisions (year, month, day, hour, minute).

Example: Retrieving Date Parts

// Returns formatted parts based on chart's timezone (e.g., Tokyo)
const parts = window.TimeZone.getDateParts(chart, 1776510000000);
console.log(parts); // { year: "2026", month: "Jun", day: "12", hour: "18", minute: "04" }

Chart Instance API Injection

The TimeZone script dynamically extends the BacktestxChartCore prototype to equip all instantiated widgets with timezone getter and setter routines:

setTimezone(tz): Assigns the new timezone identifier to this.timezone, dynamically locates the top toolbar timezone selector button to update its text span, and triggers a full canvas render() to redraw time scale tick labels.
getTimezone(): Resolves the active timezone. Falls back to configured widget options, then the developer's default property (window.TimeZone.defaultTimezone), and lastly to UTC.

// Switch active chart instance timezone
chart.setTimezone('America/New_York');

// Check active chart instance timezone
console.log(chart.getTimezone()); // 'America/New_York'

During DOM initialization, the module registers a timezone selection widget with the global ChartingAPI. This adds a dedicated timezone button to the top toolbar panel:

Dropdown Behavior & UI Styling

When clicked, a dropdown container (.timezone-dropdown-menu) displays all registered timezones. The active timezone is highlighted (.active) with a green accents theme. Clicking outside the dropdown automatically collapses it.

window.ChartingAPI.registerTopToolbarButton('timezone', {
  label: initialTzLabel,
  tooltip: 'Select Chart Timezone',
  iconSvg: '<svg...></svg>',
  onClick: function(chart, btn, e) {
    e.stopPropagation();
    toggleTimezonePopup(btn, chart);
  }
});

Custom Developer Configuration (custom-timezone.js)

Developers can customize the default timezone and the list of available timezone options by editing the custom-timezone.js file in the application's root directory:

// Registering developer custom timezones:
window.TimeZone.registerTimezone('UTC', 'UTC');
window.TimeZone.registerTimezone('Exchange', 'local');
window.TimeZone.registerTimezone('New York', 'America/New_York');
window.TimeZone.registerTimezone('London', 'Europe/London');
window.TimeZone.registerTimezone('Tokyo', 'Asia/Tokyo');
window.TimeZone.registerTimezone('Mumbai', 'Asia/Kolkata');
window.TimeZone.registerTimezone('Sydney', 'Australia/Sydney');

// Set the default timezone when the chart loads:
window.TimeZone.defaultTimezone = 'UTC';