Upgrading Visualisation's Templates

Some visualisations were written before the introduction of the ImpVis Vue Template, or were written outside the template for some other reason. This page will help you with the process of importing visualisations written in plain HTML and Javascript into the Vue.js template.

Getting the Files

The files for visualisations are usually stored in two places: the ImpVis Github or the ImpVis Website.

To access visualisations on the Github, simply clone the relevant Github repository, and start editing locally (you may also wish to create a fork of the repository which you can push changes to).

To access visualisations on the ImpVis website you will need to have super-admin permissions on the website. Request these from one of the staff members or mentors/experienced students. Once you have the right permissions you will need to navigate to this page: here you can search for the relevant visualisation, and click on it. Then in the top right hand corner of the page you should see a download button. Click this to download the source files. You may want to set up a local git repository if you are planning to work on this visualisation for a long time.

Setting Up a New Template

This section assumes that NPM and the ImpVis front-end library have been installed on your machine. You can find out how to set up a blank template here. Open up a Command Line/Terminal and navigate to the folder you wish to work in. To set up a new template, key in "impvis create --visualisation name--" and press "Enter". There will be a section asking for packages you want to install. Please ensure that you include packages you may require for the visualisation, for example d3.js. Once the new template is set up, you may install additional legacy packages such as plotly.js or jquery (note “jQuery” is depreciated and “jquery” must be installed instead), by navigating to the new template folder using “cd” and running the command “npm install plotly.js”. An example of using a legacy package would be to add import Plotly from “plotly.js/dist/plotly.min.js”; at the top of the script section in App.vue.

Binding title prop to set the title of the visualisation.

Add a title to your vis by creating a title prop with default value of a string with your desired name and binding it to the <iv-visualisation> tag as shown.

Transferring Old Vis

Structure of side pane component, with example text.

First configure a side pane as shown, copying text over from the old vis. Replace any equations, using the equation box component (you may want to add some linebreaks <br> to make it look nicer).

Add appropriate <iv-toggle-hotspot> and <iv-fixed-hotspot> hotspots for sliders and buttons. Then create all required sliders using the <iv-slider> component and copy over the HTML for the buttons from the old visualisation.

Copy over the main HTML for the visualisation to the <iv-visualisation> component.

Create a Vue "mounted" lifecycle hook and copy over all the required javascript code for your visualisation into the mounted hook. Note that if there are multiple javascript files for the original visualisation, you will have to combine them, as all the required javascript code should go in the mounted hook.

Add the following line to the start of your mounted hook let v = this;. You can now refer to data and props of your Vue instance from within the mounted hook as v.dataName.