Widget editor

The widget-editor is an easy to use React component to explore datasets and create customizable widgets. With it, you can create and edit charts (pie, scatter, bars, etc.) and simple maps.

The widget-editor produces widgets that are serialised as JSON objects, making it easy store and embed them.

The widget-editor is currently used in projects such as Resource Watch.

Table of content

• Installation
• Props
  • Notes on areaIntersection
  • Notes on schemes
• Adapter's customization

Installation

The widget-editor is composed of several parts, one of which being the adapter which interfaces with the source of data for the datasets. Below is the example of how to install the widget-editor in case you'd be using the Resource Watch API.

Please note it needs a React and Redux environment.

First, install the dependencies:

yarn add @widget-editor/widget-editor @widget-editor/rw-adapter

Then hook the editor to your Redux setup:

import { createStore, combineReducers, applyMiddleware } from 'redux';
import { reducers, middleware, sagas } from '@widget-editor/widget-editor';

const initStore = (initialState = {}) => {
  const appReducers = combineReducers({
    ...reducers,
  });

  const store = createStore(appReducers, initialState, applyMiddleware(middleware));

  middleware.run(sagas);

  return { store };
};

export default initStore;

Finally, render the widget-editor:

import WidgetEditor from '@widget-editor/widget-editor';
import RwAdapter from '@widget-editor/rw-adapter';

const App = () => <WidgetEditor adapter={RwAdapter} datasetId="XXX" />;

export default App;

Props

Below is the list of props the WidgetEditor component accepts:

Name	Mandatory	Default value	Description
adapter: Adapter	Yes	−	The adapter is an essential part of the widget-editor which handles all the external data.
datasetId: string	Yes	−	The ID of the dataset that will be used in the editor.
widgetId: string	No	−	The ID of the widget that will be restored. The editor won't overwrite this widget when saved unless the host app decided to do so. If not provided, no default visualization will be shown.
areaIntersection: string	No	−	The ID of an area used as a default geographic filter (see notes below).
schemes: Scheme[]	No	Resource Watch	Color schemes available for use in the editor (see notes below).
onSave: (payload: OutputPayload) => void	No	−	Callback executed when the user clicks the save button. If not provided, the save button isn't displayed.
disable: string[]	No	['typography', 'end-user-filters']	Features to disable from the following list: geo-filter, end-user-filters, theme-selection, typography, advanced-editor and table-view. If a widget uses one of them, its rendering won't be affecting.
compact: boolean	No	false	In compact mode, the settings panel of the editor is displayed as a popup window on top of the visualization view. This mode is useful for narrow layouts.

Notes on areaIntersection

If the editor is restoring a widget that already has a geographic filter, and areaIntersection is set, the geographic filter will be overwritten by the value of areaIntersection. The user will still be able to change the filter's value in the UI.

If the areaIntersection prop is later removed, the widget-editor will remove the geographic filter instead of restoring the widget's original filter value.

If the areaIntersection is a user's area, the widget-editor's adapter must be correctly configured so that it can load this private area. If not, it will be show as “Custom area”. In the case of the Resource Watch's adapter, the userToken properties must be set. Read more about it in its customization section.

If the dataset doesn't provide geographic information, this property is ignored.

Notes on schemes

Color schemes are sets of colors applied to the charts. Each color scheme must have a unique name.

With the schemes prop, the host app may decide to provide a list of its own color schemes so that the user can choose between them. Nevertheless, the user is able to customize any scheme to their liking. If this is the case, a new scheme called “Custom” will be created (its internal name will be user-custom).

It is important to note that the schemes are embedded in the widgets so they can be displayed as intended in the Renderer.

Below are the rules the editor follows to determine which scheme to use by default:

1. If it is instantiated without any widget or with a widget that doesn't have an emdedded scheme, the default scheme is the first one provided to the schemes prop or the “Resource Watch” one if the host app doesn't provide any.
2. If the editor is instantiated with a widget that has an embedded scheme supported by the host app (i.e. its name can be found in the list passed to the schemes prop), then it will be the scheme used to display the widget.
3. If the editor is instantiated with a widget that has an embedded scheme that isn't supported by the host app or a scheme called user-custom, then this scheme will be used to display the widget, and it will be called “Custom” in the UI, independently from its real name.

Adapter's customization

Some adapters like Resource Watch's one contain environment variables such as the API's endpoint or the user's token used to retrieve their custom areas.

In order to overwrite them easily, the widget-editor provides a helper, AdapterModifier, that can be use to extend any existing adapter. Here's an example of how to use it:

import WidgetEditor, { AdapterModifier } from '@widget-editor/widget-editor';
import Adapter from 'somewhere';

// Here you can overwrite environment variables. Note that the adapter is free to restrict which variables can be modified.
const customProperties = {
  endpoint: 'https://another-api.com',
  token: 'Bearer XXX',
};

// It's better to create the adapter outside of the render function so it is stable
const CustomAdapter = AdapterModifier(Adapter, customProperties);

const App = () => <WidgetEditor adapter={CustomAdapter} datasetId="XXX" />;

export default App;

If you're looking at how to extend the Resource Watch adapter, please have a look at its dedicated page.