Merge pull request #412 from creative-commoners/pulls/5/selectorfield

DOC Add SearchableDropdownField to 5.2.0 changelog
silverstripe · Dec 14, 2023 · f2858bd · f2858bd
2 parents 034594c + e1cc2c2
commit f2858bd
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 0 deletions.
diff --git a/en/02_Developer_Guides/03_Forms/Field_types/01_Common_Subclasses.md b/en/02_Developer_Guides/03_Forms/Field_types/01_Common_Subclasses.md
@@ -59,6 +59,8 @@ doesn't necessarily have any visible styling.
 - [TreeMultiselectField](api:SilverStripe\Forms\TreeMultiselectField): Represents many-many joins using a tree selector shown in a dropdown-like element.
 - [GridField](api:SilverStripe\Forms\GridField\GridField): Displays a [SS_List](api:SilverStripe\ORM\SS_List) in a tabular format. Versatile base class which can be configured to allow editing, sorting, etc.
 - [ListboxField](api:SilverStripe\Forms\ListboxField): Multi-line listbox field, through `<select multiple>`.
+- [SearchableDropdownField](api:SilverStripe\Forms\SearchableDropdownField): Dropdown field with optional type to search and optional AJAX lazy loading.
+- [SearchableMutliDropdownField](api:SilverStripe\Forms\SearchableMutliDropdownField): Multi-select field with optional type to search and optional AJAX lazy loading.
 
 ## Utility
 

diff --git a/en/04_Changelogs/5.2.0.md b/en/04_Changelogs/5.2.0.md
@@ -11,6 +11,7 @@ title: 5.2.0 (unreleased)
   - [ErrorPage allowed codes configuration](#errorpage-allowed-codes-configuration)
   - [Create random passwords for new users](#create-random-passwords-for-new-users)
   - [Buttons to select all files and deselect all files](#bulk-action-buttons)
+  - [New searchable dropdown fields](#searchable-dropdown-field)
   - [More nuanced permissions for `/dev/*` routes](#dev-route-permissions)
   - [New exception in React forms](#react-forms-exception)
   - [Other new features](#other-new-features)
@@ -146,6 +147,16 @@ The files section of the CMS now has buttons to select and deselect all files an
 
 ![select all functionality in the CMS](../_images/asset-admin-select-all.png)
 
+### New searchable dropdown fields {#searchable-dropdown-field}
+
+A pair of new dropdown form fields have been added which are particularly useful for dropdowns with a large number of options.
+
+[`SearchableDropdownField`](api:SilverStripe\Forms\SearchableDropdownField) is similar to [`DropdownField`](api:SilverStripe\Forms\DropdownField) which allows selecting a single option, and [`SearchableMultiDropdownField`](api:SilverStripe\Forms\SearchableMultiDropdownField) is similar to [`ListboxField`](api:SilverStripe\Forms\ListboxField) which allows selecting multiple options.
+
+Both of these fields include a `setIsLazyLoaded()` method which will load a limited number of options at a time using an AJAX request matching what a user has typed in. There are quite a few options to customise these, including optionally using `SearchContext` to power the lazy-loaded search functionality. We encourage you to look at the API documentation for these new classes to see what you can do with them.
+
+Note that these are both powered by react components, and are only intended to be used within the CMS. If you want to use them on the front-end of your project you will need to provide your own templates and JavaScript implementation for them.
+
 ### More nuanced permissions for `/dev/*` routes {#dev-route-permissions}
 
 Previously, all `/dev/*` routes registered with [`DevelopmentAdmin`](api:SilverStripe\Dev\DevelopmentAdmin) (for example `/dev/tasks/MyBuildTask`) could only be access by administrator users, and this couldn't be configured.