Скрипты Источники Данных
В качестве источника данных для автозаполнения полей можно использовать скрипты. С помощью скриптов вы можете заполнить поля данными любого сервиса, предоставляющего API, или данными других библиотек.
Жизненный цикл скрипта источника данных
- Пользователь вводит текст в поле формы редактирования записи.
- Введенный текст передается в скрипт источника данных в виде глобальной переменной query.
- Выполняется скрипт.
- Пользователю показывается список найденных скриптом объектов.
- Пользователь выбирает объект и свойства этого объекта записываются в поля записи согласно правилам заполнения.
- Если скрипт вернул функцию получения дополнительных данных, то эта функция вызывается и результат её работы также записывается в поля записи.
Шаг 1. Добавление источника данных для автозаполнения
- Откройте экран редактирования библиотеки, перейдите на вкладку Autofill и нажмите кнопку +.
- Если поиск данных для автозаполнения должен выполняться по названию, то выберите By title. Если поиск должен выполняться по штрихкоду - выберите By barcode.
- Выберите Custom source.
- Выберите поле, через которое будет осуществляться поиск данных в источнике.
- После открытия окна правил автозаполнения нажмите на Скрипт источника данных.
Шаг 2. Написание скрипта
Скрипт выполняется в контексте библиотеки и для него доступны те же функции и объекты, что и для триггеров. Для скрипта применяются те же параметры безопасности, что и для триггеров.
Результаты работы скрипта следует передать в функцию result в виде массива объектов.
result(objects , extraFun)
- Функция для возврата найденных скриптом объектов.
- Аргументы
- objects — список объектов, которые будут отображены пользователю для выбора.
- extraFun — функция дополнительной загрузки данных, необязательный аргумент. Эта функция запускается при выборе пользователем одного из объектов.
- Объекты переданные в функцию result могут иметь следующие стандартные свойства:
- title - название объекта.
- desc - дополнительный текст отображаемый под названием объекта.
- thumb - ссылка на изображение объекта.
- id - идентификатор объекта. Идентификатор следует установить если планируется использовать функцию дополнительной загрузки данных.
Пример источника данных для поиска и получения информации из другой библиотеки.
var anotherLib = libByName(“AnotherLib”)
var entries = anotherLib.find(query);
var resultArray = new Array();
for(var i in entries ) {
Var object = new Object();
Object[“title”] = entries[i].title;
Object[“desc”] = entries[i].description;
Object[“number”] = entries[i].field(“Number”);
resultArray.put(object);
}
result(resultArray);
Загрузка дополнительных данных
Многие сервисы (API) при поиске выдают общую информацию, без деталей. Чтобы получить полную информацию, требуется выполнить отдельный запрос к API. Для этого используйте функцию загрузки дополнительных данных. В качестве аргумента в функцию передается идентификатор выбранного пользователем объекта. Функция должна возвращать объект, свойства которого будут записаны в поля записи с использованием правил автозаполнения.
Для примера возьмем абстрактное API с двумя методами:
- http://api.example.com/search?q='search_query' - выполняет поиск объектов, в результатах поиска передаются только идентификаторы и имена объектов. В качестве результата возвращается json массив объектов. Каждый объект имеет обязательные title и id.
- http://api.example.com/get?id=123 - получает подробную информацию об объекте по его идентификатору. В качестве результата возвращается json объект.
Скрипт источника данных может быть следующим:
var jsonResult = http().get("http://api.example.com/search?q=" + encodeURIComponent(query));
result (
JSON.parse(jsonResult) ,
function(id) {
return http().get("http://api.example.com/get?id=" + id);
});
Шаг 3. Настройка правил автозаполнения
После создания скрипта необходимо соотнести свойства возвращаемых им объектов с полями библиотеки:
- Закройте экран редактирования скрипта и нажмите кнопку +.
- Откроется диалог создания правила автозаполнения.
- Укажите название свойства объекта, возвращаемого скриптом.
- Выберите поле библиотеки, в которое будет записано указанное свойство.
- Создайте правила для остальных свойств объектов.
Пример реализации источника данных
Для примера рассмотрим сервис https://www.discogs.com/ , предоставляющий информацию о музыкальных альбомах. Этот сервис имеет открытое API, документация по которому доступна здесь: https://www.discogs.com/developers/
Пример реализации JavaScript-библиотеки, выполняющей запросы к данному сервису, доступен в репозитории скриптов Memento на github.com:
https://github.com/mementodatabase/scripts/blob/master/data-sources/discogs.js
Вы можете подключить эту библиотеку в редакторе скрипта источника данных:
- Откройте редактор скрипта источника данных.
- Нажмите Add javascript libraries…
- Перейдите на вкладку Repositories
- Выберите репозиторий github.com/mementodatabase/scripts/data-sources
- Выберите discogs.js
Скрипт источника данных при использовании данной библиотеки может быть следующим:
var discogs = new Discogs("Consumer key" ,"Consumer secret" , "release")
var r = discogs.search(query);
result( r , function(id) { return discogs.extra(id);});
- Consumer key и Consumer secret - это ключи, требуемые при выполнении запросов. Они могут быть получены по этой ссылке : https://www.discogs.com/settings/developers
- После создания скрипта необходимо настроить соответствие свойств объектов, возвращаемых скриптом, и полей библиотеки. Доступные свойства объектов можно узнать в документации к Discogs API - смотрите пример ответа при успешном запросе ресурса: https://www.discogs.com/developers/#page:database,header:database-release
- Если поиск в источнике данных необходимо выполнять по штрихкоду, то вместо discogs.search(query) используйте discogs.barcode(query)