Подключение внешнего справочника

Чтобы подключить внешний справочник к подсказкам, выполните следующие шаги:

Подготовьте справочник.
Подготовьте конфигурацию.
Скопируйте справочник и конфигурацию на сервер подсказок.
Перезагрузите подсказки.
Используйте через API или jQuery-плагин.

Ниже каждый из шагов рассмотрен более подробно.

Справочник

Справочник — это обычный CSV-файл:

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

Если надо, чтобы подсказки возвращали вычисляемые поля (например, «ФИО», составленное из фамилии, имени, и отчества) — эти поля тоже должны быть в справочнике. Сами подсказки их делать не умеют.

Если одни записи справочника более «весомые», чем другие (например, головные организации и филиалы), то веса должны быть предрассчитаны для всех записей и вынесены в отдельный столбец — сами подсказки этого делать не будут.

Все значения подсказки трактуют как строки, даже если по факту это числа или даты.

Пример справочника

hid	name	surname	patronymic	fullname	email	phone	inn	salary	position	department
1001	Волкова	Татьяна	Анатольевна	Волкова Татьяна Анатольевна	volkova.tatyana@evercorp.ru	+7 926 387-34-23	560104625432	50000	Менеджер по закупкам	Отдел закупок
1002	Барчук	Валерий	Николаевич	Барчук Валерий Николаевич	barchuk.valeriy@evercorp.ru	+7 495 234-13-98	490875413490	45000	Менеджер по продажам	Отдел корпоративных продаж
1003	Жукова	Кристина	Олеговна	271307275938	ceo@evercorp.ru		271307275938	90000	Директор
...

Конфигурация

Конфигурация — это YAML-файл, который описывает, как подсказки работают со справочниками. Проще всего объяснить его на примере:

# название справочника
# наш пример — справочник сотрудников
name: employees
# настройки чтения CSV файла
# необязательно, значения по умолчанию описаны ниже
csv:
  quote: '"'
  delimiter: ','
  endOfLine: '\n'
  encoding: UTF-8
# какие есть поля и как их использовать
fields:
  # Исправлять латинскую раскладку, по умолчанию true
  switch_layout: false
  # какие поля участвуют в поиске по идентификаторам
  # необязательно, по умолчанию не задано
  ids:
    hid: ~
    inn: ~
  # какие поля участвуют в полнотекстовом поиске (обязательно хотя бы одно)
  # для полей можно указать параметр boost — вес для ранжирования
  # чем больше вес, тем «весомее» считается совпадение по этому полю
  # например, если вес по fullname = 10, а по email = 1,
  # то совпадение по ФИО считается весомее, чем по адресу эл. почты
  # по умолчанию вес = 1
  search:
    fullname:
      boost: 10
    email: ~
    phone: ~
  # по каким полям фильтровать
  # необязательно, по умолчанию не задано
  filter:
    department: ~
  # по какому полю ранжировать
  # необязательно, по умолчанию не задано
  # чем больше значение, тем выше ранжируется соответствующая запись справочника
  # если указано несколько полей, то значения умножаются
  # по умолчанию вес = 1
  boost:
    salary: ~
  # по какому полю сортировать
  # необязательно, по умолчанию равно настройке fields.value + ALPHA_NUMERIC
  # принцип сортировки:
  #   ALPHA_NUMERIC - по алфавиту (с честной сортировкой чисел)
  #   TOKEN_COUNT - по количеству слов (чем меньше слов, тем выше позиция)
  sort:
    fullname:   TOKEN_COUNT
    department: ALPHA_NUMERIC
  # какое поле показывать в списке (suggestion.value, обязательно)
  value: fullname
  # какое поле содержит полное значение одной строкой
  # необязательно, по умолчанию равно настройке fields.value
  unrestricted_value: fullname_with_position
  # какие поля возвращать в объекте подсказки (suggestion.data)
  # необязательно, по умолчанию не задано (suggestion.data == null)
  data:
    name: ~
    surname: ~
    patronymic: ~
    email: ~
    phone: ~
    position: ~
    department: ~

Скопировать на сервер

Конфигурацию:

Сохранить конфигурацию в файл {name}.yaml, где {name} — название справочника, как указано в конфигурации.
Скопировать файл на сервер в каталог /SGT_ROOT/configuration/

Справочник:

Сохранить справочник в файл {name}.csv, где {name} — название справочника, как указано в конфигурации.
Создать на сервере каталог /SGT_ROOT/dictionaries/{name}/ и скопировать в него файл справочника.

API

Аналогично «родным» справочникам:

POST /suggestions/api/4_1/rs/suggest/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "Василий"
}

Поддерживается стандартный параметр count и фильтрация (если была настроена):

POST /suggestions/api/4_1/rs/suggest/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "Василий",
  "filters": [{"department": "Маркетинг"}, {"department": "ИТ"}]
  "count": 5
}

Поиск по идентификаторам (если был настроен):

POST /suggestions/api/4_1/rs/findById/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "1024"
}

jQuery-плагин

В плагине всё как обычно, только в поле type указывается название справочника:

$("#manager").suggestions({
  type: "employees",
  ...
});

Дерево страниц