README

Provides Select2-powered dropdown and Ajax fields for SilverStripe v4. Intended to be used with SilverWare, however this module can also be installed into a regular SilverStripe v4 project.

Requirements
Installation
Configuration
Usage
Issues
Contribution
Attribution
Maintainers
License

Requirements

SilverStripe Framework v4

Installation

Installation is via Composer:

$ composer require silverware/select2

Configuration

As with all SilverStripe modules, configuration is via YAML. Extensions to LeftAndMain are applied via config.yml.

Usage

Select2Field

The Select2Field class is used exactly the same way as a regular old DropdownField:

use SilverWare\Select2\Forms\Select2Field;

$field = Select2Field::create(
  'MySelect2Field',
  'Select2 Field',
  [
    1 => 'An',
    2 => 'Array',
    3 => 'of',
    4 => 'Options'
  ]
);

Select2 Configuration

You can define any of the Select2 configuration settings by using the setConfig() method:

$field->setConfig('maximum-input-length', 20);

Alternatively, you can set the defaults for all Select2Field instances in your app by using YAML config:

SilverWare\Select2\Forms\Select2Field:
  default_config:
    maximum-input-length: 20

NOTE: configuration setting names are defined using HTML attribute style, and not camel case, for example:

$field->setConfig('maximum-input-length', 20);  // this will work
$field->setConfig('maximumInputLength', 20);    // this will NOT work

Select2AjaxField

The Select2AjaxField is used to search a DataList based on a search term entered by the user. The results are retrieved from the server via Ajax and rendered as dropdown options. This is very handy for cases where the number of available options in a regular dropdown would be prodigious.

The field is created like any other field:

use SilverWare\Select2\Forms\Select2AjaxField;

$field = Select2AjaxField::create(
  'MySelect2AjaxField',
  'Select2 Ajax Field'
);

But we do not pass an array of options to choose from to the constructor. Instead, we configure the field to search a DataList on the server-side. Here are the default settings:

$field->setDataClass(SiteTree::class);  // by default, the field searches for SiteTree records

$field->setIDField('ID');       // the name of the field which identifies the record
$field->setTextField('Title');  // the name of the field to use for the option text

$field->setSearchFields([
  'Title'  // an array of fields to search based on the entered term
]);

$field->setSortBy([
  'Title' => 'ASC'  // an array which defines the sort order of the results
]);

$field->setLimit(256);  // the maximum number of records to return

As mentioned, these are the default settings, and the field will work out-of-the-box for SiteTree searches.

Exclusions

You can also optionally define a series of exclusion filters, which use the same format for the exclude method of DataList:

$field->setExclude([
  'Title:ExactMatch' => 'Hide This Title'
]);

Any records matching the defined exclusion filters will be excluded from the results.

Formatting

By default, the field will render a regular series of dropdown options based on the $ID and $Title of the matching records, however you can apply more advanced formatting for both results and the current selection. For example:

$field->setFormatResult('<span>Found: <em>$Title</em></span>');
$field->setFormatSelection('<span>Selected: <strong>$Title</strong></span>');

HTML will be rendered as a jQuery object, so be sure to wrap it in an enclosing element such as a <span>.

Ajax Configuration

Any of the Select2 Ajax settings can be defined using the setAjaxConfig() method:

$field->setAjaxConfig('cache', false);
$field->setAjaxConfig('delay', 500);

Alternatively, you can set the defaults for all Select2AjaxField instances in your app by using YAML config:

SilverWare\Select2\Forms\Select2AjaxField:
  default_ajax_config:
    cache: false
    delay: 500

NOTE: configuration setting names are defined using HTML attribute style, and not camel case, for example:

$field->setAjaxConfig('data-type', 'json');  // this will work
$field->setAjaxConfig('dataType', 'json');   // this will NOT work

Issues

Please use the GitHub issue tracker for bug reports and feature requests.

Contribution

Your contributions are gladly welcomed to help make this project better. Please see contributing for more information.

Attribution

Makes use of Select2 by Kevin Brown, Igor Vaynberg and others.

silverware / select2

Maintainers

Details