299

Product support

Get help in the plugin support forum.

Categories

This is a developer plugin to add Relation Dynamic Dropdown functionality to backend forms.

This plugin includes a Relation Dynamic Dropdown Form Widget that extends relation form widget and provides capabilities of dynamic search and selection of dropdown options for 'belongsTo' and 'hasOne' relations with new field type: relation-dynamic-dropdown, which could be used instead of relation field type.

Animated demo

Relation Dynamic Dropdown Form Widget

This is a developer plugin to add Relation Dynamic Dropdown functionality to backend forms.

This plugin includes a Relation Dynamic Dropdown Form Widget that extends relation form widget and provides capabilities of dynamic search and selection of dropdown options for 'belongsTo' and 'hasOne' relations with new field type: relation-dynamic-dropdown, which could be used instead of relation field type.

Advantages of this form widget

  • Helps manage relation dropdown fields with a lot of associated records.
  • Prevents loading of all records as select options in form HTML page, which is a huge performance advantage in case of thousands of records.
  • Provides dynamic search of records in dropdown with autocomplete functionality.
  • Uses pagination in autocomplete search results, next page is loaded automatically on scroll to the bottonm of search results.
  • Handles AJAX search requests automatically, all you have to do is switch filed type from 'relation' to 'relation-dynamic-dropdown'.

Demo

Demo

Getting Started

Download from the October Marketplace or clone the https://github.com/euknyaz/oc-relation-dynamic-dropdown-formwidget from github into your plugins folder.

Installing

Simply install the plugin from the market place or clone the repository as mentioned in the Getting Started section.

You can then access the FormWidget in your model's fields.yaml file by used 'relation-dynamic-dropdown' as the field type.

# fields.yaml
user:
    label: User
    span: auto
    type: relation-dynamic-dropdown
    nameFrom: email

Here is an example of advanced configuration:

# fields.yaml
user:
    label: User
    comment: 'dynamic search and autocomplete with lazy loading'
    span: auto
    type: relation-dynamic-dropdown
    select: CONCAT(first_name, ' ', last_name, ' - ', email)
    emptyOption: None # for nullable relations only
    limit: 10
    order: first_name # optional parameter
    scope: withAuthorRoles # optional parameter
    attributes:
        data-minimum-input-length: 2
        data-ajax--delay: 300

Note: You may use type: 'relation-dynamic-dropdown' for any relation fields defined as: 'belongsTo' or 'hasOne' in the model associated with form.

Option Description
nameFrom Field name to search and display in dropdown. Option inherited from Relation widget.
select Dynamically generated field with raw SQL capabilities like SQL functions. The most useful is function: CONCAT(field1, ' ', field2, ...).
emptyOption Label of ompty option to reset selection if your relation is nullable. Recommended: None.
order Field name to sort search results. Optional parameter
limit Count of records to be displayed in search results. Default: 20.
scope This is an optional parameter to search results for dropdown values based on scope filter defined in relation model.
attributes.data-minimum-input-length Count of records to load and display with dynamic dropdown. Default: 20.
attributes.data-ajax--delay Delay between consequtive search ajax requests in milliseconds. Default: 300.

How it works

Relation Dynamic Dropdown Form Widget extends Relation widget overrides functionality of "belongsTo" or "hasOne" relations, which displays "dropdown" form widget.

It sets "data-handler" attribute for select2 dropdown to "onRelationDropdownSearch" automactially, which turns select2 dropdown into search & autocomplete mode.

Embedded handler method "onRelationDropdownSearch" is used for AJAX requests for search & autocomplete functionality, this method pickups field configuration and renders data for you automcatically, by looking at field configuration parameters 'nameFrom' and 'select'.

Note: You can use HTML markup in your field rendering with configuration like "select: CONCAT('<b>', first_name, ' ', last_name, '</b> - ', email)", and it's going to work fine in Update Form and Relation Dropdown widget, but it's not going to render HTML properly in Preview Form becuase of it's current limitations.

Support

Feel free to use any of the following support channels (Please don't use Reviews to request for support.):

Built With

References

Versioning

I use use Github for versioning.

Authors

License

This project is licensed under the MIT License.

Acknowledgments

  • Thanks to the OctoberCMS community.
1.0.3

Fixed bug with relations as field in repeater widget and implemented support of emptyOption parameter

Apr 22, 2020

1.0.2

Fixed bug with display of multiple instances of widget of the same form

Apr 22, 2020

1.0.1

Fixed bug with display of selected item on form rendering

Apr 22, 2020

1.0.0

First version of Relation Dynamic Dropdown Form Widget.

Apr 19, 2020