Widgets and data.fao.org
A client application usually needs to represent and manage data coming from one or more sources, combining them in a homogeneous interface that should be intuitive and easy to use.
When data sources are distributed in a complex architecture, it is useful to have tools and features that allow developers to easily create applications holding all the data in a fully customizable graphical arrangement. This is the entry point for the concept of a widget.
What is a widget?
Technically, widgets are reusable visual elements that, when correctly configured and combined in an application, allow creating user interfaces that work with data of different types and come from different sources, guaranteeing a high level of integration and flexibility.
The data.fao.org library
At this point of data.fao.org development, the library contains the following groups of widgets:
- Localization widgets - language selector, management of text and images that need to be localized.
- Data widgets - single controls or a group of multiple controls that get data from data.fao.org statistical data through Process APIs (referenced in a previous blog article).
- Digital assets widgets - documents, images, audio and videos that come from data.fao.org digital assets.
- Geospatial widgets - components that allow displaying and browsing of maps or extracting data from them. The main widget of this group is the Map Browser component that allows interactive visualization of one or more maps that come from different map servers, enriching them through styles and simple or complex markers.
The library contains visual and non-visual widgets. Non-visual widgets are used by the visual ones to perform additional operations. All of the widgets, visual and non-visual, can be combined together to form more complex widgets.
The most important thing to know is that each visual widget of the library (with the exception of the DataMapper, mentioned later) works with an HTML root element. The coupling between the widget instance and its root element is done through the corresponding ID. After the instantiation, a widget is built starting from the root element and with a visual structure depending on its type. If the root element does not exist inside the HTML document, it will be dynamically created inside the Document Object Model. This allows developers to choose between two approaches:
To develop an application using the widgets library, it is necessary to include the following line in the customized HTML page:
A widget example
To easily understand what that possibilities are for this library, we can discuss an example that summarizes more or less all of the concepts we implemented.
Let’s imagine that we have a map of the world with all the country boundaries highlighted. It would be nice to open an information summary related to a specific country, for example, the country flag, a generic country picture, or a list of codes that identify it. Technically, to do this we need a clickable map of the world and the possibility to extract data, pictures, and flags from data.fao.org resources through information that identifies the country that was chosen. In this particular situation we can identify countries with the ISO3 code.
How can we do this? First of all, we instantiate the widget JSMapComponent and add a couple of geolayers to it in order to have a good visible representation of the whole world with all of the countries included. To be able to extract information from a map server, we need to add a layer to the map component based on a data store, for example, a shape file or a PostGIS layer. This type of layer brings with it a set of data for each geographical location. By enabling map queries on the map component, we will be able to obtain the ISO3 code of the selected country after the user clicks on a specific map location.
With the ISO3 code we are able to extract the following information from data.fao.org resources:
- Country flag
- Country picture
- Country codes
Representing geographic information
To represent the first two digital assets, which are pictures, we can use the AssetImage widget. This type of widget works with an img root element and sets the src attribute, depending on a set of attributes necessary to uniquely reference the asset. To reference an asset, the following parameter should be provided to the widget:
<database name>:<asset type>:<asset dimension>:<asset name>
In this example the asset name corresponds to the ISO3 code, so it is easy to extract both the flag and the picture.
To represent country codes in a totally customizable graphical view, we use the DataMapper widget. This type of widget works on a set of HTML span elements, each one with its own ID. It extracts the information to represent statistical data from data.fao.org. It runs a specific query and maps the result object on the span elements through a mapping configuration object provided by the user. To reference the query that you want to run, it is necessary to provide the query identifier, composed as the following:
<database name>:<query name>
The query used in this example requires an ISO3 code as the parameter to extract codes for a country, therefore, it is necessary to provide it to the widget.
After we click on a map location, a marker displays that combines the three previously mentioned widgets, graphically organizing them in a customized view. The following is the result of our example:
This example shows only some of the widgets available in the library, however, it gives a good idea about integration flexibility and capabilities.
To obtain more detailed information about all of the widgets currently available, see the documentation at the following link: http://data.fao.org/widgets/.
Author: Francesca Vigetti