Adding or Updating Visualizations on HDX

Current HDX path for visualizations: https://data.humdata.org/visualization/viz-<name-of-visualization>

Adding new visualizations

All visualizations that are ready to go to production (and eventually embedded into ckan pages) will follow these steps:

1. Work on a personal github repo until ready for production

2. Import or fork your github repo into OCHA-DAP organisation github account; the name of the repo must be identical to the path you want to be visible under and prefixed with "viz-", for example if you want to be displayed as data.humdata.org/visualization/very-cool-viz, you need to import it as github.com/OCHA-DAP/viz-very-cool-viz

3. Setup or ask Serban to setup the github pages on the repo by displaying the content of branch "gh-pages"

Updating visualizations

1. Work on dev branch in OCHA-DAP visualization repo. Test locally until you think all looks good.

2. Create a pull request from dev branch to gh-pages branch and ask a review from another person (data team, dev team, ops team).

3. When the merge is complete, the visualization will be updated on production.

Verify your work in production

1. Test if the visualization looks good at https://ocha-dap.github.io/viz-very-cool-viz.

2. It is likely that you would have to solve the CORS headers issue (make sure the viz is visible directly at github pages above AND at humdata.org embedded page and at the current visualization path.

How to use the visualization

Always make sure you use https://data.humdata.org/visualization/very-cool-viz and not https://ocha-dap.github.io/viz-very-cool-viz (for obvious SEO reasons).

Vue.js visualizations

For visualizations created using Vue.js (more precisely Nuxt) we need to take into account some guidelines and make sure we include specific settings to make them work as shown above (storing the project on GitHub pages, having a project with multiple pages, relative links and avoiding adding NGINX exceptions).

Sample project with patches applied: https://github.com/OCHA-DAP/viz-vuejs-testing-dashboard.

1. Open the root nuxt.config.js file and add the following settings:

   const withSubfolder = process.env.DEPLOY_ENV === 'WITH_SUBFOLDER' export default { [...], target: 'static', ssr: !withSubfolder, build: { publicPath: withSubfolder ? './' : '/_nuxt/', extend (config, ctx) { config.output.publicPath = withSubfolder ? './' : config.output.publicPath } }, router: { base: withSubfolder ? '.' : '/', mode: 'hash' }, [...] }

2. Inside .vue files, manually define page links using hashed relative URLs and avoid using the default Vue :to property (use the href attribute instead). For example, <nuxt-link :to="{ name: 'about', hash: '#methodology' }">Methodology Notes</nuxt-link> should be replaced by <a href="./#/about#methodology">Methodology Notes</a>.

3. Vue also sets an active CSS class when the target route is active. This is not the case if we don’t use <nuxt-link :to=[...]. If you need this, the solution is to create a new method isRouteActive (name) { return this.$route.path === name } and add the :class="{'active': isRouteActive('/about`) }" attribute to the links, where about is the page name. In the end, it should look similar to this: <a href="./#/about" class="nav-link" :class="{'active': isRouteActive('/about') }">About this Dashboard</a>.