Upgrading to 2.3.0

This document is intended for developers, to help with the process of upgrading to version 2.3.0 of Open SDG, from 2.2.0 or higher.

Upgrade data repository to sdg-build 2.3.1

In your data repository, update your requirements.txt file to:

git+https://github.com/open-sdg/sdg-build@2.3.1

Note: A hotfix was implemented in April 2024 so for this file, sdg-build should point to 2.3.1, not 2.3.0.

Upgrade translations to sdg-translations 2.3.0

In your data repository's config file, update the version of sdg-translations in the "translations" section:

translations:
  - class: TranslationInputSdgTranslations
    source: https://github.com/open-sdg/sdg-translations.git
    tag: 2.3.0

Update version of Open SDG to 2.3.0

In your site repository's _config.yml file, update the version of Open SDG in remote_theme, like so:

remote_theme: open-sdg/open-sdg@2.3.0

Update version of jekyll-open-sdg-plugins to 2.3.0

In your site repository's Gemfile, update the version of jekyll-open-sdg-plugins like so:

gem "jekyll-open-sdg-plugins", "2.3.0"

Updating overridden files

If you are overriding certain files, you may need to adjust your version in order to benefit from the latest features, bugfixes, and design changes. If you are unsure, check the _includes and _layouts folders in your site repository. If they contain any of the following files, you may want to incorporate the latest changes into your overrides. The links below will show you the latest changes for each file.

Note that we strive to avoid any breaking changes, so this process of updating overridden files is optional. However we strongly recommend keeping your overridden files as current as possible.

New features

This release introduces some optional features that you may be interested in adding to your platform.

Indicator iframes

This feature allows you to create iframe-friendly versions of each indicator. An iframe is an HTML element that loads another HTML page within the same page. It essentially puts another webpage within the parent page.

The URLs of the iframe-friendly versions will be the same link but with "-iframe" at the end e.g. "/1-1-1" & "/1-1-1-iframe". An example of how to embed this into a new page is shown below:

---
title: My page
permalink: /my-page/
layout: page
---
Indicator 1.1.1 should be embedded below:

<script type="text/javascript" src="https://pym.nprapps.org/pym.v1.min.js"></script>
<div id="my-iframe-container"></div>
<script>
    var pymParent = new pym.Parent('my-iframe-container', '{{ site.baseurl }}/1-1-1-iframe', {});
</script>

It is also possible to do an iframe directly, however you would lose out on the benefit of the Pym.js library, which is supposed to prevent vertical scrollbars. If you wanted to do this, it would be something like this:

---
title: My page
permalink: /my-page/
layout: page
---
Indicator 1.1.1 should be embedded below:

<iframe src="{{ site.baseurl }}/1-1-1-iframe"></iframe>

observation_attributes

Open SDG now has the functionality to display observation attributes for indicator data in charts, tables and maps. This setting controls the data columns that should be considered "observation attributes", as well as the labels that should be used for these columns when displaying their values in the footer beneath charts and tables.

There are two steps to displaying observation attributes in your data:

  1. Add the relevant information into your data - this is achieved by adding a COMMENT_OBS column to the indicator data file which is filled in with wording (e.g. Estimated value, Forecast value etc.) for those lines of data that are observation attributes.

  2. Include the observation_attribute setting in your site configuration - add the following lines to the site_config.yml in the site repository: 

observation_attributes: 
  - field: COMMENT_OBS 
    label: ''

The default is to display ‘note 1(2,3 etc.)’ after each data point in the tooltips of the chart, table and graph, that is an observation attribute. The number of the note corresponds to a type of observation attribute entered into the COMMENT_OBS column as outlined below: 

[note 1] Estimated value 
[note 2] Forecast value 
[note 3] Unvalidated value 
[note 4] Low reliability 
[note 5] Experimental value 
[note 6] Imputed value

You can change the label in the setting to say something other than the default ‘note’ as desired too.

Reporting status page - Option to remove "out of scope" disaggregations

Open SDG users will now have the option to show or remove the "Out of Scope" tag on their Reporting Status page in the Disaggregation status. This can now be used to only show indicators where a disaggregation is explicitly mentioned in the indicator title. This will hide the out of scope indicators from the bar on the screen. This should hopefully better represent how many indicators are disaggregated.

To omit "out of scope" from the disaggregation status page, in the data config file, set ignore_out_of_scope_disaggregation_stats to true.

ignore_out_of_scope_disaggregation_stats: true

To change the label of the totals in the disaggregation status page, in the site configuration file (eg, _data/site_config.yml), in the reporting_status section add a disaggregation_indicator_count_label to the reporting_status section. The default is "indicators", so for example you might want to use "indicators in scope".

reporting_status:
    disaggregation_indicator_count_label: indicators in scope

use_new_config_forms

New and improved site configuration forms have been developed to make changes to your site as user friendly as possible. The original forms are still available if you do not change the setting as indicated below and you still access the forms in the same way.

As usual, there are two ways of updating to your site_config.yml file in order to make configuration changes to your site:

  • You can edit the _data/site_config.yml file directly, or
  • You can use the site configuration forms via your staging site.

You can use either method at any time for any change.

To turn on the new site configuration forms:

  1. Go to the site_config.yml file in the _data folder in your site repository.
  2. Include this line: 
use_new_config_forms: true

You can then access the site configuration forms by going to your staging site and in the footer menu at the bottom of any page, click "Configuration".

From here you can navigate around the forms depending on what setting you would like to change. Every setting has its own section which may consist of checkboxes, text boxes, drop-downs, toggles and list items. You can interact with each of them to update any settings from the default. There is more information provided to give context and guidance for each setting which can be accessed by clicking on the drop-down at the bottom of each setting.

See the site configuration forms guidance page for more information.

Ruby 3

The Open SDG platform now supports Ruby 3, and if you would like to upgrade here are the instructions. Note that this is not required, but if you would like to be on the latest version then it is now possible. To upgrade to Ruby 3, you will need to make changes in your site repository:

  • Changes to your "Gemfile"
  • Changes to the "workflows" in the .github folder

Here is an illustration of the specific changes needed: https://github.com/open-sdg/open-sdg-site-starter/pull/98/files

Bug-fixes and improvements

  • Fixed an issue where maps were not displaying for some indicators
  • Fixed an issue where some series were not appearing
  • Country name now translated in table header
  • Header columns now pinned in tables
  • Added units and series columns to data download files
  • Improvements to checkbox selection on indicator pages
  • data_start_values on maps: geographical fields now ignored
  • Graph annotation label position functionality improved
  • Improvements to screenreader and voice control functionality
  • Allowed DataSchemaInputSdmxDsd as a data schema