A wrapper for the OECD data explorer. The plugin embeds a react application in the page and allows the interaction between the static PHP page and the React app.
The Data Explorer plugin for Wordpress and Drupal is made of three main parts:
The Data Explorer is a React application, it is responsible of showing the interface to the user, react to the inputs, retrieve data from the SDMX registry and presenting the results to the user.
The Wordpress plugin makes easier to embed the Data Explorer in a CMS page. The plugin creates a few menus in the Wordpress administrative area. After a few configuration steps it is possible to embed a Data Explorer in the pages.
Many parts of the Data Explorer are configurable (e.g. the rounding rules, how to sort the time dimension, the starting dataflow …). The configurations are contained in .json files that must be hosted on a web server.
The project is hosted in two Github repositories, both repositories must be downloaded to install the plugin.
Download or clone the contents of the first repository:
https://github.com/unicef-drp/wp_dotstat_data_explorer_cfg
This repository contains the Data Explorer application and all the configuration files.
Create a configuration file (you can copy one of the existing files in the "configs" folder as a starting point).
We’ll only change the endpoints for the SDMX registry and the starting dataflow for now, a complete description of the configuration file is available in another section of the document.
Change the URL to the Fusion SDMX registry in "SETTINGS_override.fusion.url"
Change the starting dataflow (must be an existing dataflow in your registry). In "DATAFLOW" change the following values:
- agencyId: the dataflow's agency id
- dataflowId: the dataflow's id
- version: the dataflow's version
- dataquery: the initial dataquery as specified in the sdmx standard
- period: the starting and ending year
It is a good idea to test the parameters using the SDMX registry to be sure to query an existing dataflow with the right parameters and avoid the Data Explorer showing the "no data" error.
The files must be available through simple HTTP calls, make sure that the files are reachable.
You can try to point the browser to the configuration files, the javascripts and the css to check if everything is reachable. The files could also be published on the Wordpress server itself, it could be necessary to change the configuration of .htaccess file.
E.g. if the URL containing your file is available at:
https://your_server.org/wp-content/plugins/wp_dotstat_data_explorer_cfg you can try to load one of the configuration files and see if it shows on your browser (point your browser to https://your_server.org/wp-content/plugins/wp_dotstat_data_explorer_cfg/configs/GLOBAL_DATAFLOW.json)
Download or clone the contents of the second repository:
https://github.com/unicef-drp/wp_dotstat_data_explorer
The repository contains the Wordpress plugin, the files must be copied in the Wordpress' plugins directory (typically wp-content\plugins).
Open the Wordpress admin page, open the "Plugins" menu.
The "Data Explorer" plugin should appear in the list of plugins, click on "Activate"
After the activation the "Data Explorers" menu item should appear, the plugin also adds an item in the "Settings" menu.
Open the "Settings" menu and click on "Data Explorer"
In the "Remote files URL" field paste the URL to the files hosted on the web server, in our previous example the URL to paste was https://your_server.org/wp-content/plugins/wp_dotstat_data_explorer_cfg
Now that our plugin is added and configured to point to the right server, you can add a Data Explorer page
Open the Wordpress admin page, click on "Data Explorers" and "Add new".
Add a title for the page in the top field.
Paste the name of the configuration file that you created during the "Create a configuration file" step without the .json extension (the name of the file is the configuration ID).
E.g. if you created a UNICEF.json file then the configuration id is "UNICEF"
After the configuration in saved in the Wordpress admin the permalink should be available. Pointing your browser to the Data Explorer page just created should show the Data Explorer with some data.
The configuration repository contains 5 folders
- configs: contains the configuration Json that will be used by the Data Explorer to configure its behavior
- css: contains the css files that can be used to override some parts of the style embedded in the Data Explorer
- de:contains the built and minified React application (the contents should not be changed)
- js: contains some additional startup or utility scripts (the contents should not be changed)
- maps: this folder can contain maps in geoJSON format
The configuration file is pointed by the Data Explorer page and controls some aspects of the application appearance and behavior.
The following list describes the fields
- origin: The URL of the Data Explorer
- SETTINGS_override.{registry_id}.url: The url to the registry. The registry_id value is arbitrary and can be assigned to identify a specific registry
- unicef_settings.indicatorProfileUrl: It will show an icon next to the Indicators if it contains a link to an "indicator profiles" page (a page providing information on the indicator). Clicking on the icon will open the Indicator profiles page. No icon is shown if the field is empty
- unicef_settings.hideTotalLabel: If the value is 1 any cell containing the value "Total" (SDMX code = _T) does not show the Total label. If the value is 0 all the Total (SDMX code = _T) are shown
- unicef_settings.roundData: The number of decimal digits to round to (0=no rounding)
- unicef_settings.showDataflowNavigator: Used by UNICEF to allow the navigation between Dataflows, should be set to 0
- unicef_settings. stickyDims: Used by UNICEF to allow the navigation between Dataflows, should be set to []
- unicef_settings.dataflowsOnEvidence: Used by UNICEF to allow the navigation between Dataflows, should be set to []
- map_settings: This section allows to define maps that will be shown in the data explorer. Each map is attached to a specific dataflow. The dataflow is the object’s key (e.g. map_settings.UNICEF:NUTRITION means that the map is attached to the dataflow having agency=UNICEF and id=NUTRITION
- map_settings.{AGENCY_ID:DATAFLOW_ID}.ref_area_dim_id: It must contain the id of the dimension containing the geographic areas. (usually REF_AREA)
- map_settings.{AGENCY_ID:DATAFLOW_ID}.geojson_url: The url to the maps folder
- map_settings.{AGENCY_ID:DATAFLOW_ID}.areas: A list of area codes to automatically select when entering the map view. This field solves the problem of entering the map view with a subset of areas selected or no areas at all. An example could be the list of European country codes if we want to show the map of Europe
- DATAFLOW: This section defines the first Dataflow to show when the Data Explorer is loaded by the user
- DATAFLOW.datasourceId: Must match the registry_id assigned in the SETTINGS_override.{registry_id}.
- DATAFLOW.agencyId: The id of the SDMX agency assigned to the dataflow
- DATAFLOW.dataflowId: The id of the dataflow
- DATAFLOW.version: The version of the dataflow
- DATAFLOW.dataquery: The data query expressed in SDMX format, it is used to limit the number of datapoints loaded and can help reducing the loading time. Each dimension is separated by a ".". The codes for each diemsnion are separated by a "+" symbol. Please refer to the SDMX documentation to have additional information
- DATAFLOW.period: Contains the start year and end year (e.g.[2010, 2021]
- DATAFLOW.backendId: The type of SDMX registry (FUSION or EUROSTAT)
- helpUrl: Can contain a link to a help page. A help icon will appear if this field is defined. Clicking on the icon will open the Help page. No help icon will appear if the field is empty
- timeDimensionOrder: asc: for asending, desc: for descending
The plugin can be easily translated to work in a Drupal CMS, UNICEF tested the solution successfully but maintaining the Drupal version is not in the plans for now.