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

From Memento Database Wiki
Revision as of 13:57, 17 August 2021 by UnConnoisseur (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

В качестве источника данных для автозаполнения полей можно использовать скрипты. С помощью скриптов вы можете заполнить поля данными любого сервиса, предоставляющего 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[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. Настройка правил автозаполнения

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

  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)