История страницы
Информация |
---|
Требуется отдельная лицензия. Лицензия позволяет подключить любое количество справочников — как готовых из перечисленных ниже, так и собственных справочников заказчика. |
Готовые внешние справочники
Мы подготовили набор отраслевых справочников, которые можно подключить и использовать:
- кем выдан паспорт;
- почтовые отделения;
- налоговые инспекции;
- мировые суды;
- марки автомобилей;
- страны;
- валюты;
- ОКВЭД;
- ОКПД;
- и другие.
Если хотите подключить собственный справочник — читайте дальше, как это сделать.
Оглавление |
---|
Подготовить справочник
Включить страницу | ||||
---|---|---|---|---|
|
Настроить конфигурацию
Включить страницу | ||||
---|---|---|---|---|
|
Подключить конфигурацию и справочник
Включить страницу | ||||
---|---|---|---|---|
|
Проверить на демо-странице
Включить страницу | ||||
---|---|---|---|---|
|
Использовать через API
Включить страницу | ||||
---|---|---|---|---|
|
Использовать через jQuery-плагин
Включить страницу | ||||
---|---|---|---|---|
|
Чтобы подключить внешний справочник к подсказкам, выполните следующие шаги:
- Подготовьте справочник.
- Подготовьте конфигурацию.
- Скопируйте справочник и конфигурацию на сервер подсказок.
- Перезагрузите подсказки.
- Используйте через API или jQuery-плагин.
Ниже каждый из шагов рассмотрен более подробно.
Справочник
Справочник — это обычный CSV-файл:
- Плоский: даже если в исходном справочнике есть иерархия, перед подключением к подсказкам он должен быть переведен в плоский вид.
- С заголовочной строкой: она используется в настройках.
- В названии самого справочника и заголовках полей можно использовать только латинские буквы и подчёркивание.
Если надо, чтобы подсказки возвращали вычисляемые поля (например, «ФИО», составленное из фамилии, имени, и отчества) — эти поля тоже должны быть в справочнике. Сами подсказки их делать не умеют.
Если одни записи справочника более «весомые», чем другие (например, головные организации против филиалов), то веса должны быть предрассчитаны для всех записей и вынесены в отдельный столбец — сами подсказки этого делать не будут.
Все значения подсказки трактуют как строки, даже если по факту это числа или даты.
Пример справочника
...
Барчук Валерий Николаевич
...
Конфигурация
Конфигурация — это 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}
— название справочника, как указано в самом первом параметре конфигурации.
Для нашего примера этоemployees.yaml
- Создать на сервере каталог
/SGT_ROOT/configuration/outward/
и скопировать в него файл конфигурации.
Для нашего примера итоговый путь к файлу будет/data/configuration/outward/employees.yaml
Справочник:
- Сохранить справочник в файл
{name}.csv
, где{name}
— название справочника, как указано в конфигурации.
Для нашего примера этоemployees.csv
- Создать на сервере каталог
/SGT_ROOT/dictionaries/{name}/
и скопировать в него файл справочника.
Для нашего примера итоговый путь к файлу будет/data/dictionaries/employees/employees.csv
Чтобы подсказки увидели, справочник, перезапустите их.
Проверить на демо-странице
Работу подсказок можно проверить на демо-странице по адресу 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 и фильтрация (если была настроена):
Без форматирования |
---|
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
указывается название справочника:
...