Skip to content

Adapters

Jump to bottom
Clément Prod'homme edited this page Feb 15, 2021 · 3 revisions

Adapters have a central place in the widget-editor: they are in charge of all the data flow with the external storage where the datasets, widgets and layers lie.

The widget-editor has been engineered in a way so that the core and applications are agnostic to the data handling. It's the adapters' responsibility to retrieve and provide data in the format that is expected. This also means that the widget-editor could potentially work with any source of data, provided that they are compatible with a few requirements.

Table of content

Requirements

Though the other parts of the widget-editor don't know anything about the adapters' implementation, the editor has been built with the Resource Watch API in mind. This means it will be easier to create another adapter if the data structure is similar.

The entities the editor manages are:

  • Datasets that own metadata about the fields and information about the SQL table
  • Fields that correspond to the SQL table's columns and that can have aliases and descriptions
  • Layers that follow closely the Resource Watch's specification
  • Widgets that are attached to a single dataset
  • Areas that are shapes that can be used as filters

In addition and as you might have guessed, the actual data used to build charts needs to be stored in a database that supports SQL queries. The widget-editor's queries are built on the filters and settings set by the user, and are sent right through the adapter. The adapter must support SQL features such as aliases, aggregation functions, and filtering/sorting temporal data.

Moreover, the database must have geographical capabilities to intersect data points with geometries. The editor does not use geographical functions in the SQL queries, but it may send a geostore parameter with the ID of the area the user wants to filter with. It's up to the adapter to compute the intersection and return the correct data.

Finally, and even if the adapter does not make any request to an external server, it needs to implement a function called abortRequests. When executed, the adapter should stop immediately any pending or asynchronous task. The editor may use it in situation where it is reset.

Minimal implementation

Every adapter should extend the public adapter interface. If you open the file, you will see all the methods that need to be implemented, as well as a description for each of them.

If you want to see an example of implementation, head over to the Resource Watch Adapter's code.

Customization in the host app

The adapter may contain hard-coded variables such as an endpoint where the requests to get datasets are made, or a variable that contains the user's token necessary to retrieve their custom areas (for the getUserAreas method).

When a developer integrates the widget-editor in their host app, they may want to overwrite those variables with specific values. In that case, the adapter's extendProperties method will be executed. The developer won't have to call it manually though. Instead, they will use the AdapterModifier helper provided by the @widget-editor/widget-editor package. See the Adapter's customization section of the widget-editor page to get more information.

Clone this wiki locally