Введение#

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

Свойства#

Наименование	Тип	Описание
bind	Строка	свойство, к которому привязывается элемент управления
bindingMode	Строка	режим привязки. Доступные значения: object, primitive, multiple. По умолчанию значение object
caption	Строка	заголовок
captionTextAlign	Строка	выравнивание текста заголовка элемента управления. По умолчанию значение left. Разрешенные значения: left, right
captionWidth	Число	ширина заголовка элемента управления (для Bootstrap-верстки)
codeBoxWidth	Число	ширина поля с кодом. По умолчанию значение 50
dataSource	Массив	источник данных Lookup
displayMember	Строка	имя свойства, являющегося наименованием объекта. По умолчанию значение Name
displayMemberColumnText	Строка	заголовок колонки с наименованием
displayMemberColumnWidth	Строка	ширина колонки с наименованием. Если не задано, то вычисляется автоматически
editorWidth	Число	ширина элемента управления (для Bootstrap-верстки)
enabled	Bool	доступность элемента управления для редактирования. По умолчанию значение true
filterCondition	Строка	тип фильтрации (доступные значения: contains, starts_with, equal). По умолчанию значение contains
hint	Строка	всплывающая подсказка, которая появляется при наведении на элемент управления
id	Строка	nan
placeholder	Строка	вспомогательный текст в поле displayMember элемента управления
popupWindowType	Строка	тип окна выпадающего списка. Доступные значения: simple, tree (с простым и древовидным гридом)
readOnly	Bool	режим "только для чтения". По умолчанию значение false
rowsCount	Число	количество строк, отображаемое в выпадающем списке. По умолчанию значение 9
showDisplayMember	Bool	отображение поля с наименованием. По умолчанию значение true
showValueMember	Bool	отображение поля с кодом. По умолчанию значение true
sortBy	Строка	поле сортировки в выпадающем списке по умолчанию
sortOrder	Строка	порядок сортировки. По умолчанию значение asc
tags	Строка	позволяет объединять элементы управления в группы, возвращает массив имен
value	Объект	текущее значение
valueKey	Строка	значение свойства выбранного объекта, которое указано в качестве свойства valueMember
valueMember	Строка	имя свойства, являющегося кодом объекта. По умолчанию значение VCode
valueMemberColumnText	Строка	заголовок колонки с кодом
valueMemberColumnWidth	Bool	ширина колонки с кодом. Если не задано, то вычисляется автоматически
valueMemberPlaceholder	Строка	вспомогательный текст в поле valueMember элемента управления
visible	Bool	видимость элемента управления. По умолчанию значение true
width	Число	ширина элемента управления. По умолчанию значение 100%

Методы#

Наименование	Описание
getDataSourceParameters	возвращает текущие применённые параметры загрузки источника данных
setDataSourceParameters	устанавливает объект в качестве словаря параметров загрузки источника данных. После установки параметров фокусировка вызовет обновление источника данных с учетом заданных параметров
resetLoadedData	сбрасывает кэш загруженных данных выпадающего списка и обозревателя аналитик (для постраничного лукапа)
setColumnsVisibility	устанавливает видимость для дополнительных колонок в выпадающем списке
getVisibleColumns	возвращает список видимых колонок в выпадающем списке
getHiddenColumns	возвращает список скрытых колонок в выпадающем списке

Детальное описание#

setColumnsVisibility#

Принимает массив объектов:

dataField - dataField колонки
value - видимость колонки (значение true или false)

Пример:

1	`this.controls.Lookup1.setColumnsVisibility([{ dataField: 'c1', value: false }])`

Не работает для колонок valueMember и displayMember (для них есть свойство showValueMember и showDisplayMember).

setDataSourceParameters#

Пример:

this.controls.Lookup1.setDataSourceParameters({
  parameter1: value1,
  parameter2: value2
});

События#

Наименование	Описание
valueChanged (onchage)	возникает при смене значения

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

