Think pie, bar, scatter or line charts. Like all widgets, the display of chart widgets is rendered with the widgetConfig property.

The standard approach for building widget configuration objects uses Vega grammar. The RW API does not apply any restriction to the data saved in the widget configuration field (widgetConfig). This allows for a very high level of flexibility but has the downside of making it harder to document how to use widgets. It is recommended that you take a look at the API documentation section about Widget configuration using vega grammar as well as the Vega documention.

The widgetConfig is a JSON specification that controls the rendering of a widget. It is usually written using a Vega Specification Creating a widgetConfig is a free-form process. It is easiest to start with an existing widgetConfig instead of creating one from sratch.

There are several sources of example widget configs.

1. From an Ocean Watch chart widget: To get the widget config of an existing widget, get the widget alpha-numeric API ID. You can get the widget ID from the catalog/tracking sheet mentioned above. You can also click on the share button on the widget on the OW page to generate a shareable link. Copy and paste the bit.ly link into your browser to reveal the widget ID in the URL. You can get the body of a widget (including the widgetConfig) by querying the RW API at

https://api.resourcewatch.org/v1/widget/<widget_id>

Note: We recomened installing a JSONson viewer like this one, so you can easily view and copy components of a JSON file. Use a JSON formatter like this one to keep the parsed formatting of the the widgetConfig

2. From a Vega example: Vega has tons of examples of JSON specifications that can be used as widgetConfigs. Click on the one you like, and copy the specification or open it in the "Online Vega Editor."

3. From the Widget Editor: The Widget Editor was created by Vizzuality to explore datasets and create customizable widgets. All of the documentation is stored inside the widget-editor wiki. You can use the default dataset to create a widget that closely matches your intended vizualization. Then switch to "Advanced" mode to see the Vega JSON specification.

The Online Vega Editor is a great tool to test your specification. In the pane in the lower right you can access error logs, a data viewer, and a signal viewer. These features make the Vega editor a great tool for developing and debugging your widgetConfig. The Widget Editor on Resource Watch has default config properties to match charts to the Resource Watch "styling". These defaults are different than those of the Vega Editor. To change the default configuration, copy and paste this specification into the CONFIG tab in the upper left.

{
  "range": {
    "dotSize": [20, 250],
    "category20": [
      "#3BB2D0",
      "#2C75B0",
      "#FAB72E",
      "#EF4848",
      "#65B60D",
      "#C32D7B",
      "#F577B9",
      "#5FD2B8",
      "#F1800F",
      "#9F1C00",
      "#A5E9E3",
      "#B9D765",
      "#393F44",
      "#CACCD0",
      "#717171"
    ],
    "ordinal": { "scheme": "greens" },
    "ramp": { "scheme": "purples" }
  },
  "axis": {
    "labelFontSize": 13,
    "labelFont": "Lato",
    "labelColor": "#717171",
    "labelPadding": 10,
    "ticks": true,
    "tickSize": 8,
    "tickColor": "#A9ABAD",
    "tickOpacity": 0.5,
    "tickExtra": false
  },
  "axisX": {
    "bandPosition": 0.5,
    "domainWidth": 1.2,
    "domainColor": "#A9ABAD",
    "labelAlign": "center",
    "labelBaseline": "top"
  },
  "axisY": {
    "domain": false,
    "labelAlign": "left",
    "labelBaseline": "bottom",
    "tickOpacity": 0.5,
    "grid": true,
    "ticks": false,
    "gridColor": "#A9ABAD",
    "gridOpacity": 0.5
  },
  "mark": {
    "fill": "#3BB2D0"
  },
  "symbol": {
    "fill": "#3BB2D0",
    "stroke": "#fff"
  },
  "rect": {
    "fill": "#3BB2D0"
  },
  "line": {
    "interpolate": "linear",
    "stroke": "#3BB2D0",
    "fillOpacity": 0
  }
}

A note on fonts: The Resource Watch Widget Editor uses the default font "Lato". This font renders differently (and very unappealingly) in the Vega Editor. Don't worry -- you will see it looks much better in the Widget Editor. Its recommended to use the "Lato" font to maintain consistent styling. The Widget Editor only specifies "Lato" as default in the ["axis"]["labelFont"]. It is recommended to manually set all text to "Lato". This includes ["axes"]["titleFont"], ["legends"]["titleFont"], ["legends"]["labelFont"].

Once you have copied an existing specification and the CONFIG into the Vega Editor, you can adjust the specification to read and render the new data.

You can paste the existing specification into the VEGA tab and edit it directly (once you change the data, this will produce lots of errors until all column and variable names are fixed), or you can build the new specification from scratch, using the existing specification as a guide.

To pull in the new data, you will need to edit the data properies. Load the dataset using the url property. We use a call to the Carto's SQL API. It is helpful to at least partially transform the data with your SELECT statement. Here's and example:

[
  {
    "name": "effort_table",
    "url": "https://wri-rw.carto.com/api/v2/sql?q=SELECT year, SUM(value::NUMERIC) AS effort FROM com_030d_fishing_effort_by_zone AS data WHERE year <= 2021 AND year >= 2017 GROUP BY year ORDER BY year ASC",
    "format": {
      "type": "json",
      "property": "rows"
    },
    "transform": [...]
  }
]

To pull data for the correct page, Ocean Watch widgets are "parameterized." This means there is a placeholder in the url for the API call. Please refer to the Geostore and Parameterized Queries section for information on how to parameterize queries. It is recommended to build the specification using a url that loads data for a specific geostore identifier. Test the specification with a multiple different identifiers. Once you have finalized the specification and are ready to create the widget on Resource Watch, swap in the {{geostore_env}} and {{geostore_id}} placeholders.

After loading the data, you can inspect it in the Data Viewer tab. Perform any additional transformations using the transform property. Now you are ready to add or edit the rest of the properties including scales, axes, marks, legends, and singals.

A note on tooltips: While the Resource Watch Widget Editor can display the Vega tooltip it renders rather poorly. It is recommended to use the custom Widget Editor tooltip to match the Resource Watch styling. Unfortunately this custom portion of the specification cannot be tested in the Vega Editor. It is recommended to use the Vega tooltip while developing and convert to the Widget Editor tooltip in the final stage of development (see below)

The Vega Editor allows you to share a rendering of your configuration. This can be useful for getting feedback on versions as you develop.

Once you have your widgetConfig, you are ready to test and refine in the Widget Editor. Switch to "Advanced" mode, and copy and paste your specification. This will render the widgetConfig as it will appear on Resource Watch (if you encounter any differences, it may be because the version of vega used on Resource Watch is slightly behind the Widget Editor). It is recommended to change the tooltip to the Widget Editor custom tooltip and remove the Vega tooltip parameter (see above note). At this point, you can also remove the width and height properties, as those will get overwritten. If you are creating a parameterized widget, the final step will be to swap in the {{geostore_env}} and {{geostore_id}} placeholders in url in the data property. Once you add the placeholders, the data cannot load and the specification will no longer render.