Select2 4.0

[kevin-brown]

The release announcement is available at https://select2.github.io/announcements-4.0.html
The documentation is available at https://select2.github.io/
You can get the latest code in a zip file from https://github.com/ivaynberg/select2/archive/select2-ng.zip

Select2 hasn't had any major releases for a few years, which has limited the
scope of the improvements that we have been able to make. Select2 4.0 aims to
be a total rewrite and reorganization of the code base.

This pull request is a work in progress. The checklist will be updated as things reach a state of completion, and new items will be added as we decide what features will be migrated.

Repository

• Add a new dist folder.
  • This will include two subfolders, js and css, that will contain
    compiled versions of Select2's CSS and JavaScript.
• Include copies of dependencies within the repository.
  • Copies of jQuery and any other dependencies will be included in the
    vendor folder.
• Switch to a task runner
  • Something like Grunt or Gulp, which are JavaScript-based.
  • It will allow for a system-independent updater to be created.
• Move all source files into a src folder
• Move to the Select2 organization on GitHub
  • Set up a migration repository for the documentation

Documentation

• Update documentation to Bootstrap 3
• Include documentation on the master branch
  • This will prevent confusion for users who do not realize it is on the
    gh-pages branch.
  • This will also include the documentation in releases, so users do not
    have to always access it online.
  • Documentation will be versioned alongside Select2.
• Split documentation across multiple pages
  • Integrations
  • Contributing
  • Initialization options
  • Examples
• Include an examples page that provides examples of the core options.
• Include an options page that outlines all of the options in detail.
• Create an announcement that briefly covers the important changes in 4.0.
• Create a changelog that references all milestones.

CSS

• Compiled stylesheets via SASS (SCSS syntax)
  • Allows for variables to be used for easy customization
• Split up the CSS into separate components
  • Multiple small files that can be compiled into one main stylesheet.
• Create mixins for commonly repeated styles
  • This will allow us to update prefixes for properties as they stop being
    supported by major browsers.

JavaScript

One of the goals of this refactoring is to bring Select2 back to its roots, so it will better match the native behaviour of a <select> box. This is being done through a series of core changes.

• No longer stop all events from leaving the Select2 container [https://github.com//issues/2345]
  • Modules will be created to stop events at certain levels.
• Support <select> for as the primary base element
  • Backwards compatibility with <input /> elements may still be
    maintained through additional modules.
• Full test suite
  • This will allow us to ensure that future changes do not break features.

Core Modules

Select2 currently provides over 40 different options that can be combined during initialization to create a select box. During this upgrade process, we cannot provide them all by default, but support will be added for the most critical ones. Backwards compatibility modules may be created for any options which are not as important, but are still widely used.

Container

The Select2 container displays the selected results.

• Custom templating
• Placeholders
  • Selected options can be cleared to show the placeholder
  • Decorator to hide the placeholder option
  • Custom placeholder id (used when checking) [https://github.com//issues/2353]
• Automatically close the element when other elements are clicked.
  • Allow a mask to be used to detect clicks.
  • Detect click events that bubble up to the root element.

Results

The Select2 dropdown should allow for the results to be displayed.

• Searching results
  • Results can be optionally filtered based on user input.
• Custom templating
  • Allow the template to be specified on initialization.
• Custom matcher
  • A custom matcher function can be created that will determine what results are visible in the dropdown.
  • The matcher can be defined during initialization that points to a custom method
  • A module that adds backwards compatibility with the old parameters will be created
• Custom sorting
  • A custom sorting function can be used to determine the order that results will be displayed
  • The sorting function can be defined during initialization
  • [~] A module will be created that adds backwards compatibility with the old parameters
• Diacritics support
• Pagination
  • Infinite scrolling
  • [~] Next / previous paging
• Document the AJAX response format
  • Expects a results key which is an array of objects
  • Pagination-related information goes under the pagination key
• Allow the dropdown to automatically position itself
  • Allow the dropdown to be attached to the body
  • Allow the dropdown to be attached to the parent element
    • Allow the parent element to be configurable.

Data sets

Select2 should support pulling the data from multiple sources, including a standard <select>, an array of data, and a remote data source.

• Standard data sets
  • A <select> element with <option> and <optgroup> child elements that can be controled, just like a standard select box.
• Array data sets
  • A <select> element that is controlled by an external array, instead of child <option> elements.
  • Automatically convert array data to <option> tags.
  • [~] If a function is used, convert the array results on demand.
  • Automatically convert strings to full objects.
• AJAX data sets.
  • A <select> element that is controlled by an external data source.
  • Searching can be delayed or debounced for a period of time.
• Options can be added on the fly (tagging)
  • Results can be created based on the entered search term.
  • Should be able to wrap any data set that implements the required interface.
  • Position of the new tag can be customized.
  • Result will be automatically created when selected.
  • Any values defined when initializing tagging should be immediately added to the possible data.

Translations

Currently, Select2 supports many languages through translation files included within the repository. This includes over 40 languages that have been contributed by over 70 different contributors.

• Allow language fallback chains to be created
• Create a base language file for English
  • No results found
  • Loading results
  • Error loading results
  • Enter more characters
  • Enter less characters
  • Maximum number of results selected
• Migrate the existing translations to the new format
• Allow for the locale to be set on initialization

Other

• [~] Allow updating options on the fly
• Allow setting options through data-* attributes

Backwards compatibility

Each of these options will be included in the core options. In cases where the options are changed during the migration, backwards compatibility modules will be created that try as best as possible to maintain backwards compatibility.

• Maximum selections
  • Restrict the number of selected results to a specific number.
• Minimum search length
  • Do not start searching until a certain number of characters have been entered.
• Maximum search length
  • Do not allow searches over a specific number of characters to be made.
• Minimum results for search
  • Do not display the search box when opening the dropdown unless a specific number of results are visible
• Tokenization
  • Allow tags to be created on the fly, separated by a specific character
  • Allow the token characters to be specified during initialization
  • Allow the entered tags to be transformed during tokenization
• [~] Next search term
  • Allow the search box to be pre-filled when opening the dropdown or after a selection is made
• Custom data set (old query function)

Miscellaneous

• Full WAI-ARIA support [https://github.com//issues/2499]
  • Select2 should be detected as a combobox, like a standard <select>
  • The results should be detected as a tree
  • Migrate title attributes over from original <select>
    • <option> tags
    • <select> tag
• [~] Transparent support for mobile devices (A decision was made to maintain full mobile support.)

[kevin-brown]

The first beta public release has been made.

https://github.com/select2/select2/releases/tag/4.0.0-beta.1

[colemanw]

Congrats on the release and thanks for all your hard work @kevin-brown !