Data Sources: Difference between revisions

From Memento Database Wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 8: Line 8:


== Lifecycle of an Autofill from a custom data source ==
== Lifecycle of an Autofill from a custom data source ==
# A user types text in a field in an Entry Edit card for use as a key to look up information.
# When adding an entry, the user types a search key into a field in the Entry Edit card.
# The entered text is passed to the custom data source script in the form of the global variable '''''query'''''.
# The data source script is then executed, with the search key passed in as the global variable '''''query'''''.
# The data source script is executed.
# The user is presented with a list of matching objects found by the script.
# The user is presented with a list of objects found by the script.
# The user chooses an object, and its properties are written to the mapped entry fields according to data load rules.
# The user selects an object, and its properties are written to the mapped entry fields according to data load rules.
# If the script has also returned a function, that script function is then called with the selected object's '''''id''''' property as an argument, and when the script function returns the object, now loaded with additional data, the object's new properties are loaded into mapped fields according to data load rules.
# If a function is returned as a result of the script, the script function is called with the selected object's id property as the argument, and the returned object's properties are loaded into mapped fields according to data load rules.


== Adding a custom data source ==
== Adding a custom data source ==

Revision as of 10:27, 5 March 2017

« Page as of 2017-03-05, editions Mobile 4.3.0, Desktop 1.1.0 »

The Autofill facility in Memento allows users to look up information from data sources on the Web, in Memento libraries, or from other data sources. Certain Web data sources are included by default in the Memento application for the convenience of users. For other lookups, a custom data source is needed.

A Custom Data Source is one in which a script acts as a source of data to fill fields with data from any service that has an API, from other libraries, or from other sources.

To add a custom data source for a library, edit the library, press the Autofill tab, and select Custom Source.

Lifecycle of an Autofill from a custom data source

  1. When adding an entry, the user types a search key into a field in the Entry Edit card.
  2. The data source script is then executed, with the search key passed in as the global variable query.
  3. The user is presented with a list of matching objects found by the script.
  4. The user chooses an object, and its properties are written to the mapped entry fields according to data load rules.
  5. If the script has also returned a function, that script function is then called with the selected object's id property as an argument, and when the script function returns the object, now loaded with additional data, the object's new properties are loaded into mapped fields according to data load rules.

Adding a custom data source

Step 1 — Adding a data source for autofill

  1. Open the Library Edit screen. Click on the Autofill tab, and then click +.
  2. Select the type of search — By Name or By Barcode.
  3. Select Custom source.
  4. Select the field to be used for data search within the source.
  5. You are presented with an Autofill Rules edit card. Select the field to use as the search key for the custom data source.

Step 2 — Script writing

The script is executed in the context of the library or entry, so it can use the same functions and objects as a trigger.
A script has the same security parameters as a trigger.
The result of the script should be returned as an array object.

Step 3 — Settings for autofill rules

After the script is written, it is necessary to map the properties of the returned object to the fields of the library:

  1. Close the script edit card and click +.
  2. This will open the card for creation of autofill rules.
  3. Identify the object property returned by the script.
  4. Select the library field to receive the data.
  5. Create rules for the remaining object properties.

Script Details

The API specific to data sources is as follows.

result(objects, getDetailsFunction)
Function to return the initial result of the script — an array of objects representing the search results and a function to be called for details.
Arguments
objects
List of objects which will be presented to the user for selection
getDetailsFunction
Optional argument — function to fetch detailed data. This function is called when one of the objects is selected.
Objects sent to the result function can have the following standard properties. When present, these properties will be displayed to the user for selection:
Properties
title
Name of the object
desc
Additional text shown under the name of the object
thumb
Reference to the image of the object
id
Object identifier. Used if the result() is called with a second argument.

Examples

Example — Filling data from another library

Say we have a library Organizations, and now we are building a new library that has organization information as a part of it. When we add an entry, we want to provide a search key and have the rest of the organization fields filled from the Organizations library. This is different from referencing the Organizations library, as with a Link to Entry field and Calculation or JavaScript fields; in the case of Autofill, the data is copied from the Organizations library as a separate copy.

So, we edit the new library, go to the Autofill tab, and press the + button to add an Autofill rule.

TBD

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:

  1. http://api.example.com/search?q='search query' — 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.
  2. http://api.example.com/get?id=123 — Receive the detail information of the object based on the id. The result is a JSON object.

Scripted data source can be as follows:

insert code

Example — Web data source

Let's consider service http://www.discogs.com/ — 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 is available in the script repository at github.com: insert URL. This library can be connected using the custom data source editor:

  1. Open custom data source editor.
  2. Click Add JavaScript libraries.
  3. Click on tab Repositories.
  4. Select repository github.com/mementodatabase/script/data-sources.
  5. 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 obtained 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).