Подсказки при вводе ФИО в отдельных полях

В основной статье про подсказки для ФИО, которую можно посмотреть здесь, мы рассказали, как с помощью Ахантера сделать быстрый и удобный ввод ФИО одной строкой в одном поле формы.

Однако в некоторых случаях вам может понадобиться заполнять ФИО по отдельности в трёх разных полях. Для этих целей в Ахантере реализована поддержка дискретного ввода ФИО, который подразумевает, что фамилия, имя и отчество в вашей форме вводятся отдельно друг от друга в соответствующих полях. Подсказки в этом случае формируются для каждого такого поля по отдельности, а не для всего ФИО целиком.

Как работают дискретные подсказки для ФИО

Также как и в случае с однострочным вводом ФИО, Ахантер предлагает подсказки с учётом пола и национальности персоны. Эти сведения он распознаёт по уже введённой информации в остальных полях формы.

Приведенная ниже форма демонстрирует вживую, как это работает. Список подсказок отображается при вводе компонентов ФИО в соответствующие поля формы.

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

• Соответствие пола (все компоненты ФИО должны относиться к одному и тому же полу).
• Соответствие национальности (компоненты ФИО с высокой вероятностью относятся к одной и той же или близким национальностям).

Таким образом, если пользователь ввёл, например, армянское женское имя в поле Имя, то при вводе в поля Отчество и Фамилия ему будут предлагаться подсказки с армянскими женскими отчествами и фамилиями соответственно. При формировании подсказок учитывается, что слова, составляющие ФИО, могут содержать ошибки. При выполнении поиска осуществляется автоматическое исправление этих ошибок.

В демонстрационной форме, приведённой выше, для отображения подсказок используется наш JavaScript-модуль ahunter_suggest.js, скачать его можно по следующей ссылке. Модуль использует библиотеку jQuery, поэтому, чтобы запустить подсказки у вас на сайте, в дополнение к ahunter_suggest.js нужно будет установить свежую версию jQuery.

Для запуска подсказок в этой форме мы использовали следующий JavaScript-код.

//настраиваем подсказки для ввода ФИО в отдельных полях
var options = 
{ 
  fields: 
  [ 
    { id: 'js-Field1', tag: 'last_name' },
    { id: 'js-Field2', tag: 'first_name' },
    { id: 'js-Field3', tag: 'patronym' }
  ]
};

//запускаем дискретные подсказки
AhunterSuggest.Person.Discrete( options );

Детальное описание этого кода, а также описание подготовки вашего сайта к использованию подсказок приводится далее в этой статье.

В большинстве случаев для работы с подсказками бывает достаточно использовать модуль ahunter_suggest.js. Однако если вам нужно встроить подсказки в отдельное приложение, либо если у вас есть своё JavaScript решение для отображения подсказок, то для получения подсказок от Ахантера нужно будет использовать напрямую его REST API. Соответствующее описание приводится во второй части данной статьи.

Дискретные подсказки для ФИО на веб-сайте

Подготовка сайта для подключения подсказок

Чтобы добавить дискретные подсказки для фамилий, имён и отчеств на сайт, как и в случае с обычными подсказками, необходимо выполнить подготовку сайта. А именно, нужно установить jQuery, установить наш JavaScript-модуль ahunter_suggest.js, взяв его здесь, а также настроить таблицу стилей, чтобы подсказки отображались красиво.

Все эти процедуры детально описаны в подсказках для почтовых адресов по следующей ссылке. При разработке модуля ahunter_suggest.js мы реализовали единообразную работу с почтовыми адресами и ФИО, поэтому подготовка в обоих случаях выполняется одинаково.

Подключение подсказок на сайте

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

Каждому из этих полей вашей формы должен быть присвоен идентификатор, чтобы по нему наш модуль ahunter_suggest.js смог найти это поле на веб-странице и запустить для него подсказки. HTML-разметка такой формы может выглядеть следующим образом.

