Поле и кнопка выбора из справочника

Поле выбора из справочника

Контрол Поле выбора из справочника (Controls/lookup:Input) позволяет выбирать значения из диалога или выпадающего блока автодополнения.

Рис. 1. Использование поля выбора из справочника в карточке задачи на online.sbis.ru.

Поле выбора из справочника состоит из:

  • поля ввода, при вводе в поле может появляться автодополнение, из которого можно производить выбор;
  • кнопки открытия диалога выбора.

Окно диалога выбора из справочника открывается по клику на кнопку-значок: или на метку, например, такую:

Метка может размещаться внутри или вне поля ввода.

Демонстрационный пример

Справочные материалы и ресурсы

Руководство разработчика по конфигурации контрола

Для работы с полем выбора из справочника рекомендуются к использованию следующие контролы:

  • Controls/lookup:Input — контрол поля ввода с кнопкой-значком для выбора из справочника,
  • Controls/lookup:Link — контрол, использующийся для отображения стандартной метки внутри или вне поля ввода.

Внедрение поля выбора в ваше прикладное решение состоит из следующих шагов:

  1. Создание окна выбора из справочника. Данный этап подробно описан в документе Контрол «Окно выбора из справочника». Для разработки поля выбора нас интересуют следующие разделы этого документа:
  2. Добавление контрола поля выбора. В контрол, в котором предполагается использовать поле выбора, нужно добавить Controls/lookup:Input.

Источник данных

Источник данных устанавливается с помощью опции source. В опцию передается объект, который реализует интерфейс ISource для доступа к данным.

Если в задаче необходимые данные уже есть, и надо их просто установить и отобразить в поле выбора (при этом дополнительный запрос на сервер делать не нужно), рекомендуется использовать источник данных Types/source:PrefetchProxy. PrefetchProxy — это источник, который на первое обращение к нему отдаст данные, которые ему передали в опцию data.

С помощью опции keyProperty определяется уникальный идентификатор (ключевое поле) элемента, с помощью displayProperty — название поля, значение которого отображается при выборе элемента из справочника.

В случае использования источника данных Types/source:SbisService следует обратить внимание:
для получения записей в поле выбора используется списочный метод.

  • WML
    <Controls.lookup:Input
       source="{{_source}}"
       keyProperty="id"
       displayProperty="description"/>
  • JavaScript
    define('Engine-demo/Lookup',
       [
          'UI/Base',
          'wml!Engine-demo/Lookup/Lookup',
          'Engine-demo/Selector/SelectorData',
          'Controls-demo/Input/Lookup/LookupData',
          'Types/source',
          'Controls-demo/Utils/MemorySourceFilter',
          ...
       ], function(Base, template, SelectorData, LookupData, source, memorySourceFilter) {
          'use strict';
        
          return Base.Control.extend({
             _template: template,
        
             _beforeMount: function() {
                this._source = new source.Memory({
                   data: SelectorData.companies,
                   keyProperty: 'id'
                });
             }
          });
       }
    );
  • описание данных источника
    return {
       companies: [
          {
             id: 'Наша компания',
             title: 'Наша компания',
             city: null,
             description: 'Управленческая структура',
             active: true
          },
          {
             id: 'Все юридические лица',
             title: 'Все юридические лица',
             city: null,
             description: null,
             active: true
          },
          ...
       ],
    }

Окно выбора из справочника

В опцию selectorTemplate передать:

Из демо-примера к полю выбора:

  • WML
    <Controls.lookup:Input
       source="{{_source}}"
       keyProperty="id"
       displayProperty="description"
       >
       <ws:selectorTemplate templateName="Controls-demo/Input/Lookup/FlatListSelector/FlatListSelector" />
    </Controls.lookup:Input>

Подсказка внутри поля выбора

Подсказка в поле выбора устанавливается с помощью опции placeholder.

В эту опцию можно передать обычный текст:

<Controls.lookup:Input
   source="{{_source}}"
   placeholder="Enter company name"
   />

чтобы получить поле выбора следующего вида:

В опцию можно добавить разметку.
Например, можно добавить метку выбора из справочника. Для отображения стандартной метки рекомендуется использовать Controls/lookup:Link. В примерах использован именно этот контрол:

<Controls.lookup:Input
   source="{{_source}}"
   name="lookupInsideLabel"
   >
   <ws:placeholder>
      Enter
      <Controls.lookup:Link 
         caption="company" 
         <!-- Клик на кнопку позовет метод, который откроет окно выбора из справочника. -->
         on:click="showSelectorInsideLabel()"/>
      name
   </ws:placeholder>
</Controls.lookup:Input>

получим поле выбора следующего вида:

Если требуется выбор из нескольких справочников, в placeholder можно добавить несколько меток. Например, для выбора из справочника компаний и справочника отделов можно добавить в поле две метки следующим образом:

<Controls.lookup:Input
   source="{{_source}}"
   name="directoriesLookup"
   >
   <ws:placeholder>
      Specify the
      <!-- Клик на кнопку "department" или "company" позовет метод, который откроет окно выбора из справочника. -->
      <Controls.lookup:Link caption="department" on:click="showSelector('Departments')"/>
      and
      <Controls.lookup:Link caption="company" on:click="showSelector()"/>
   </ws:placeholder>
</Controls.lookup:Input>

получим поле следующего вида:

Метка рядом с полем выбора

Метку можно вынести за пределы поля выбора:

  • над полем выбора:

    <div class="inputLookup__labelAbove">
       <Controls.lookup:Link 
          caption="From whom"
          <!-- Клик на кнопку позовет метод, который откроет окно выбора из справочника. -->
          on:click="showSelectorLabelAbove()"/> 
    </div>
    <Controls.lookup:Input
       name="lookupLabelAbove"
       placeholder="Enter company name"
       ...
       >
    </Controls.lookup:Input>

  • рядом с полем выбора:

    <Controls.lookup:Link 
       caption="From whom" 
       <!-- Клик на кнопку позовет метод, который откроет окно выбора из справочника. -->
       on:click="showSelectorLabelBeside()" 
       attr:class="inputLookup__labelBeside"/>
    <Controls.lookup:Input
       name="lookupLabelBeside"
       placeholder="Enter company name"
       ...
       >
    </Controls.lookup:Input>

Для решения прикладных задач может быть использована любая кнопка. Например, кнопка-значок:

Множественный выбор значений из справочника

Для возможности одновременного выбора нескольких записей нужно активировать режим множественного выбора.
Активируется режим с помощью опции multiSelect:

<Controls.lookup:Input
     source="{{_source}}"
     keyProperty="id"
     multiSelect="{{true}}"
     >
</Controls.lookup:Input>

С активацией режима для поля выбора необходимо установить множественный выбор для окна выбора из справочника.

Настройка отображения выбранных значений в поле выбора

C помощью опции multiLine, установленной в true, активируется режим отображения поля в несколько строк.

При активированном режиме поле заполняется выбранными значениями и, по мере заполнения, увеличивается по высоте. После последнего выбранного значения выводится область для ручного ввода с подсказкой; если в строке недостаточно места для отображения области, то она переносится на следующую строку.

В верхнем левом углу поля выбора выводится счетчик. По клику на счётчик открывается всплывающая подсказка с полным списком выбранных значений.

Рис. 2. Поле выбора из справочника с активированным режимом отображения в несколько строк.

Если количество выбранных значений больше установленного ограничения, то неуместившиеся значения скрываются под счётчик. Ограничение устанавливается опцией maxVisibleItems.

Шаблон отображения выбранных значений

Для отображения выбранных записей рекомендуется использовать стандартный шаблон Controls/lookup:ItemTemplate.

Шаблон конфигурируется с помощью опций:

  • size — размер записей; возможные значения: s, m, l;
  • style — стиль отображения; возможные значения: none, bold, accent, primary;
  • clickable — позволяет установить кликабельность выбранного значения.

Пример показан далее:

  • WML
    <Controls.lookup:Input
       source="{{_source}}"
       placeholder="Enter company name"
       searchParam="title"
       keyProperty="id"
       >
       <ws:itemTemplate>
          <ws:partial template="Controls/lookup:ItemTemplate" 
             style="{{_selectedKeyStyle}}"
             size="{{_selectedKeySize}}"
             displayProperty="title">
          </ws:partial>
      </ws:itemTemplate>
    </Controls.lookup:Input>

Автодополнение поля выбора