Основным свойством элемента управления Lookup является его источник данных - dataSource. В качестве источников данных могут выступать модели и запросы.

<Group caption="Источник данных">
  <Lookup id="lu1" caption="На модели" rowsCount="5" valueMember="VCode" displayMember="Name" dataSource="./client.model.json"/>
  <Lookup id="lu2" caption="На запросе" rowsCount="5" valueMember="VCode" displayMember="Name" dataSource="../lookups/lookupDataSource.query.json"/>
  <Lookup id="lu3" caption="На DataAdapter" rowsCount="5" valueMember="userName" displayMember="firstName" dataSource="./systemUsers"/>
</Group>

Для использования нужного источника данных в элементе управления необходимо задать в свойстве dataSoure путь к нему относительно текущей формы.

Загрузка указанного источника данных будет выполнена однократно при первом обращении к элементу управления (точнее, при первой фокусировке на нём).

Работа с источником данных#

Зачастую запросы в системе реализуются с целью выполнения расчетов на основе их входных параметров. Подобные запросы можно использовать в качестве источника данных для Lookup. Для таких ситуаций у элемента управления Loookup реализованы методы для получения и установки параметров загрузки источника данных: getDataSourceParameters и setDataSourceParameters.

<Group caption="Работа с источником данных">
  <Lookup id="lookupOnQueryWithParameters" caption="на запросе" width="100%" editorWidth="2" captionWidth="1" valueMemberColumnText="Код" valueMember="VCode" displayMember="Наименование" displayMemberColumnText="Наименование" dataSource="./Contractor.query.json"/>
  <TextBox id="queryParameter" width="100%" editorWidth="1" captionWidth="1" caption="VCode >="/>
  <Button width="100%" editorWidth="1" captionWidth="0" value="установить" clicked="setQueryParameters"/>
</Group>

Описание запроса, который используется в данном примере в качестве источника данных:

{
  "rights": {
    "read": [
      "super"
    ]
  },
  "parameters": {
    "code": "bigint"
  },
  "select": {
    "text": "./Contractor.sql",
    "parameters": [
      "code"
    ]
  }
}

Запрос подразумевает использование параметра code. Для его ввода используются элементы управления TextBox и Button.

setQueryParameters() {
  const lookup = this.controls.lookupOnQueryWithParameters
  onst code = this.controls.queryParameter.value
  lookup.setDataSourceParameters({ code })
}

Установка параметра осуществляется в обработчике нажатия кнопки с помощью метода setDataSourceParameters, используя значение в текстовом поле с идентификатором queryParameter.

Выполнение метода setDataSourceParameters вызывает загрузку источника данных элемента управления (что можно использовать при необходимости его обновить).

Режимы привязки#

Режим привязки Lookup отвечает за то, в каком виде формируются и считываются значения в контроле. В примере представлены варианты настройки на режимы множественного выбора и примитивных типов. По-умолчанию используется режим привязки на объект.

Свойство bindingMode влияет на то, как будут загружаться, выбираться, сохраняться и отображаться значения при работе с данными формы. Например, в режиме примитивных типов (значение - primitive) контрол требует добавление источника данных в коллекцию кэшей данных формы. При использовании привязки к данным формы (используя свойство bind) в привязанном поле будет храниться примитивное значение.

В режиме множественного выбора (значение - multiple) у элемента управления отключается работа с данными формы и сохранение выбранных пользователем значений необходимо контролировать отдельно. В таком режиме в значение элемента управления записывается массив, содержащий выбранные записи.

<Group caption="Режимы">
  <Lookup id="lumultiple7" caption="Множественный выбор" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" bindingMode="multiple"/>
  <Lookup id="luprimitive8" caption="Примитив" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" captionWidth="1" dataSource="./city.model.json" bindingMode="primitive"/>
</Group>

Постраничность#

Пример:

