Skip to content

Select2

For dynamic selection fields, this project is using the jQuery-Plugin Select2 on the client side and DataTables on the server side.

Official documentation

In addition to the following documentation, the official documentation for the used packages provides plenty of material.

The Blade-Components overview unter http://localhost/widget provides an example as well.

Concepts

The jQuery-Plugin Select2 is preconfigures in such a way that it attaches to all selection fields with the class Select2. There are Blade-Components that generate suitable selection fields. The server requests from Select2 are sent to the same interface ast the DataTables.

Options

Select2-Optiions can be set via data-*-Attributes of the HTML-Elements. These can easily be set using the dataset-Property from the Blade-Components. The values are encoded to match automatically.

Source Code

For example, the options can bet set as follows.

<?php
class Controller extends \Illuminate\Routing\Controller
{
    // Used for demonstration purposes only, to render Template-Strings.
    use \Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
    public function index()
    {
        return (string) $this->blade(
            <<< 'blade'
                <x-base::select2 :dataset="['closeOnSelect' => false]"/>
            blade,
        );
    }
}
return (new Controller())->index();

Note

Due to the limitations of the parser of the blade components, it is not possible to use the quotation marks that also enclose the value within a value of an attribute with a PHP value. for example, it poses a problem to use double quotation marks within :dataset="...". This Problem can be solved by using the PHP function chr() with the ASCII-Value of the quotation mark (34): :dataset="chr(34)"

Output

The above PHP Source Code results in the following HTML-Output.

<select class="select2" data-close-on-select="false"></select>

Client- and server-side query

Select2 supports both client and server side data queries. The client-side query is active by default. in order to switch to the server-side query, the URL of the data source must be specified with the ajax.url option. Select2 has its own Server Interface Format, but the Blade-Component is preset with the appropriate adapters so that the existing interfaces of DataTables can simply be used. In addition to the usual Select2 options, the following are included:

  • ajax.disabled: The IDs of the disabled options (default: []).
  • ajax.getters.count: The path to the total number of results (default: "recordsFiltered").
  • ajax.getters.disabled: The path to the disabled field of a result (default: null).
  • ajax.getters.id: The path to the id field of a result (default: "id").
  • ajax.getters.more: The path to the id field of a result (default: null).
  • ajax.getters.results: The path to the results (default: "data").
  • ajax.getters.selected: The path to the selected field of a result (default: null).
  • ajax.getters.text: The path or paths to the text field of a result (default: "id"). If several paths are given, they are all resolved and the results are appended with spaces and then used.
  • ajax.selected: The IDs of the selected options (default: automatically determined from the session).

Note

For normal use, only the options ajax.url and ajax.getters.text are actually relevant.

Source Code

For example, server-side processing can be configured as follows.

<?php
class Controller extends \Illuminate\Routing\Controller
{
    // Used for demonstration purposes only, to render Template-Strings.
    use \Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
    public function index()
    {
        return (string) $this->blade(
            <<< 'blade'
                <x-base::select2 :dataset="['ajax' => [
                    'url' => '/tabulate',
                    'getters' => ['text' => 'name'],
                ]]"/>
            blade,
        );
    }
    public function tabulate()
    {
        return \Support\DataTables\Factory::make(collect([
            ['id' => 1, 'name' => 'one'],
            ['id' => 2, 'name' => 'two'],
            ['id' => 3, 'name' => 'three'],
        ]));
    }
}
return (new Controller())->index();

Output

The above PHP Source Code results in the following HTML-Output.

<select
    class="select2"
    data-ajax--url="/tabulate"
    data-ajax--getters--text="name"
></select>