Произвольный внешний справочник

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

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

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

Справочник

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

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

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

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

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

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

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

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

# название справочника
# наш пример — справочник сотрудников
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: ~

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

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

1. Сохранить конфигурацию в файл {name}.yaml, где {name} — название справочника, как указано в самом первом параметре конфигурации.
   Для нашего примера это employees.yaml
2. Создать на сервере каталог /SGT_ROOT/configuration/outward/ и скопировать в него файл конфигурации.
   Для нашего примера итоговый путь к файлу будет /data/configuration/outward/employees.yaml

Справочник:

1. Сохранить справочник в файл {name}.csv, где {name} — название справочника, как указано в конфигурации.
   Для нашего примера это employees.csv
2. Создать на сервере каталог /SGT_ROOT/dictionaries/{name}/ и скопировать в него файл справочника.
   Для нашего примера итоговый путь к файлу будет /data/dictionaries/employees/employees.csv

Чтобы подсказки увидели, справочник, перезапустите их либо используйте API.

Проверить на демо-странице

Работу подсказок можно проверить на демо-странице по адресу http://СЕРВЕР:ПОРТ/suggestions/outward

В поле «Тип» укажите название справочника, после этого подсказки заработают:

API

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

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

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

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

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",
  ...
});

Если конфигурация справочника допускает, можно использовать фильтрацию:

$("#manager").suggestions({
  type: "employees",
  params: {
    filters: [
      { "department": "Отдел закупок"}
    ]
  }
});