<div>
  <input id="js-Field1" placeholder="Фамилия"/> 
  <input id="js-Field2" placeholder="Имя"/> 
  <input id="js-Field3" placeholder="Отчество"/> 
</div>

Согласно этой форме, первое поле с идентификатором js-Field1 предназначено для ввода фамилии. В поле с идентификатором js-Field2 пользователи будут вводить свои имена, а в поле с идентификатором js-Field3 – отчества. Когда пользователь будет заполнять эти поля, Ахантер должен будет предлагать подсказки для соответствующего компонента ФИО.

Чтобы сообщить Ахантеру, какие именно подсказки он должен предлагать при заполнении этих полей, необходимо в опциях модуля явно указать связь между компонентами ФИО и полями вашей формы. Для этого на странице с формой нужно добавить следующий код.

//настраиваем подсказки для ввода ФИО в отдельных полях
var options = 
{ 
  fields: 
  [ 
    { id: 'js-Field1', tag: 'last_name' },
    { id: 'js-Field2', tag: 'first_name' },
    { id: 'js-Field3', tag: 'patronym' }
  ]
};

//запускаем дискретные подсказки
AhunterSuggest.Person.Discrete( options );

Здесь видно, что в опциях options заполняется список fields, каждый элемент которого устанавливает связь между полем вашей формы и одним из компонентов ФИО, для которого Ахантер будет предлагать подсказки. Эта связь устанавливается за счёт пары из двух следующих обязательных полей.

• id – строковый идентификатор вашего поля формы, при редактировании которого будут формироваться подсказки.
• tag – идентификатор, который использует Ахантер, чтобы различать компоненты ФИО. Данный идентификатор может принимать три следующих значения.
  • last_name – соответствует фамилии;
  • first_name – соответствует имени;
  • patronym – соответствует отчеству.
  Задавая одно из этих значений в поле tag, мы таким образом сообщаем Ахантеру, для какого компонента ФИО нужно формировать подсказки в соответствующем поле формы.

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

После того как настройки в объекте options заполнены, они передаются нашему модулю посредством вызова AhunterSuggest.Person.Discrete( options ). Этот вызов привяжет функционал дискретных подсказок к заданным в списке options.fields полям формы, так что ввод ФИО в этих полях будет приводить к отображению подсказок.

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

Среди этих опций следует отдельно выделить флаг suggest_on_empty, который, в отличие от адресных подсказок, не применяется для ФИО.

Пример запуска подсказок с разными опциями

Ниже приведён пример инициализации формы из трёх полей, для которых подсказки запускаются с использованием дополнительных опций.

//настраиваем подсказки для ввода ФИО в отдельных полях
var options = 
{ 
  fields: 
  [ 
    { 
      id: 'js-Field1', 
      tag: 'last_name', 
      empty_msg : 'Неизвестная фамилия'
    },
    { 
      id: 'js-Field2', 
      tag: 'first_name',
      empty_msg : 'Неизвестное имя'
    },
    { 
      id: 'js-Field3', 
      tag: 'patronym',
      empty_msg : 'Неизвестное отчество'
    }
  ],
  //Веб-адрес облачной версии сервиса
  ahunter_url : 'https://ahunter.ru/',

  //Будем показывать только 5 топовых подсказок
  limit : 5,
  
  //Не будем показывать подсказки при возврате фокуса в поле ввода
  suggest_on_focus : false
};

//запускаем дискретные подсказки
AhunterSuggest.Person.Discrete( options );

Здесь у каждого поля мы дополнительно указали параметр empty_msg, который содержит сообщение, показываемое пользователю, если в соответствующее поле он ввёл что-то неизвестное Ахантеру. Это сообщение будет появляться под редактируемым полем. Такие сообщения полезно показывать, поскольку они своевременно предупреждают пользователя о том, что он вводит некорректные данные, и, таким образом, стимулируют его исправить уже введённую информацию.

