Difference between revisions of "Скрипты Источники Данных"

From Memento Database Wiki
Jump to navigation Jump to search
(Created page with "В качестве источника данных для автозаполнения полей можно использовать с...")
 
Line 28: Line 28:
 
:Объекты переданные в функцию '''result''' могут иметь следующие стандартные свойства:
 
:Объекты переданные в функцию '''result''' могут иметь следующие стандартные свойства:
 
:: '''title''' - название объекта.
 
:: '''title''' - название объекта.
:: '''hint''' - дополнительный текст отображаемый под названием объекта.
+
:: '''desc''' - дополнительный текст отображаемый под названием объекта.
:: '''icon''' - ссылка на изображение объекта.
+
:: '''thumb''' - ссылка на изображение объекта.
 
:: '''id''' - идентификатор объекта. Идентификатор следует установить если планируется использовать функцию дополнительной загрузки данных.
 
:: '''id''' - идентификатор объекта. Идентификатор следует установить если планируется использовать функцию дополнительной загрузки данных.
  

Revision as of 23:15, 27 February 2017

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