Datepicker: Add option for onUpdateDatepicker callback

[patrick-vandy]

Add a new option named onUpdateDatepicker that allows a custom callback to be provided. If provided, the callback is called at the end of $.datepicker._updateDatepicker.

Problem

Currently, there is not a good way to manipulate the DOM for the datepicker calendar. Using a common example, if you want to add a custom button, you have to do it in a callback on both beforeShow and onChangeMonthYear.

If using an inline datepicker, you also have to add the custom button in onSelect. Furthermore, If you call $('.my-date-picker').datepicker('refresh');, the custom button goes away and there is no callback option or event to use for adding it back.

Here is one of many stackoverflow.com posts on this problem.

This makes it difficult (sometimes impossible) to customize the datepicker calendar using the provided options, which leads to horrible hacks like this:

$.datepicker._base_updateDatepicker = $.datepicker._updateDatepicker;
$.datepicker._updateDatepicker = function (inst) {
    this._base_updateDatepicker(inst);
    // do custom stuff
};

Solution

Ideally, datepicker would trigger events like afterUpdate.datepicker and developers could then easily add event handlers to customize the behavior. However, since this isn't the current approach, I chose to add another callback option named onUpdateDatepicker that is always called (if defined) at the end of _updateDatepicker. This is a quick and easy solution that follows the current conventions of datepicker.

The following can now be used to customize the calendar in one place:

$('.my-date-picker').datepicker({
    onUpdateDatepicker: function(inst) {
        // do custom stuff
    }
});

Notes

I didn't see anything on how to update the documentation. If someone can please point me in the right direction, I will include updates for https://api.jqueryui.com/datepicker/.

[fnagel]

+1 by reading

The commit message "Datepicker: improve callbacks test for onUpdateDatepicker " should read "Datepicker: Improve callbacks test for onUpdateDatepicker"

@mgol Can we fix the commit message when merging?

[fnagel]

Interesting PR! Seems like a valid use case and a proper approach.

Docs need a PR against https://github.com/jquery/api.jqueryui.com/blob/main/entries/datepicker.xml

@mgol I'm fine with this PR. What do you think? How to deal with the needed docs update?

Too bad the rewrite has never been released. It's using the widget factory and is much easier to extend :-(
https://github.com/jquery/jquery-ui/blob/datepicker/ui/widgets/calendar.js
https://github.com/jquery/jquery-ui/blob/datepicker/ui/widgets/datepicker.js

[patrick-vandy]

Docs need a PR against https://github.com/jquery/api.jqueryui.com/blob/main/entries/datepicker.xml

@mgol I'm fine with this PR. What do you think? How to deal with the needed docs update?

@fnagel I cloned api.jqueryui.com and started updating datepicker.xml to include this option. However, I don't see how to provide example code for the option. For example, looking at the prevText option on that page I see code examples:

But looking at prevText in datepicker.xml I don't see where that's defined. I global searched the repo for prevText (and some other options with examples) but could not find where these examples are defined. Can you let me know how, as I'd like to include examples.

[patrick-vandy]

The commit message "Datepicker: improve callbacks test for onUpdateDatepicker " should read "Datepicker: Improve callbacks test for onUpdateDatepicker"

@fnagel I've updated the commit message 🙂

[mgol]

@patrick-vandy I did a bit of research and it seems code examples are generated based on metadata using one of the patterns from the https://github.com/jquery/grunt-jquery-content repository. This particular example is using this pattern:
https://github.com/jquery/grunt-jquery-content/blob/4534d3e6771cfea2d69a110d65cf33b88467a764/tasks/jquery-xml/entries2html-base.xsl#L594-L653

I'd start with making sure the new option is properly documented in the signatures section in entries/datepicker.xml and there's a chance the example will be generated automatically if you fill in all required fields.

[patrick-vandy]

@fnagel @mgol Okay, I've opened jquery/api.jqueryui.com#334 to add this new option to the documentation. Let me know if there's anything else that needs to happen.

Also, I just realized on this PR I committed to master (though it looks like jQuery is using main now) instead of creating a feature branch on my fork. I can make a new branch off main and cherry pick my commits from this PR into a feature branch, then reopen a PR. Let me know if I should do that.

[fnagel]

@patrick-vandy No need to change the source branch and the target branch has been changed from master to main by GH.