Значения можно выбирать через автодополнение. Окно автодополнения появляется, когда пользователь вводит символы в поле выбора. В опции suggestTemplate задают шаблон окна автодополнения. В этом шаблоне используют контейнер Controls/suggestPopup:ListContainer, в котором размещают контрол списка. Шаблон футера автодополнения задают в опции suggestFooterTemplate.

Когда автодополнение не находит релевантых значений, отображается шаблон, указанный в опции emptyTemplate.

Автодополнение можно показывать каждый раз, когда поле выбора получает фокус. Чтобы включить это поведение, установите опцию autoDropDown в значение true.

Из демо-примера к полю выбора:

  • конфигурация поля выбора:
    <Controls.lookup:Input
       source="{{_source}}"
       searchParam="title"
       keyProperty="id"
       readOnly="{{true}}"
       >
       <ws:suggestTemplate templateName="Controls-demo/Input/Lookup/Suggest/SuggestTemplate"/>
    </Controls.lookup:Input>
  • конфигурация шаблона блока автодополнения:
    <!-- Все необходимые настройки передаются в шаблон от поля выбора -->
    <Controls.suggestPopup:ListContainer>
       <Controls.list:View
          keyProperty="id"
          attr:class="demo-SuggestList">
          <ws:itemTemplate>
             <ws:partial template="Controls/list:ItemTemplate">
                <ws:contentTemplate>
                   {{itemTemplate.itemData.item.Name}}
                </ws:contentTemplate>
             </ws:partial>
          </ws:itemTemplate>
       </Controls.list:View>
    </Controls.suggestPopup:ListContainer>

Поиск в списке автодополнения

Для настройки поиска используем опции:

  • searchParam — название поля, по которому должен работать поиск; значение поиска будет вставлено в фильтр по этому параметру;
  • searchDelay — задержка (в мс) между тем, когда был введен символ, и началом поиска;
  • minSearchLength — минимальное количество символов, необходимое для начала поиска.

  • WML

<Controls.lookup:Input
   source="{{_source}}"
   searchParam="title"
   searchDelay="{{500}}"
   minSearchLength="{{5}}"
   />

Работа с одним ключом (опция selectedKey)

Адаптер Controls/source:SelectedKey позволяет контролу работать не с массивом selectedKeys, а с одним ключом selectedKey. Для корректной работы необходимо контрол обернуть в адаптер; значение selectedKey настраивается у адаптера.

Cобытие адаптера selectedKeyChanged позволяет обработать изменение выбранного ключа.

Пример конфигурации

<Controls.source:SelectedKey bind:selectedKey="_selectedKey">
   <Controls.lookup:Input
      ...
   />
</Controls.source:SelectedKey>
_beforeMount: function() {
   this._selectedKey = 25;
}

Комментарий в поле ввода

Когда в контроле нет выбранного значения, в поле ввода отображается подсказка, которая задаётся через опцию placeholder. Однако, после выбора значения, такая подсказка скрывается. Чтобы отображать подсказку рядом с выбранным значением, используют другую опцию — comment. Использование опции актуально только для режима единичного выбора значений из справочника. Подсказка comment сообщает пользователю, что поле доступно для ввода значения. Введенное пользователем значением можно получить из опции value.

Кнопка выбора из справочника

Кнопка выбора из справочника используется для быстрого выбора значений из связанного с ней справочника. Представляет из себя кнопку-ссылку, при нажатии на которую открывается окно выбора.

Для работы с кнопкой используется контрол Controls/lookup:Selector.

Рис. 3. Вид кнопки до выбора значений и с выбранными значениями.

Демонстрационный пример

См. демо.

Исходные файлы примера:

Справочные материалы и ресурсы

Руководство разработчика по конфигурации контрола

Конфигурирование

Конфигурирование контрола аналогично описанному выше конфигурированию поля выбора из справочника.

Основные отличия в конфигурировании кнопки:

  • наличие опции caption, которая отображает надпись на кнопке;
  • отсутствие опции multiLine, настраивающей режим отображения в одну или несколько строк — у кнопки нет однострочного режима отображения,
  • отсутствие опции value, которая используется в конфигурировании поля ввода.

Следует отметить также, что у кнопки выбора, в режиме множественного выбора, в конце списка выбранных значений отображаются кнопки +еще и Очистить. Они помогают быстро добавить новые значения к списку уже выбранных, а также полностью очистить список выбранных значений.