<Group caption="Постраничность">
  <PageableLookup id="lookup567" caption="Запрос (постраничный)" displayMember="Name" valueMember="VCode" dataSource="../lookups/pageable.query.json" rowsCount="5" topCount="5"/>
  <PageableLookup caption="Модель (постраничный)" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" rowsCount="5" topCount="1">
    <Column datafield="Email" width="200" hint="Колонка 1">
      <TextBox/>
    </Column>
    <Column datafield="Email2" hint="Колонка 2">
      <TextBox/>
    </Column>
    <Column datafield="Email3" hint="Колонка 3">
      <TextBox/>
    </Column>
  </PageableLookup>
  
  <PageableLookup id="lu1" caption="Pageable2 filter:starts_with" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" filterCondition="starts_with" topCount="5" rowsCount="5"/>
  <PageableLookup id="lupageable3" caption="pageable multiple" editorWidth="2" captionWidth="1" width="100%" dataSource="./client.model.json" valueMember="VCode" displayMember="Name" bindingMode="multiple" rowsCount="5" topCount="2">
    <Column datafield="Email" width="10%" text="Email">
      <TextBox/>
    </Column>
    <Column datafield="textt" text="testtest2" width="200">
      <TextBox/>
    </Column>
  </PageableLookup>
</Group>

Данный пример показывает несколько вариантов настройки специализированного вида элемента управления Lookup - PageableLookup. PageableLookup используется для загрузки большого количества данных небольшими порциями ("страницами"). Для этого у элемента управления реализованы свойство topCount, которое определяет количество записей на страницу. topCount рекомендуется использовать вместе со свойством rowsCount - количеством строк, отображаемых в контроле.

Древовидная структура данных#

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

<Group caption="Древовидный" editorWidth="6">
  <Lookup id="lutree6" caption="Стандарт" sortBy="VCode" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" dataSource="../lookups/treeForLookup.query.json" captionWidth="2" editorWidth="3" codeBoxWidth="100" parentKeyProperty="PCode" keyProperty="VCode" popupWindowType="tree"/>
  <Break/>
  <Lookup id="lutree7" caption="Обработка вывода" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" dataSource="../lookups/treeForLookup.query.json" codeBoxWidth="90" editorWidth="3" captionWidth="2" parentKeyProperty="PCode" keyProperty="VCode" popupWindowType="tree" labelRenderer="labelRenderer"/>
  <Break/>
  <Lookup id="lutree8" caption="На примитивах" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" codeBoxWidth="90" editorWidth="3" captionWidth="2" dataSource="./treeAdapter.js" parentKeyProperty="PCode" keyProperty="VCode" popupWindowType="tree" labelRenderer="labelRenderer" bindingMode="primitive"/>
</Group>

Для включения древовидного режима отображения данных обязательно необходимо использовать свойство popupWindowType в значении tree. Далее необходимо указать какие свойства объектов коллекции использовать в качестве ключевого поля (keyProperty) и поля, хранящего ключ родительской записи (parentKeyProperty).

Для данного режима реализован также специальный метод labelRenderer, который позволяет обрабатывать и формировать отображаемые в элементе управления значения полей, используемых в качестве информационных (displayMember):

labelRenderer(e) {
  let parentNode = e.getParent()
  if (parentNode) {
    return `${parentNode.data.Name} > ${e.data.Name}`
  } else {
    return e.data.Name
  }
}

В древовидном режиме отображения данных элемент управления поддерживает также работу в режиме привязки на примитивных значениях (в примере: элемент управления с id lutree8). Для такого режима также, как и при обычном режиме отображения данных, требуется использовать кэши данных. В данном случае используется адаптер:

import { DataAdapter } from 'ecosoft-lexema8'
import $ from 'jquery'
export default class TreeAdapter extends DataAdapter {
  load() {
    return $.Deferred().resolve([
      { VCode: 'Goal', Name: 'Ворота', PCode: null },
      { VCode: 'Pole', Name: 'Столб', PCode: 'Goal' },
      { VCode: 'Field', Name: 'Поле', PCode: null }
    ])
  }
}

Фильтрация данных#

