Скрипты Источники Данных

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

Жизненный цикл скрипта источника данных

1. Пользователь вводит текст в поле формы редактирования записи.
2. Введенный текст передается в скрипт источника данных в виде глобальной переменной query.
3. Выполняется скрипт.
4. Пользователю показывается список найденных скриптом объектов.
5. Пользователь выбирает объект и свойства этого объекта записываются в поля записи согласно правилам заполнения.
6. Если скрипт вернул функцию получения дополнительных данных, то эта функция вызывается и результат её работы также записывается в поля записи.

Шаг 1. Добавление источника данных для автозаполнения

1. Откройте экран редактирования библиотеки, перейдите на вкладку Autofill и нажмите кнопку +.
2. Если поиск данных для автозаполнения должен выполняться по названию, то выберите By title. Если поиск должен выполняться по штрихкоду - выберите By barcode.
3. Выберите Custom source.
4. Выберите поле, через которое будет осуществляться поиск данных в источнике.
5. После открытия окна правил автозаполнения нажмите на Скрипт источника данных.

Шаг 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[“hint”] = 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. Настройка правил автозаполнения

После создания скрипта необходимо соотнести свойства возвращаемых им объектов с полями библиотеки:

1. Закройте экран редактирования скрипта и нажмите кнопку +.
2. Откроется диалог создания правила автозаполнения.
3. Укажите название свойства объекта, возвращаемого скриптом.
4. Выберите поле библиотеки, в которое будет записано указанное свойство.
5. Создайте правила для остальных свойств объектов.

Пример реализации источника данных

Для примера рассмотрим сервис 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
Вы можете подключить эту библиотеку в редакторе скрипта источника данных:

1. Откройте редактор скрипта источника данных.
2. Нажмите Add javascript libraries…
3. Перейдите на вкладку Repositories
4. Выберите репозиторий github.com/mementodatabase/scripts/data-sources
5. Выберите 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)