Upgrading to 2.2.0

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

Upgrade data repository to sdg-build 2.2.0¶

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

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

Upgrade translations to sdg-translations 2.2.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.2.0

Update version of Open SDG to 2.2.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.2.0

Update version of jekyll-open-sdg-plugins to 2.2.0¶

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

gem "jekyll-open-sdg-plugins", "2.2.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.

• _includes/assets/js/indicatorInit.js
• _includes/assets/js/indicatorModel.js
• _includes/assets/js/indicatorView.js
• _includes/assets/js/mapView.js
• _includes/assets/js/plugins/jquery.sdgMap.js
• _includes/assets/js/plugins/leaflet.disaggregationControls.js
• _includes/assets/js/view/chartHelpers.js
• _includes/assets/js/view/constants.js
• _includes/assets/js/view/helpers.js
• _includes/assets/js/view/seriesHelpers.js
• _includes/assets/js/view/tableHelpers.js
• _includes/components/charts/chart.html
• _includes/components/goal/goal-content.html
• _includes/components/goal/header.html
• _includes/components/indicator/indicator-main.html
• _includes/components/indicator/series-template.html
• _includes/components/reportingstatus/reporting-status-label.html
• _includes/components/reportingstatus/reporting-status-overall.html
• _includes/head.html
• _includes/javascript-variables.html
• _includes/polyfills.html
• _includes/title-tag.html
• _layouts/data-editor.html
• _layouts/indicator.html
• _layouts/reportingstatus.html

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.

progressive_web_app¶

Open SDG now has the functionality to make the platform into a web app which users can add to their mobile device's home screen and use while offline. To enable this, you will need to edit your config file. Once enabled the web app can be installed to a user’s mobile device by visiting the settings while visiting the platform on a browser app.

To enable this, edit your config file to include the field below

progressive_web_app: 
  enabled: true 
  name: My SDG App Name 
  short_name: SDG App 
  precaching: true 

The "precaching" is what is meant to allow the site to be viewed even while offline.

Proxy¶

When the indicator data provided is alternative to that specified by the UN, Open SDG now has the functionality to mark it as “proxy” data with a label and definition.

To set an entire indicator to be a "proxy", this line is needed in each indicator configuration file in the metadata section on indicator pages:

proxy: proxy

If your data has multiple series and not all of them are proxies, this is needed instead, to define which series are proxies (for example):

proxy: both
proxy_series:
  - my first proxy series
  - my other proxy series

To change the text that appears for the proxy description as default, add this to the site_config.yml file in your site repository to customise the description text. Note: you will need to update the translation for this if you use any other languages on the site.

proxy_indicators:
  label: Proxy
  description: My alternate proxy description

Search Engine Optimization (SEO) Customisation Options¶

There are a number of SEO additions to this update including:

• Meta Tags
• Goal Page H1s & H2s

Meta Tags

Title tags and meta descriptions are two important elements of SEO. Title tags are the clickable headlines that appear in search engine results pages (SERP), while meta descriptions are brief summaries of the page's content. Both title tags and meta descriptions can help improve your website's click-through rate (CTR), which is the percentage of people who see your listing in the SERPs and click on it.

This setting can be used to set meta tags on any of the paths within the site. It should contain a list of items, each containing a path, a name, and content.

meta_tags:
  - path: about
    name: description
    content: My description text for the About page
  - path: '1'
    name: keywords
    content: my list of keywords for Goal 1

Goal Page H1s & H2s

H1 and H2 tags are HTML elements that are used to define headings in a web page. H1 tags are the most important headings, followed by H2 tags. Heading tags are important for SEO because they help search engines understand the structure of your content and the topics that you are writing about. They also help users scan your content to find the information they are looking for.

Text entered here will appear as an H1 heading at the top of the goal page. This is optional and overrides the default (e.g. 'Goal 1: No Poverty'). This is useful for SEO purposes, and can be plain text or a translation key.

Example code for Goal 6 heading being the H1 and content_heading being the H2

    - goal: 6
      heading: Goal 6 - Clean Water and Sanitation
      content_heading: Ensure availability and sustainable management of water and sanitation for all

colorRange function support and easier overrides¶

The maps in Open SDG are "choropleth" maps, where each region is given a color according to its numeric value. The range of colors that will be used is controlled in the colorRange parameter in the map_options site configuration. The value of this option is now much more flexible: it can refer to a JavaScript variable or a JavaScript function. This allows for very granular control of the map colors, in a dynamic way.

However if you are interested in use one set of map colors for every map on your site, the easiest way to accomplish this is to override this file: _includes/assets/js/mapColors.json.

Note: while these colours can be changed, this may affect the accessibility of the maps, particularly for the visually impaired, so this should be done with caution.

For more details about using colorRange to control the map colors, see the map documentation.

Bug-fixes and improvements¶

• A broken reference to one of the map dependencies ("nezasa") is fixed in this release
• The reporting status overall row now shows the SDG wheel, so that it lines up visually with the other rows
• The built-in data edit functionality ("Edit data") has been fixed after a dependency updated
• The range of years on maps now correctly updates for each disaggregation
• The indicator configuration data_start_values now works for maps
• When a chart image is downloaded, it now downloads as double the size
• The reporting status "label" option in the site configuration is now correctly used