Кроме этого в данной конфигурации мы явно запретили показывать подсказки при переключении фокуса между полями формы. Это сделано с помощью флага suggest_on_focus = false. Также с помощью параметра limit у всех полей формы установлен лимит на количество показываемых подсказок.

Ниже показано, как будет работать эта форма вживую.

REST API дискретных подсказок для ФИО

Использование REST API дискретных подсказок напрямую без модуля ahunter_suggest.js может потребоваться, если вы хотите использовать подсказки в вашем приложении, не поддерживающем JavaScript или jQuery. В этом случае, как и с обычными подсказками для ФИО, следует использовать ту же самую API команду suggest/person. Однако для работы в дискретном режиме понадобится передавать дополнительные параметры, а также немного иначе оформлять сам запрос.

Принципы использования API подсказок при дискретном вводе ФИО

Дискретный режим команды suggest/person подразумевает, что компоненты ФИО вводятся не в одно, а в три разных поля: в одном поле вводится фамилия, в другом поле – имя, а в третьем - отчество. В любой момент времени редактироваться может только одно из этих полей, при этом полагается, что остальные два поля либо уже полностью заполнены, либо пока пусты. Каждый раз, когда пользователь вводит очередной символ в одно из этих полей, увеличивается количество информации, на основе которой сервис может сформировать подсказки для соответствующего компонента ФИО. При этом информация, уже введённая в других полях, тоже должна учитываться.

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

Для организации такого взаимодействия ваше приложение должно отслеживать события, возникающие, когда происходят изменения в каком-либо поле формы. При возникновении такого события приложение должно отсылать сервису запрос, содержащий текст, введенный к настоящему моменту в каждое из этих полей, с указанием того, в какое из них сейчас вводится информация, чтобы Ахантер вернул подсказки именно для этого компонента ФИО.

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

Пример простого запроса подсказок

Приведенный ниже запрос отсылает сервису информацию о том, что в поле Фамилия введен текст "Смирнов", а в поле Имя пользователь к настоящему моменту ввёл текст "А" и продолжает ввод. На основании этой информации сервис должен сформировать подсказки для завершения компонента, вводимого пользователем в настоящий момент (в данном случае этим компонентом является имя).

В данном запросе используются следующие параметры.

• output=json – сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• last_name=%D0%A1%D0 ... %BE%D0%B2 – закодированная с использованием URL-encoding введенная пользователем фамилия "Смирнов" в кодировке UTF-8.
• first_name=%D0%90 - закодированное с использованием URL-encoding введенное пользователем начало имени "А" в кодировке UTF-8, для которого необходимо получить подсказки.
• active=first_name – сообщает сервису о том, что в настоящий момент пользователь вводит имя, и именно для него должны быть сформированы подсказки.

Рассмотрим более подробно все параметры, которые сервис может получать в рамках данной команды.

Параметры команды

Обязательные параметры для выполнения запроса.

• http://ahunter.ru/site/suggest/person - URL-команды.
• output=json или output=xml – формат, в котором требуется вернуть результат выполнения команды.
• active=last_name или active=first_name или active=patronym – компонент ФИО, вводимый пользователем в настоящий момент. Для этого компонента сервис должен сформировать подсказки.

Опциональные параметры.

• last_name=строка – строка, содержащая введенную пользователем фамилию персоны. Если этот параметр не задан, полагается, что поле Фамилия пусто.
• first_name=строка – строка, содержащая введенное пользователем имя персоны. Если этот параметр не задан, полагается, что поле Имя пусто.
• patronym=строка – строка, содержащая введенное пользователем отчество персоны. Если этот параметр не задан, полагается, что поле Отчество пусто.
• output=pretty – опция, применимая только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON-текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом. Если этот параметр не задан, JSON-ответ будет возвращен в виде сплошной строки.
• output=cp1251 – опция, применимая только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251. Если этот параметр не задан, данные возвращаются в кодировке UTF-8.
• input=utf8 или input=cp1251 – кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметрах last_name, first_name и patronym. Если этот параметр не задан, полагается, что данные получены в кодировке UTF-8.
• personlim=число - ограничение на число возвращаемых подсказок. Если данное значение превышает установленный администратором сервиса порог, равный 20 подсказкам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный параметр не указан, то в качестве лимита будет выступать установленное администратором сервиса умолчальное значение, равное 10 подсказкам.

