Dynamics 365 F&O
X++
JavaScript
Extensible controls
AX 2012 upgrade

Calendar week numbers in the D365 F&O date picker

AX 2012 showed calendar weeks in its date lookup, D365 F&O does not. How I added ISO week numbers to every date picker with X++ and JavaScript.

Ertugrul BalverenManaging Director, D365FO Technical Solution Architect7 October 20269 min read

The result on a purchase order: the Wk column shows the ISO week of each row. Customer data is blurred.

On this page+

On a customer project moving from Dynamics AX 2012 to Dynamics 365 Finance and Operations, we got a requirement that sounds small: show calendar week numbers in the date picker. The purchasing and logistics teams plan deliveries by week. In AX 2012 the date lookup showed the week number at the start of every row, and they used it all day. In D365 F&O it is gone, and there is no setting to bring it back. Microsoft has an idea for it from 2019 that is still open.

This post shows how I added ISO week numbers to every date picker in the web client, with one X++ extensible control and a small JavaScript file. All the code is below, so you can use it in your own project.

Why there is no property to switch on

In AX 2012 the week numbers were one property on the SysDateLookUp form: ShowRowLabels = Yes on the days table. My first idea was to find the same form in D365 F&O. It exists, but the web client does not use it for the normal date picker.

The D365 F&O date picker is pure client code, and there are two of them:

Date fields on forms and dialogs use a jQuery UI datepicker. jQuery UI has showWeek, weekHeader and calculateWeek built in. The standard client never sets them.
Date cells in grids use a React date picker from the grid control library. That class is private, has no week option, and does not use jQuery at all.

So one fix has to cover both. I found this by reading the client scripts in PackagesLocalDirectory/bin/DesignTimePreview/Scripts before writing any code. That saved me from building a replacement picker.

The approach

An invisible extensible control

It carries the script, the CSS and the label to the browser.

An event handler on FormRun.onFormRun

It adds the control to every form at run time. No form needs a design change, and the week numbers work no matter which form a user opens first.

Form fields: switch on what jQuery UI already has

The script sets the jQuery UI defaults once: showWeek, the localized header text and the week calculation.

Grids: mark the rows, let CSS draw

A MutationObserver watches for an open grid date picker. It writes the week number into a data- attribute on the first cell of each row, and CSS draws it with ::before. The table structure is never changed, so the React component does not notice anything.

If a platform update changes the client internals, the worst case is that the week numbers disappear. Nothing else breaks.

The solution has seven objects:

BALCalendarWeekNumbersBuild
X++ class
Design time part of the control.
BALCalendarWeekNumbersControl
X++ class
Run time control, adds itself to a form.
BALFormRunEventHandler
X++ class
Subscribes to FormRun.onFormRun.
BALCalendarWeekNumbers.htm
Resource
Control template, loads script, styles and label.
BALCalendarWeekNumbers.js
Resource
Week logic for both pickers.
BALCalendarWeekNumbers.css
Resource
Layout of the week column.
BALCalendarWeek
Label file
Column header: KW in German, Wk in English.

The X++ part

The build class

The build class only has to exist and carry the attribute that links it to the control name.

BALCalendarWeekNumbersBuild.xppX++

1/// <summary>2/// The build class for the calendar week numbers control.3/// </summary>4[FormDesignControlAttribute("BALCalendarWeekNumbers")]5public class BALCalendarWeekNumbersBuild extends FormBuildControl6{7}

The control

The control points to its HTML resource. The static addToForm method adds it to a form once, and skips fact boxes so it is not added many times on the same page.

BALCalendarWeekNumbersControl.xppX++

