Add support for InputGroups #906
Description
About
There has been some interest expressed in adding support for "prefix / suffix" functionality in backend forms. This issue will act as the design document for the proposed functionality and discussion hub for any comments on the feature.
Potential Use Cases
- Clarification: Providing additional visual / textual information to an input to make it more clear to the user what type of data is expected (i.e. calendar icon for dates, envelope for email address, units of measurement for number inputs, etc)
- Normalization: Enforcing a standard representation of data that can be expressed in multiple formats, (i.e. instead of asking for a URL and getting
https://example.com,example.com, orhttp://example.com, you can set it up so that the user-editable part of the input is always justexample.comand the functionality normalizes the value so that you always receivehttps://example.comwhen asking for the value of the field; same with social media user names, phone numbers, etc). - Compact Triggering of Extended Functionality: Providing a compact button to trigger additional functionality, i.e. a popup where additional information is provided, files are uploaded, records are selected, or a dropdown where the input is quantified (currency selector), etc.
Terminology
- InputGroup: The container that holds various UI elements that together act as a single user input field
- Input: The main input element where the user's input is provided and displayed
- Add-on: An additional UI element that acts as an interactive and / or visual part of the InputGroup, usually with a visual separation from the main Input element.
- Inline Add-on: An Add-on element that is styled to look as if it part of the Input element itself.
- Leading (or Prefix): Located before the Input element
- Trailing (or Suffix): Located after the Input element
- Icon: Visual Add-on that displays an icon that helps communicate what data is being managed by the InputGroup (ex. email, calendar, clock, etc)
- Text: Visual Add-on that displays plain-text that helps communicate what data is being managed by the InputGroup (ex. units of measurement)
- Button: Interactive Add-on that triggers some additional functionality (ex. a popup dialog) when pressed
- Dropdown: Interactive Add-on that allows users to select from a list of predefined values to prefix / suffix their provided data with (ex. Currency, Country for phone numbers, Unit of Measurement, etc)
Desired Functionality
Option 1: Add support for related properties to a preselected list of existing fields:
We would add new properties / options to number & text field types, potentially use the functionality to also improve the email field.
The properties would be the TO BE DEFINED
Option 2: New InputGroup FormWidget
Provide a new InputGroup FormWidget that would allow
- Define a
leading / prefixadd-on - Auto trimming of prefix / suffix on paste / change
- Whether or not to include the prefix / suffix in the stored value
Existing Examples in the wild:
- https://tailwind-elements.com/docs/standard/forms/input-group/
- https://flowbite.com/docs/forms/input-field/#input-group
- https://tailwindui.com/components/application-ui/forms/input-groups
- https://stackoverflow.com/questions/49796934/add-a-text-suffix-to-input-type-number
- Provide the current Form instance to partials #902 (comment)
- https://wintertricks.com/tricks/formwidget-to-wrap-another-formwidget-with-a-prefixsuffix-zone
Current Uses in Winter CMS
The following FormWidgets in Winter already use similar UI features. It is not necessarily important to design this functionality to replace the implementations of these FormWidgets, as we want to design something that can be used for the 80% use case with people continuing to use custom FormWidgets for the 20% use case that is significantly more complex (which covers the majority of the following examples).
ColorPicker
Leading Add-on w/ interactive state, live preview of the selected colour. Popup picker triggered by focus on input element.
DatePicker
Trailing Inline Icon on both input fields, indicates which input is for which part of the date / time data. Popup picker triggered by focus on input element.
FileUpload
Trailing Add-on Button Icon, used to trigger the native fileupload dialog.
IconPicker
Leading Add-on w/ interactive state, live preview of the selected icon. Popup picker triggered by focus on input element.
MediaFinder
Trailing Add-on Button Icon, used to trigger the native fileupload dialog
RecordFinder
Trailing Add-on Button Icon, used to trigger the popup picker.
Sensitive
Trailing Add-on Button Icon w/ interactive state, used to trigger toggling the visibility of the sensitive value.
