Replacing Selectize with Tom Select

[mflorea]

Hi everyone,

We’re using Selectize quite a lot in XWiki (46 files match the word “selectize” in xwiki-platform) to implement various suggest input pickers. Unfortunately this library is not maintained since 2022 and its last release has serious regressions that make it unusable (see Loading...):

• data-* attribute regression/bug since 0.15 to 0.15.2 · Issue #2036 · selectize/selectize.js · GitHub
• Select loses change trigger · Issue #1969 · selectize/selectize.js · GitHub
• lost data() value after selectize() · Issue #1958 · selectize/selectize.js · GitHub

Moreover, Selectize depends on jQuery and it uses deprecated jQuery APIs, preventing us from upgrading jQuery to version 4.x where those APIs have been removed.

Given this, I started looking for alternatives, but you have to know that replacing Selectize is not simple and will for sure lead to some regressions / breakages in our extensions. Even though we have a wrapper around Selectize, xwiki-selectize, we expose directly the Selectize JavaScript API, and there is of course the HTML structure and the CSS classes that some extensions may rely on as well.

There are two libraries that offer similar features and seem to be maintained:

• GitHub - Choices-js/Choices: A vanilla JS customisable select box/text input plugin ⚡️
• GitHub - orchidjs/tom-select: Tom Select is a lightweight (~16kb gzipped) hybrid of a textbox and select box. Forked from selectize.js to provide a framework agnostic autocomplete widget with native-feeling keyboard navigation. Useful for tagging, contact lists, etc.

The later is particularly interesting because it started as a fork of Selectize, so we can expect less API breakage. With this in mind, I started updating the xwiki-platform code to replace Selectize with Tom Select to see how well it works and to evaluate how big is the breakage. The result is:

• It works quite well. I haven’t noticed any regressions in behavior compared to Selectize.
• It doesn’t provide a Bootstrap 3 CSS but it provides CSS for Bootstrap 4 and 5, so we’ll have to tweak a bit the CSS to be consistent with the rest of our form controls (but it generally looks good out of the box).
• I haven’t noticed any API breakage on the JavaScript side, which is quite surprising.
• But the HTML structure is slightly different and the CSS classes have changed (ts-* vs. selectize-*). This means I had to update our CSS, the test page objects and all the rest of the code that was using selectize-* CSS classes.
• I also noticed an incompatibility with Prototype.js but fortunately we have ways to patch Prototype.js to workaround this.

Overall it looks good. I’m currently running the integration tests to see if I missed anything. If all is OK I’d like to push this change on 18.2.0RC1 along with the jQuery 4.x upgrade.

Thanks,
Marius

[CharpentierLucas]

Thank you for conducting this research!

Both projects seem to consider accessibility. I noticed Tom Select have a config for automated accessibility testing, which is great (even though they didn’t update this config in years)! I looked further, and it seems they deactivated it three years ago…

When checking their demo pages, Axe-core finds WCAG violations on both (numbers below exclude contrast issues that will not impact us anyways) :

• 25 on Basic Examples - Tom Select (but there’s a few console errors that probably mean something is not working as expected)
• 5 on Choices

+1 from me to use Tom Select.

When testing before a push, can you run some docker tests with WCAG turned on to make sure the base select does not violate WCAG? There might be new violations in some specific use cases, but the most important to check before a first merge is that we don’t flood the report with violation and fail too many test suites at once.

Thank you again!
Lucas C.

[mleduc]

tom select seems like a good choice overall.

@mflorea we’ll need to plan a call at some point to define a good API for an equivalent UI component in the Abstract Design System. I think this is a good step to avoid having to redo this kind of breaking migration again in the future.

@mflorea

It doesn’t provide a Bootstrap 3 CSS but it provides CSS for Bootstrap 4 and 5, so we’ll have to tweak a bit the CSS to be consistent with the rest of our form controls (but it generally looks good out of the box).

@mflorea