1/// <summary>2/// Invisible control that enables calendar week numbers in all date pickers of the web client session.3/// </summary>4[FormControlAttribute("BALCalendarWeekNumbers", "/resources/html/BALCalendarWeekNumbers", classStr(BALCalendarWeekNumbersBuild))]5public class BALCalendarWeekNumbersControl extends FormTemplateControl6{7    private const str ControlName = "__BALCalendarWeekNumbers";89    protected void new(FormBuildControl _build, FormRun _formRun)10    {11        super(_build, _formRun);1213        this.setTemplateId("BALCalendarWeekNumbers");14        this.setResourceBundleName("/resources/html/BALCalendarWeekNumbers");15    }1617    /// <summary>18    /// Adds the control to a form at run time, so that week numbers are enabled in every web client19    /// session, independent of the start page.20    /// </summary>21    /// <param name = "_formRun">The form instance.</param>22    public static void addToForm(FormRun _formRun)23    {24        FormDesign formDesign;2526        if (!_formRun || _formRun.isFactBox())27        {28            return;29        }3031        formDesign = _formRun.design();3233        if (formDesign && !formDesign.controlName(ControlName))34        {35            formDesign.addControlEx(classStr(BALCalendarWeekNumbersControl), ControlName);36        }37    }38}

The event handler

onFormRun is a static delegate on a kernel class, so an event handler is the only option here. If your model already has a handler class for FormRun, put the method there instead of creating a new class.

BALFormRunEventHandler.xppX++

1/// <summary>2/// Events that apply to all form instances.3/// </summary>4public class BALFormRunEventHandler5{6    /// <summary>7    /// Adds the calendar week numbers control before the form is run.8    /// </summary>9    /// <param name = "_formRun">The form instance.</param>10    [SubscribesTo(classStr(FormRun), staticDelegateStr(FormRun, onFormRun))]11    public static void FormRun_onFormRun(FormRun _formRun)12    {13        BALCalendarWeekNumbersControl::addToForm(_formRun);14    }15}

The resources

Add the three files as resources to the project in Visual Studio (Add, New item, Resource). The browser loads them by file name, under /resources/html/, /resources/scripts/ and /resources/styles/.

HTML template

The template loads the CSS, the script and the label file in the language of the user. The div itself is hidden.

BALCalendarWeekNumbers.htmHTML

1<link rel="stylesheet" type="text/css" href="/resources/styles/BALCalendarWeekNumbers.css" />2<script src="/resources/scripts/BALCalendarWeekNumbers.js"></script>3<script src="/resources/labels/BALCalendarWeek.js"></script>45<div id="BALCalendarWeekNumbers" class="balCalendarWeekNumbers" data-dyn-bind="6     visible: $data.Visible,7     attr: { name: $data.Name },8     sizing: $dyn.layout.sizing($data)"></div>

Labels

The header text comes from a label, read in the browser with $dyn.label, the same way standard controls do it. Use a small label file of its own for this. The URL /resources/labels/<file>.js sends the whole label file to the browser, and a big project label file can easily be a few hundred KB.

BALCalendarWeek.label.txtText

1BALCalendarWeek.en-US.label.txt2WeekHeader=Wk3 ;Header of the week number column in date pickers45BALCalendarWeek.de.label.txt6WeekHeader=KW7 ;Header of the week number column in date pickers

JavaScript

This is the core. weekOfRow is used by both pickers, so a form field and a grid always show the same number for the same row.

BALCalendarWeekNumbers.jsJavaScript

