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.

Adding Text

First configure a side pane as shown, set showPagination to true in iv-sidebar-content if you are making a multipage visualisation or collection, the next and previous buttons wont work locally but should work when your visualisation is on the website and published. Copy text over from the old vis into iv-sidebar-section components in the side pane. Replace any equations, using the equation box component (you may want to add some linebreaks <br> to make it look nicer).

Copying Code

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 vm = this;. You can now refer to data and props of your Vue instance from within the mounted hook as vm.dataName.

Updating on Input

The mounted function runs when the page first loads so to update components when sliders or other inputs are changed, you should add a function called update() in the mounted hook, which is called repeatedly via requestAnimationFrame(update). You can then add a data attribute to the Vue instance called "update" and set this equal to a Boolean. Then in the update function, put an if(vm.update){} and add all your code for updating plots or interactive elements. Then when you click on any input, you can use the a v-on directive to set the update data equal to true.

Transferring Sliders

Old sliders should be replaced with the <iv-slider> component. Value displays next to slider, and name tags can be removed since the <iv-slider> component can display its own value in the bubble, and has a title built in. Refer to the documentation on this wiki for more information on the slider component.