Пример запроса подсказок с дополнительными опциями

Приведенный ниже запрос отсылает сервису информацию о том, что в поле Имя введен текст "Фёдор", в поле Отчество - текст "Михайлович", а в поле Фамилия пользователь к настоящему моменту ввёл текст "Д" и продолжает ввод. На основании этой информации сервис должен сформировать подсказки для завершения компонента, вводимого пользователем в настоящий момент (в данном случае этим компонентом является фамилия).

В данном запросе используются следующие параметры.

• input=utf8 – сообщает сервису о том, что обрабатываемая строка представлена в кодировке UTF-8.
• output=json|pretty – сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
• first_name=%D0%A4%D1 ... %BE%D1%80 – закодированное с использованием URL-encoding введенное пользователем имя "Фёдор" в кодировке UTF-8.
• patronym=%D0%9C%D0 ... %B8%D1%87 - закодированное с использованием URL-encoding введенное пользователем отчество "Михайлович" в кодировке UTF-8.
• last_name=%D0%94 - закодированное с использованием URL-encoding введенное пользователем начало фамилии "Д" в кодировке UTF-8, для которого необходимо получить подсказки.
• active=last_name – сообщает сервису о том, что в настоящий момент пользователь вводит фамилию, и именно для неё должны быть сформированы подсказки.
• personlim=3 – сообщает сервису, что следует вернуть только три наиболее подходящие подсказки для вводимого ФИО.

Результат запроса: подсказки в формате JSON

Ниже приведен ответ сервиса с результатом формирования подсказок по запросу со следующими исходными данными:

• Имя: "Фёдор"
• Отчество: "Михайлович"
• Фамилия: "Д" (вводится в настоящий момент).

Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста, а также с опцией personlim=3, чтобы ограничить число выводимых подсказок тремя штуками

{
  "query" : "Фёдор Михайлович Д",
  "request_process_time" : 15,
  "suggestions" : [
    {
      "first_name" : "Фёдор",
      "last_name" : "Дмитриев",
      "patronym" : "Михайлович",
      "value" : "Дмитриев"
    },
    {
      "first_name" : "Фёдор",
      "last_name" : "Давыдов",
      "patronym" : "Михайлович",
      "value" : "Давыдов"
    },
    {
      "first_name" : "Фёдор",
      "last_name" : "Денисов",
      "patronym" : "Михайлович",
      "value" : "Денисов"
    }
  ]
}

Результатом формирования подсказок для вводимого ФИО является JSON-объект со следующими элементами.

• suggestions – массив с вариантами подсказок для обработанного ФИО.
• query – строка, содержащая все полностью или частично введенные пользователем компоненты ФИО.
• request_process_time – время обработки всего запроса в целом в миллисекундах.

Ниже приведено детальное описание этих элементов.

JSON-массив suggestions

Поскольку при формировании подсказок полагается, что ФИО введено не полностью, вариантов завершения написания компонента ФИО, вводимого пользователем в настоящий момент, в общем случае может быть несколько. Каждый из вариантов является подсказкой для пользователя, которую тот может выбрать в качестве целевого значения компонента. Каждому предлагаемому сервисом варианту соответствует отдельный элемент JSON-массива suggestions. Количество предлагаемых вариантов может лимитироваться с помощью опционального параметра personlim, передаваемого в рамках запроса.

Пример JSON-объекта, соответствующего одному варианту подсказок для вводимого ФИО, приведен ниже.