1(function () {2    'use strict';34    var datePickerSelector = '.dyn-datePicker';5    var weekTableClass = 'balCalendarWeekTable';6    var weekAttribute = 'data-bal-calendar-week';7    var weekColorProperty = '--bal-calendar-week-color';8    // Label @BALCalendarWeek:WeekHeader, loaded by the HTML resource in the language of the user.9    var weekHeaderLabel = 'BALCalendarWeek_WeekHeader';10    var daysPerWeek = 7;11    var millisecondsPerDay = 86400000;1213    var weekHeaderText;14    var initialized = false;15    var markPending = false;1617    // Returns the ISO 8601 week number of a local date.18    function isoWeek(date) {19        var thursday = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));20        var yearStart;2122        thursday.setUTCDate(thursday.getUTCDate() + 4 - (thursday.getUTCDay() || daysPerWeek));23        yearStart = Date.UTC(thursday.getUTCFullYear(), 0, 1);2425        return Math.ceil(((thursday - yearStart) / millisecondsPerDay + 1) / daysPerWeek);26    }2728    // A calendar row is labelled with the week of its Monday. Both pickers use this function,29    // so a row shows the same number in a form field and in a grid for every first day of the week.30    function weekOfRow(firstDateOfRow) {31        var monday = new Date(firstDateOfRow.getFullYear(), firstDateOfRow.getMonth(), firstDateOfRow.getDate());3233        monday.setDate(monday.getDate() + (daysPerWeek + 1 - monday.getDay()) % daysPerWeek);3435        return isoWeek(monday);36    }3738    // Parses a date in the format YYYY-MM-DD as a local date.39    function parseIsoDate(dateText) {40        var parts = dateText.split('-');4142        return new Date(+parts[0], +parts[1] - 1, +parts[2]);43    }4445    // Week numbers for the jQuery UI date pickers (date fields on forms and dialogs).46    // jQuery UI calls calculateWeek with the first date of each calendar row.47    function enableJQueryWeekNumbers() {48        if (typeof $ === 'undefined' || !$.datepicker) {49            return;50        }5152        $.datepicker.setDefaults({53            showWeek: true,54            weekHeader: weekHeaderText,55            calculateWeek: weekOfRow56        });57    }5859    function setWeekAttribute(cell, value) {60        if (!value) {61            if (cell.hasAttribute(weekAttribute)) {62                cell.removeAttribute(weekAttribute);63            }64        }65        else if (cell.getAttribute(weekAttribute) !== value) {66            cell.setAttribute(weekAttribute, value);67        }68    }6970    function hasVisibleDay(datedCells) {71        return Array.prototype.some.call(datedCells, function (cell) {72            return !!cell.textContent;73        });74    }7576    // The week number is drawn inside the first day cell and would inherit its colour, which is white77    // on the selected day and grey on a day of another month. It gets the colour of the header instead.78    function setWeekColor(table) {79        var header = table.querySelector('thead');80        var color = header ? window.getComputedStyle(header).color : '';8182        if (color && table.style.getPropertyValue(weekColorProperty) !== color) {83            table.style.setProperty(weekColorProperty, color);84        }85    }8687    function markRow(row) {88        var cells = row.children;89        var datedCells = row.querySelectorAll('[data-date]');9091        if (!cells.length) {92            return;93        }9495        if (!datedCells.length) {96            if (cells.length === daysPerWeek) {97                setWeekAttribute(cells[0], weekHeaderText);98            }99100            return;101        }102103        // The grid picker appends a row without visible days when the month ends on the last weekday.104        if (!hasVisibleDay(datedCells)) {105            setWeekAttribute(cells[0], '');106            return;107        }108109        setWeekAttribute(cells[0], String(weekOfRow(parseIsoDate(datedCells[0].getAttribute('data-date')))));110    }111112    // Week numbers for the date pickers of the grid control. The week number is written as an attribute113    // on the first cell of each row and rendered by CSS, the table structure itself is not changed.114    function markDatePickers() {115        var tables = document.querySelectorAll(datePickerSelector + ' table');116117        Array.prototype.forEach.call(tables, function (table) {118            if (!table.querySelector('[data-date]')) {119                return;120            }121122            if (!table.classList.contains(weekTableClass)) {123                table.classList.add(weekTableClass);124            }125126            setWeekColor(table);127128            Array.prototype.forEach.call(table.querySelectorAll('tr'), markRow);129        });130    }131132    // Marks the open grid date pickers at most once per animation frame; returns immediately if none is open.133    function scheduleMark() {134        if (markPending) {135            return;136        }137138        markPending = true;139140        window.requestAnimationFrame(function () {141            markPending = false;142143            if (document.querySelector(datePickerSelector)) {144                markDatePickers();145            }146        });147    }148149    // The grid picker changes data-date on every cell when the month changes,150    // so text changes do not have to be observed.151    function observeDatePickers() {152        new MutationObserver(scheduleMark).observe(document.body, {153            childList: true,154            subtree: true,155            attributes: true,156            attributeFilter: ['data-date']157        });158159        scheduleMark();160    }161162    // Runs once per browser page, with the first form that carries the control.163    function initialize() {164        if (initialized) {165            return;166        }167168        initialized = true;169        weekHeaderText = $dyn.label(weekHeaderLabel);170171        enableJQueryWeekNumbers();172        observeDatePickers();173    }174175    $dyn.ui.defaults.BALCalendarWeekNumbers = {};176177    $dyn.controls.BALCalendarWeekNumbers = function (data, element) {178        var self = this;179180        $dyn.ui.Control.apply(self, arguments);181        $dyn.ui.applyDefaults(self, data, $dyn.ui.defaults.BALCalendarWeekNumbers);182183        initialize();184    };185186    $dyn.controls.BALCalendarWeekNumbers.prototype = $dyn.extendPrototype($dyn.ui.Control.prototype, {});187})();

CSS

BALCalendarWeekNumbers.cssCSS

1.balCalendarWeekNumbers {2    display: none;3}45/* jQuery UI date pickers (date fields on forms and dialogs) */6.ui-datepicker td.ui-datepicker-week-col {7    vertical-align: middle;8    text-align: center;9    padding-right: 8px;10    opacity: 0.7;11}1213.ui-datepicker th.ui-datepicker-week-col {14    text-align: center;15    padding-right: 8px;16    font-weight: normal;17}1819/* Grid date pickers: the week number is rendered from the data-bal-calendar-week attribute of the first cell */20.balCalendarWeekTable {21    margin-left: 30px;22}2324.balCalendarWeekTable [data-bal-calendar-week] {25    position: relative;26}2728.balCalendarWeekTable [data-bal-calendar-week]::before {29    content: attr(data-bal-calendar-week);30    color: var(--bal-calendar-week-color);31    position: absolute;32    left: -32px;33    width: 26px;34    text-align: center;35    opacity: 0.7;36    font-weight: normal;37    pointer-events: none;38}

Testing it in the browser

Build the model, then open any form in the web client with the browser developer tools open. On the Network tab, turn on Disable cache. Otherwise the browser keeps serving an old copy of the script and you keep testing yesterday's version. After a reload you should see the HTML, CSS and JS resources of the control being loaded, and the week column in every date picker you open.

D365 F&O date picker with week numbers next to the browser developer tools, Network tab with Disable cache checked and the CalendarWeekNumbers htm, css and js files loaded — Network tab with Disable cache on: the control's HTML, CSS and JavaScript are loaded, and the date field shows the Wk column. Company and object prefixes are blurred.

Things worth checking:

A date field on a form, a date field in a dialog and a date cell in a grid. These are the two different pickers.
A user whose week starts on Sunday (user options, date format) and one whose week starts on Monday.
A month that ends on the last day of the week, for example May 2026.
The selected day and days of the previous or next month, in light and dark theme.

Details that took the most time

Sunday first users. jQuery UI calls calculateWeek with the first date of each row. For a user whose week starts on Sunday, that is a Sunday, and the ISO week of a Sunday belongs to the previous week. So a form field showed 40 while the grid showed 41 for the same row. The fix is weekOfRow: both pickers take the week of the Monday in that row.

An empty last row. The grid picker adds a row without visible days when a month ends on the last weekday. Without a check, that empty row got a week number. hasVisibleDay skips it.

The invisible number. The number is drawn inside the first day cell, so it took that cell's text colour. On the selected day that is white on white, and on days of another month it is grey. The script copies the header colour into the CSS variable --bal-calendar-week-color, so the number always looks like the header.

ISO weeks only. The code uses ISO 8601 weeks (week 1 contains the first Thursday of the year), which is what German and most European users expect. AX 2012 followed the Windows regional settings, which gives the same result for German settings. If your users need US style week numbers, change isoWeek.

Summary

Three X++ classes, three resource files and one label, about 300 lines in total, and the users have their week numbers back in every date picker. No standard form was changed and no form needs its own code.

If you want this in the standard product, vote for the Microsoft idea. If you need help moving from AX 2012 to D365 F&O, or with a gap like this one, talk to us.