But the HTML structure is slightly different and the CSS classes have changed (ts-* vs. selectize-*). This means I had to update our CSS, the test page objects and all the rest of the code that was using selectize-* CSS classes.

Do those two CSS breakages have significant consequences for contrib extensions using Selectize?

[mflorea]

@mleduc

@mflorea we’ll need to plan a call at some point to define a good API for an equivalent UI component in the Abstract Design System. I think this is a good step to avoid having to redo this kind of breaking migration again in the future.

Definitely. The way we used and exposed Selectize is very messy… Replacing it with Tom Select is a short / medium term solution to allow us to upgrade jQuery. Long term we need to hide the underlying implementation and expose our own API.

@mleduc

Do those two CSS breakages have significant consequences for contrib extensions using Selectize?

They can. I checked quickly the xwiki-contrib matches for “selectize” and I noticed 3 possible failures:

• some extensions, like book-versions/application-book-versions-ui/src/main/resources/BookVersions/Code/BookOverview.xml at e0e2615c65e157cff306150cef1b29e191378d2a · xwiki-contrib/book-versions · GitHub , load the Selectize CSS. They will have to load the Tom Select CSS instead.

  #set ($discard = $xwiki.linkx.use(
    $services.webjars.url('selectize.js', 'css/selectize.bootstrap3.css'),
    {'type': 'text/css', 'rel': 'stylesheet'}
  ))
  

  versus:

  #set ($discard = $xwiki.linkx.use(
    $services.webjars.url('org.webjars.npm:tom-select', 'dist/css/tom-select.bootstrap4.min.css'),
    {'type': 'text/css', 'rel': 'stylesheet'}
  ))
  

• some extensions, like application-page-relations/application-relations-ui/src/main/resources/XWiki/Relations/Code/RelationListMacro.xml at 5f7af5c123ba3b34b0ec76848ad8433c6cb26df9 · xwiki-contrib/application-page-relations · GitHub , are referencing Selectize CSS classes. They will have to update the code to reference Tom Select CSS classes. Note that using xwiki-selectize-* is fine, since those are controlled by us.

  .selectize-dropdown {
    max-width: 40em;
  }
  

  versus:

  .ts-dropdown {
    max-width: 40em;
  }
  

• some extensions, like ai-llm/application-ai-llm-models/application-ai-llm-models-ui/src/main/resources/AI/Code/Javascript.xml at 1c12fb94d1812cf26e9be99609ac42ba2943bf70 · xwiki-contrib/ai-llm · GitHub , require the xwiki-selectize module but call:

  const selectedPrompt = $('#features-menu').selectize();
  

  instead of:

  const selectedPrompt = $('#features-menu').xwikiSelectize();
  

And there might be JavaScript level API breakages that I haven’t noticed yet.

Thanks,
Marius

[mleduc]

Thanks for explicating the risks.
I guess I’m still +1 because I can’t think of a better option.

Some brainstorming to limit the breakages: can we tweak the build to serve a custom version of css/selectize.bootstrap3.css?
I check the code to see if customizing the classes was an option, but using ts- is a documented breaking change and is hardcoded everywhere…
For the rest, I don’t think we can do much.

[mflorea]

@mleduc

Some brainstorming to limit the breakages: can we tweak the build to serve a custom version of css/selectize.bootstrap3.css?

I was thinking to load the Tom Select CSS automatically, from JavaScript, to avoid hard-coding it in so many places. With this, the load of the Selectize CSS will fail (if the WebJar is uninstalled, which might not happen on upgrade) but the end user won’t notice.

For the last item, I can provide $.fn.selectize() as a shortcut for $.fn.xwikiSelectize(), when not set already, for backward compatibility.

For the changed CSS selectors I don’t have a solution. When used inside CSS, the breakage should be minimal I think. But if they were used in JavaScript, to locate some DOM elements, the breakage could be serious. Fortunately, I haven’t seen Selectize CSS selectors used in JavaScript code when scanning the “selectize” matches for xwiki-contrib.

Thanks,
Marius