Download the PHP package dakujem/selectoo without Composer
On this page you can find all versions of the php package dakujem/selectoo. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download dakujem/selectoo
More information about dakujem/selectoo
Files in dakujem/selectoo
Package selectoo
Short Description SelectBox & MultiSelectBox hybrid input with lazy & asynchronous options loading capabilities to be used with Select2, Selectize, Chosen and similar UI libraries.
License Unlicense
Informations about the package selectoo
Selectoo
[]()
SelectBox & MultiSelectBox hybrid input with lazy & asynchronous options loading capabilities to be used with Select2, Selectize, Chosen and similar UI libraries.
The aim of Selectoo is to provide a flexible tool for creating reusable select inputs.
Features
- can work in single-choice or multi-choice modes
- single-choice mode is roughly equal to
SelectBox
- multi-choice mode is roughly equal to
MultiSelectBox
- single-choice mode is roughly equal to
- on-demand (lazy) loading of options using a callback
- options can be loaded asynchronously using AJAX
- options are only loaded when really needed
- can be skinned with UI libraries or custom scripts (see below)
- dependent / cascading inputs
Usage / Use cases
Reusable inputs with specific setup:
- select2-skinned (or other library) input with special configuration options and other application logic
- autocomplete with ajax
- tagging
- custom ui script for altering the DOM upon selection
- cascading / dependent inputs
See included examples for more information.
Configuring Selectoo input
Create a (multi)select box with fixed options
or a (multi)select box with options loaded on demand (lazy loading).
An engine can optionally be attached
and configured.
The Select2Engine
is configured using magic options (or setOption
method).
The names of the magic methods (or option names) represent the Select2 configuration options.
Lazy options loading & AJAX
Lazy loading is used when the Selectoo instance is given "item callback" callable instead of an array of items. The callable is supposed to return a list of items.
The item callback also works as a validator for values.
It receives raw value as the first argument (and the input instance as the second).
The callback should return the array of possible values (these are the items) in form
exactly the same as the items set to SelectBox
or MultiSelectBox
inputs.
The raw value is then compared to the returned items and filtered.
This approach ensures the validity of the data.
It is important to set this callback in case you work with remote item loading (ajax/api loading of options).
See the example ajax presenter, complete with input factory and user repository examples.
Ajax configuration can be very simple:
Supported and intended UI libraries
Selectoo uses "script engines" to generate JavaScript UI scripts along with HTML input element.
Any script engine can be attached to the Selectoo
instance by calling $selectoo->setEngine($engine)
.
- select2/select2
- use the
Select2Engine
instances
- use the
- selectize/selectize.js
- to be implemented
- harvesthq/chosen
- to be implemented
Custom engines can easily be created implementing the ScriptEngineInterface
interface.
Factories
For best reusability I strongly encourage using factories for inputs with more logic, typically these involve fetching data from storage or external resources along with JS/UI configuration, handling events and value validation.
See simple examples:
- general selectoo factory
- example user select factory
- example AJAX API loaded input
Script management
The scripts generated by engines can be post-processed and/or collected by a management routine. This approach can be used to gather and place the scripts at the end of the page and to solve problems when writing scripts inside the page and loading jQuery at the end of the HTML file.
See script-management example for more information.
Dependent selections / cascading inputs
Example is being prepared.
What is needed, in general:
- UI script that manages on change events
- Select2 configuration that sends the value of master inputs in the URL of the AJAX request
- repository filtering based upon the values
- API endpoint that receives the master values and makes repository request, using values from the URL
- "item callback" that also makes repository request, using values from
Form
Note that when the item callback is called the values from the
Form
object can be used to check for master valuesBy "master values" above I mean the values of the inputs the Selectoo instance depends on
By following these steps, dependent Selectoo inputs can be created and values validated.
Examples
Please see the examples included in the repository to get a better understanding of when Selectoo comes handy.
Notable differences compared to Nette SelectBox & MultiSelectBox
- disabling a Selectoo input does not modify/reset its value, so it can be re-enabled without the loss of the information
- disabled input is handled differently - raw value is always loaded even when input (or items) is disabled. The disabled values are filtered when calling
getValue
method.
Requirements
Selectoo | PHP | Nette forms |
---|---|---|
version 2.0 |
7.1+ |
3.* |
version 1.0 |
7.0+ |
2.4.* |
You should also install Select2 version 4
to use the Select2Engine
,
see Select2 documentation.
You may install any other select input "skin" and implement your own engine for it within minutes.
Selectoo can also be used without such a "skin".