# Select2 1.0.1+

# Базовое использование

<xf:macro name="tc_clib_select2_macros::select2_includes" />

<div class="block">
    <div class="block-container">
        <div class="block-body">
            <xf:selectrow data-xf-init="tc-s2-select" label="OS" placeholder="Choose…">
                <xf:option></xf:option>
                <xf:optgroup label="Desktop">
                    <xf:option value="linux">Linux</xf:option>
                    <xf:option value="windows">Windows</xf:option>
                    <xf:option value="osx">OS X</xf:option>
                </xf:optgroup>
                <xf:optgroup label="Mobile">
                    <xf:option value="android">Android</xf:option>
                    <xf:option value="ios">IOS</xf:option>
                    <xf:option value="blackberry">BlackBerry</xf:option>
                </xf:optgroup>
                <xf:option value="other">Other</xf:option>
            </xf:selectrow>
        </div>
    </div>
</div>

# TeslaCloud.S2Select (tc-s2-select)

# Параметры

Параметр	Значение по умолчанию	Описание	Настройка Select2
allowClear*	false	Если `true`, к полю выбора будет добавлена кнопка очистки.	allowClear
closeOnSelect*	true	Если `true`, выпадающий список будет закрыт после выбора.	closeOnSelect
dropdownAutoWidth	false		dropdownAutoWidth
dropdownCssClass		Дополнительные классы CSS для выпадающего списка. `:all:` добавит все классы, присутствующие в исходном элементе `<select>`.	dropdownCssClass
dropdownParent*	`$(document.body)`	Селектор для настройки положения выпадающего меню.	dropdownParent
maxLength*	0	Максимальное количество символов для поискового запроса. `maxLength` < 1 — без ограничений.	maximumInputLength
maxSelection	0	Максимальное количество опций, которые могут быть выбраны. `maxSelection` < 1 — без ограничений.	maximumSelectionLength
minLength*	0	Минимальное количество символов, необходимое для начала поиска.	minimumInputLength
minimumResultsForSearch*	0	Минимальное количество опций, необходимое для отображения окна поиска. `minimumResultsForSearch` < 0 — отключить поиск.	minimumResultsForSearch
selectionCssClass		Дополнительные классы CSS для контейнера выбора. `:all:` добавит все классы, присутствующие в исходном элементе `<select>`.	selectionCssClass
selectOnClose*	false	Если `true`, после закрытия выпадающего списка будет выбрана опция, выделенная перед закрытием.	selectOnClose
tags*	false	Если `true`, будет разрешено указание пользовательских значений.	tags
theme*	tc-clib_s2select		theme
tokens	`[',']`	Список символов, которые следует использовать в качестве разделителей токенов.	tokenSeparators
width*	100%	Настройка ширины контейнера.	width
scrollAfterSelect*	false		scrollAfterSelect
searchUrl		URL для поисковых запросов.
data*	null	Массив объектов опций.	data
resultTemplate**	`{{{styledText}}}`	Шаблон для отображения опции в выпадающем меню.
resultTemplateIconic**	`{{{iconHtml}}} {{{styledText}}}`	Шаблон для отображения варианта выбора с иконкой в выпадающем меню.
selectionTemplate***	`{{{text}}}`	Шаблон для отображения выбранной опции.
selectionTemplateIconic***	`{{{iconHtml}}} {{{text}}}`	Шаблон для отображения выбранной опции с иконкой.

* Подробности в документации Select2.
** См. Dropdown — Templating и Шаблонизация.
*** См. Selections — Templating и Шаблонизация.

# Получение данных через AJAX

Кроме генерации списка опций из HTML, существует возможность загрузки данных через AJAX.
Для включения загрузки через AJAX необходимо задать URL для поисковых запросов в параметре searchUrl.

При изменении значения в поле поиска на указанный URL выполнится GET запрос со следующими параметрами:

Параметр	Описание
term	Текущий поисковый запрос в поле поиска.
q	Содержит то же, что и `term`.
_type	Тип запроса. Если выполняется запрос к первой странице — `query`, в противном случае — `query_append`.
page	Номер запрашиваемой страницы. Параметр присутствует только в запросах с пагинацией.

В ответ сервер должен вернуть ответ со следующим содержимым:

Ключ	Описание
results*	Массив с результатами поиска. См. ниже.
pagination	Пагинация. Единственный параметр — `more`, если `true`, при прокрутке до конца списка будет выполнен запрос к следующей странице.

Результаты поиска без группировки:

Ключ	Описание
id*	ID результата, который будет использоваться в качестве значения `value` опции. Любое значение, отличное от нуля.
text*	Текст опции.
selected	Если `true`, опция будет выбрана по умолчанию.
disabled	Если `true`, опция будет недоступна для выбора.
iconHtml	HTML-код для отображаемой иконки.
q	Текущий поисковый запрос. Используется для выделения совпадения.

Результаты поиска с группировкой:

Ключ	Описание
text*	Название группы.
children*	Массив с результатами поиска. То же, что и без группировки.

* Обязательно

# Пример поиска пользователей

<xf:macro name="tc_clib_select2_macros::select2_includes" />

<div class="block">
    <div class="block-container">
        <div class="block-body">
            <xf:selectrow data-xf-init="tc-s2-select"
                          label="Username" placeholder="Enter username…"
                          data-min-length="2" data-search-url="{{ link('members/find') }}" />
        </div>
    </div>
</div>

# Пример поиска иконок Font Awesome

<xf:macro name="tc_clib_select2_macros::select2_includes" />

<div class="block">
    <div class="block-container">
        <div class="block-body">
            <xf:selectrow data-xf-init="tc-s2-select" multiple="true"
                          label="Icon" placeholder="Find icon…"
                          data-min-length="2" data-search-url="{{ link('demo/find-fa-icon') }}" />
        </div>
    </div>
</div>

Код контроллера:

<?php

namespace Demo\Pub\Controller;

use XF;
use XF\Mvc\Reply\View;
use XF\Pub\Controller\AbstractController;

class Demo extends AbstractController
{
    /**
     * @return View
     */
    public function actionFindFaIcon()
    {
        $results = [];

        $query = $this->filter('q', 'str');
        if ($query)
        {
           foreach (XF::app()->data('XF:FontAwesome')->getIconMetadata() as $icon => $data)
           {
              if (
                 stripos($icon, $query) === 0
                 || stripos($data['label'], $query) === 0
              )
              {
                 $results[] = [
                    'id'   => $icon,
                    'text' => $data['label'],
                    'q'    => $query
                 ];
              }
           }
        }

        $reply = $this->view();
        $reply->setJsonParams([
           'results' => $results
        ]);

        return $reply;
    }
}

# Шаблонизация

Select2 позволяет изменить внешний вид выбранных опций и их списка в выпадающем меню. Для этого в TeslaCloud.S2Select возможно задать шаблоны, компилируемые библиотекой mustache.js.
Шаблоны задаются параметрами selectionTemplate и resultTemplate для выбранных опций и их списка в выпадающем меню соответственно. Шаблоны опций с иконками передаются параметрами с постфиксом Iconic (resultTemplateIconic и selectionTemplateIconic).

В шаблонах доступны следующие переменные:

Переменная	Описание
id	ID результата, который будет использоваться в качестве значения опции. Любое значение, отличное от нуля.
text	Текст опции без форматирования (в том виде, в каком он был в теле опции или при поиске через AJAX).
styledText	Отформатированный текст опции. При поиске через AJAX, совпадение с поисковым запросом будет выделено через `<strong>`.
selected	Если `true`, опция будет выбрана по умолчанию.
disabled	Если `true`, опция будет недоступна для выбора.
iconHtml	HTML-код для отображаемой иконки. Код иконки может быть задан из HTML с помощью атрибута `data-icon-html` в `<option>`.
q	Текущий поисковый запрос. Используется для выделения совпадения.

При поиске через AJAX могут присутствовать и другие переменные, переданные в ответе сервера.

# Пример отображения иконок в списке, сгенерированном из HTML

<xf:macro name="tc_clib_select2_macros::select2_includes" />

<div class="block">
    <div class="block-container">
        <div class="block-body">
            <xf:selectrow data-xf-init="tc-s2-select" label="OS" placeholder="Choose…">
                <xf:option></xf:option>
                <xf:optgroup label="Desktop">
                    <xf:option value="linux" data-icon-html="<i class='fab fa-linux fa-fw'></i>">Linux</xf:option>
                    <xf:option value="windows" data-icon-html="<i class='fab fa-windows fa-fw'></i>">Windows</xf:option>
                    <xf:option value="osx" data-icon-html="<i class='fab fa-apple fa-fw'></i>">OS X</xf:option>
                </xf:optgroup>
                <xf:optgroup label="Mobile">
                    <xf:option value="android" data-icon-html="<i class='fab fa-android fa-fw'></i>">Android</xf:option>
                    <xf:option value="ios" data-icon-html="<i class='fab fa-apple fa-fw'></i>">IOS</xf:option>
                    <xf:option value="blackberry" data-icon-html="<i class='fab fa-blackberry fa-fw'></i>">BlackBerry</xf:option>
                </xf:optgroup>
                <xf:option value="other">Other</xf:option>
            </xf:selectrow>
        </div>
    </div>
</div>

# Пример отображения иконок в списке при поиске через AJAX

Шаблон идентичен шаблону из данного примера. В коде контроллера к результатам поиска добавляется иконка:

                 $results[] = [
                    'id'   => $icon,
                    'text' => $data['label'],
+                   'iconHtml' => XF::app()->templater()->fontAwesome(
+                       ($data['is_brand'] ? 'fab ' : '') . 'fa-' . $icon
+                   ),
                    'q'    => $query
                 ];