{
  "first_name" : "Фёдор",
  "last_name" : "Дмитриев",
  "patronym" : "Михайлович",
  "value" : "Дмитриев"
}

Каждый элемент массива suggestions представляет собой JSON-объект со следующими элементами.

• first_name - имя подсказываемого ФИО.
• last_name - фамилия подсказываемого ФИО.
• patronym - отчество подсказываемого ФИО.
• value – строка, содержащая один из вариантов завершения компонента ФИО, вводимого пользователем в настоящий момент. Это именно то значение, которое будет отображаться пользователю на экране в качестве подсказываемого варианта. В зависимости от компонента ФИО, для которого запрашиваются подсказки с помощью параметра active, оно будет совпадать с одним из элементов, приведённых выше: first_name, last_name или patronym. Вариант компонента ФИО, предлагаемый сервисом в этой строке, приведён в стандартизованном виде с исправленными ошибками.

Поскольку формирование подсказок происходит в режиме реального времени, никакой дополнительной информации по каждой подсказке сервис не возвращает. Это обусловлено необходимостью минимизировать сетевой трафик и время отклика сервиса. Чтобы получить исчерпывающую информацию по итоговому ФИО, которое ввел или выбрал из предложенных подсказок пользователь, приложению пользователя следует использовать команду стандартизации ФИО: cleanse/person.

Результат запроса: подсказки в формате XML

Здесь и далее приводится описание ответа сервиса в случае использования формата XML. По существу, возвращаемые в XML-ответе элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.

Ниже приведен XML-ответ сервиса в результате формирования подсказок по запросу со следующими исходными данными:

• Имя: "Фёдор"
• Отчество: "Михайлович"
• Фамилия: "Д" (вводится в настоящий момент).

<ProcessSuggestResult>
  <Query val="Фёдор Михайлович Д"/>
  <Suggestion first_name="Фёдор" 
              last_name="Дмитриев" 
              patronym="Михайлович" 
              val="Дмитриев"/>
  <Suggestion first_name="Фёдор" 
              last_name="Давыдов" 
              patronym="Михайлович" 
              val="Давыдов"/>
  <Suggestion first_name="Фёдор" 
              last_name="Денисов" 
              patronym="Михайлович" 
              val="Денисов"/>
</ProcessSuggestResult>  

Результатом формирования подсказок для вводимого ФИО является XML-документ со следующими дочерними элементами.

• Query – данный XML-элемент содержит строку, включающую все полностью или частично введенные пользователем компоненты ФИО. Эта строка передается с помощью атрибута val этого XML-элемента. Данный элемент является полным аналогом JSON-элемента query, возвращаемого в JSON-ответе сервиса.
• Suggestion – данный XML-элемент соответствует одному из предложенных сервисом вариантов завершения написания компонента ФИО, вводимого пользователем в настоящий момент. Поскольку при формировании подсказок полагается, что ФИО введено не полностью, таких вариантов может быть несколько. В связи с этим в XML-ответе может присутствовать несколько элементов Suggestion. Список из всех XML-элементов Suggestion является аналогом JSON-массива suggestions, возвращаемого в JSON-ответе сервиса.

Ниже приведено детальное описание этих XML-элементов.

XML-элемент Suggestion

Элемент Suggestion содержит информацию об одной подсказке из предложенного сервисом списка подсказок по вводимому ФИО. Пример данного элемента приведен ниже.

<Suggestion first_name="Фёдор" 
            last_name="Дмитриев" 
            patronym="Михайлович" 
            val="Дмитриев"/>

Данный элемент содержит следующие атрибуты.

• first_name - отдельное имя подсказываемого ФИО.
• last_name - фамилия подсказываемого ФИО.
• patronym - отчество подсказываемого ФИО.
• val - строка, содержащая один из вариантов завершения компонента ФИО, вводимого пользователем в настоящий момент. Вариант компонента ФИО, предлагаемый сервисом в этой строке, приведён в стандартизованном виде с исправленными ошибками.