Changes

Jump to navigation Jump to search
Created page with "В качестве источника данных для автозаполнения полей можно использовать с..."
В качестве источника данных для [[Library_Edit_screen#AUTOFILL_tab|автозаполнения]] полей можно использовать скрипты. С помощью скриптов вы можете заполнить поля данными любого сервиса, предоставляющего API, или данными других библиотек.

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

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

==Шаг 2. Написание скрипта==
Скрипт выполняется в контексте библиотеки и для него доступны те же функции и объекты, что и для [[Триггеры|триггеров]]. Для скрипта применяются те же параметры [[Triggers#Security|безопасности]], что и для триггеров.<br/>
Результаты работы скрипта следует передать в функцию '''result''' в виде массива объектов.

====== result(objects , extraFun) ======
: Функция для возврата найденных скриптом объектов.
:; Аргументы
:: '''objects''' &mdash; список объектов, которые будут отображены пользователю для выбора.
:: '''extraFun''' &mdash; функция дополнительной загрузки данных, необязательный аргумент. Эта функция запускается при выборе пользователем одного из объектов.

:Объекты переданные в функцию '''result''' могут иметь следующие стандартные свойства:
:: '''title''' - название объекта.
:: '''hint''' - дополнительный текст отображаемый под названием объекта.
:: '''icon''' - ссылка на изображение объекта.
:: '''id''' - идентификатор объекта. Идентификатор следует установить если планируется использовать функцию дополнительной загрузки данных.

=== Пример источника данных для поиска и получения информации из другой библиотеки. ===
<source lang="javascript">
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);
</source>

===Загрузка дополнительных данных===
Многие сервисы (API) при поиске выдают общую информацию, без деталей. Чтобы получить полную информацию, требуется выполнить отдельный запрос к API. Для этого используйте функцию загрузки дополнительных данных. В качестве аргумента в функцию передается идентификатор выбранного пользователем объекта. Функция должна возвращать объект, свойства которого будут записаны в поля записи с использованием правил автозаполнения.<br/>
Для примера возьмем абстрактное API с двумя методами:
:: http://api.example.com/search?q='search_query' - выполняет поиск объектов, в результатах поиска передаются только идентификаторы и имена объектов. В качестве результата возвращается json массив объектов. Каждый объект имеет обязательные title и id.
:: http://api.example.com/get?id=123 - получает подробную информацию об объекте по его идентификатору. В качестве результата возвращается json объект.

Скрипт источника данных может быть следующим:
<source lang="javascript">
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);
});
</source>

==Шаг 3. Настройка правил автозаполнения==
После создания скрипта необходимо соотнести свойства возвращаемых им объектов с полями библиотеки:
# Закройте экран редактирования скрипта и нажмите кнопку '''+'''.
# Откроется диалог создания правила автозаполнения.
# Укажите название свойства объекта, возвращаемого скриптом.
# Выберите поле библиотеки, в которое будет записано указанное свойство.
# Создайте правила для остальных свойств объектов.

==Пример реализации источника данных==
Для примера рассмотрим сервис https://www.discogs.com/ , предоставляющий информацию о музыкальных альбомах. Этот сервис имеет открытое API, документация по которому доступна здесь: https://www.discogs.com/developers/<br/>
Пример реализации JavaScript-библиотеки, выполняющей запросы к данному сервису, доступен в репозитории скриптов Memento на github.com:
https://github.com/mementodatabase/scripts/blob/master/data-sources/discogs.js<br/>
Вы можете подключить эту библиотеку в редакторе скрипта источника данных:
# Откройте редактор скрипта источника данных.
# Нажмите '''Add javascript libraries…'''
# Перейдите на вкладку '''Repositories'''
# Выберите репозиторий '''github.com/mementodatabase/scripts/data-sources'''
# Выберите '''discogs.js'''

Скрипт источника данных при использовании данной библиотеки может быть следующим:
<source lang="javascript">
var discogs = new Discogs("Consumer key" ,"Consumer secret" , "release")
var r = discogs.search(query);
result( r , function(id) { return discogs.extra(id);});
</source>

* Consumer key и Consumer secret - это ключи, требуемые при выполнении запросов. Они могут быть получены по этой ссылке : https://www.discogs.com/settings/developers<br/>
* После создания скрипта необходимо настроить соответствие свойств объектов, возвращаемых скриптом, и полей библиотеки. Доступные свойства объектов можно узнать в документации к Discogs API - смотрите пример ответа при успешном запросе ресурса: https://www.discogs.com/developers/#page:database,header:database-release<br/>
* Если поиск в источнике данных необходимо выполнять по штрихкоду, то вместо discogs.search(query) используйте discogs.barcode(query)

Navigation menu