Changes

Jump to navigation Jump to search
4,550 bytes added ,  12:04, 28 February 2017
m
no edit summary
Line 1: Line 1:  
{{Stamp|2017-02-25|4.3.0|1.1.0}}
 
{{Stamp|2017-02-25|4.3.0|1.1.0}}
coming soon
+
 
 +
A script can be used to as a source of data to fill fields and to fill data from any service that has an API or other libraries.
 +
 
 +
== Lifecycle of a scripted data source ==
 +
# A user types text in the field of the entry edit card.
 +
# Entered text is passed to the scripted data source in the form of the global variable '''''query'''''.
 +
# Script is executed.
 +
# The user is presented with a list of objects found by the script.
 +
# The user selects an object and arguments of the objects written into the entry field according to data load rules.
 +
# If a function is returned as a result of the script, the function is executed and the result is loaded into the field.
 +
 
 +
== Step 1 — Adding a data source for autofill ==
 +
# Open the Library Edit screen. Click on tab Autofill, and click +.
 +
# The user selects the type of search — By Name or By Barcode.
 +
# The user selects the Custom Source.
 +
# The user selects the field used for data search in the source.
 +
# The user is presented with an Autofill Rules edit card. The user selects Scripted Data Source.
 +
 
 +
== Step 2 — Script writing ==
 +
A script is executed in the context of the library, so it can use the same functions and objects as a trigger.<br/>A script has the same security parameters as a trigger.<br/>The result of the script should be returned as an array object.
 +
 
 +
; result(objects, extrafun): Function to return the result of the script.
 +
:; Arguments: objects &mdash; List of objects which will be presented to the user for selection.
 +
:; extrafun &mdash; Optional function for additional data optional argument. This function is executed with one of the objects is selected.
 +
: Objects sent to the result function can have the following standard arguments:
 +
:; title &mdash Name of the object.
 +
:; desc &mdash; Additional text shown under the name of the object.
 +
:; thumb &mdash; Reference to the image of the object.
 +
:; id &mdash; Object identifier. Used if the result is a function.
 +
 
 +
== Example &mdash; Filling data from another library ==
 +
[[onsert script here]]
 +
 
 +
== Additional data load ==
 +
Many services (APIs) return general information without details as a result of a search. To extract complete detailed information, an additional API request is needed. In this case, a function for additional data load should be used. The argument for this function is the identifier of the object selected by the user. The function returns an object whose parameters will be loaded into the fields of the entry according to autofill rules. As an example, let's use an API with two methods:
 +
# http://api.example.com/search?q='search query' &mdash; This API does a search for an object and returns only identifiers and names of the objects. The result is a JSON array of objects. Each object has a ''title'' and an ''id'' properties.
 +
# http://api.example.com/get?id=123 &mdash; Receive the detail information of the object based on the id. The result is a JSON object.
 +
 
 +
Scipted data source can be as follows:
 +
[[insert code]]
 +
 
 +
== Step 3 &mdash; Settings for autofill rules ==
 +
After the script is written, it is necessary to map the arguments of the returned object to the fields of the library:
 +
# Close the script edit card and click +.
 +
# This will open the card for creation of autofill rules.
 +
# Point out the object property returned by the script.
 +
# Select the library field to receive the data.
 +
# Create rules for the remaining object properties.
 +
 
 +
== Example &mdash; Data source ==
 +
Let's consider service http://www.discogs.com/ &mdash; Provides information about music albums. This service has an API documented as http://www.discogs.com/developers.
 +
 
 +
The example of JavaScript library that provides request to this service are available in the script repository at github.com: [[insert URL]] This library can be connected using scripted data source editor:
 +
# Open scripted data source editor.
 +
# Click Add JavaAcript libraries.
 +
# Click on tab Repositories.
 +
# Select repository github.com/mementodatabase/script/data-sources.
 +
# Select discogs.js.
 +
 
 +
Script example of using this library:
 +
[[insert script]]
 +
 
 +
* Consumer key and consumer secret are the keys required to execute the request. They may be objained at http://discogs.com/settings/developers.
 +
* After the script is written, it is necessary to map the object properties to the fields of the library. Available object properties are documented in diskogs API. See an example of a response to a successful request at [[insert URL]].
 +
* If the search in the data source is done by barcode, use discogs.barcode(query) instead of discogs.search(query).

Navigation menu