Lookup поддерживает возможность фильтрации коллекции отображаемых записей на стороне клиента. Для её использования необходимо определить метод формы, в котором будут описаны условия фильтрации, и использовать его в свойстве filter элемента управления:

<Group caption="Фильтры">
  <Lookup id="lu373" caption="обычный" rowsCount="5" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" filter="customFilter"/>
  <Lookup id="lu7954" caption="Примитив" dataSource="./city.model.json" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" captionWidth="1" bindingMode="primitive" filter="customFilter"/>
  <Lookup id="lutreeFilter6" caption="tree" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" dataSource="../lookups/treeForLookup.query.json" codeBoxWidth="100" parentKeyProperty="PCode" keyProperty="VCode" popupWindowType="tree" filter="treeCustomFilter"/>
  <Lookup id="lumultiple2" caption="Множественный выбор" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" bindingMode="multiple" filter="customFilter"/>
  <CheckBox id="even" caption="Чётные" value="true"/>
  <Lookup id="lu3732" caption="Чёт / нечёт" rowsCount="5" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" filter="isEvenFilter"/>
</Group>

Методы фильтрации могут иметь разнообразную логику. Но стоит помнить о производительности и том, что метод будет вызываться для каждой записи в коллекции данных элемента управления. Примеры методов фильтрации:

treeCustomFilter(s, e) {
  e.item.getChildren()
  if (e.item.data.VCode % 2 === 0) {
    return true
  }
}
isEvenFilter(s, e) {
  return Number(!this.controls.even.value) === (e.item.VCode % 2)
}
customFilter(s, e) {
  if (e.item.VCode % 2 === 0) {
    return true
  }
}

Сортировка данных#

1
2
3

<Group caption="Сортировка">
  <Lookup id="lu" caption="Lookup sortByName" rowsCount="5" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" sortBy="Name" sortOrder="desc"/>
</Group>

Для установки сортировки в элементе управления по умолчанию можно использовать свойства sortBy и sortOrder. В первом указывается нужное поле источника данных, во втором - порядок сортировки (asc или desc).

Проверка выбранного значения#

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

<Group caption="Валидация">
  <Lookup id="luValid" caption="обычный" rowsCount="5" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" validator="lookupValidator"/>
  <Lookup id="lutreeValid" caption="Древо" rowsCount="5" valueMemberColumnText="код" displayMemberColumnText="имя" valueMember="VCode" displayMember="Name" dataSource="../lookups/treeForLookup.query.json" codeBoxWidth="100" parentKeyProperty="PCode" keyProperty="VCode" popupWindowType="tree" validator="lookupValidator"/>
</Group>

Метод, используемый для проверки значения:

1
2
3

lookupValidator(value) {
  return value.Name === 'officer'
}

Если выбранное значение не удовлетворяет описанному в методе условию, то оно не будет установлено в качестве текущего значения элемента управления.

Настройка внешнего вида#

Элемент управления по умолчанию поддерживает изменение размера выпадающего списка путём перетаскивания его границ указателем мыши.

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

<PageableLookup caption="Модель (постраничный)" valueMember="VCode" displayMember="Name" dataSource="./client.model.json" rowsCount="5" topCount="1">
  <Column datafield="Email" text="covfefe" width="200" hint="Колонка 1">
    <TextBox maxLength="5"/>
  </Column>
  <Column datafield="Email2" hint="Колонка 2"/>
  <Column datafield="Email3" hint="Колонка 3"/>
</PageableLookup>

Также колонкам можно задавать ширину с помощью их свойства width.

Ввод с клавиатуры#

Функционал элемента управления Lookup поддерживает работу с клавиатурой. При фокусировке на элемент упарвления с помощью клавиш со стрелками можно переключаться между кодовым полем (valueMember) и поле наименования (displayMember), а также открывать выпадающий список и переходить в нём по доступным значениям. Выбрать нужное значение можно с помощью клавиши Enter.

При вводе текста в поля элемента управления осуществляется фильтрация доступных значений после секундной паузы во вводе.