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. 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.

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.

‎

<iv-visualisation: title="projectName">
‎

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).

<iv-visualisation :title="projectName">
    <template #hotspots>
        <iv-pane position="left">
            <iv-sidebar-content :showPagination="false">
                <iv-sidebar-section :title="projectName">
                    Next all we have to do is incorporate Snell's Law of refraction. This law states that: <br>
                    <iv-equation-box equation="\frac{sin(\theta_{i})}{sin(\theta_{t})} - \frac{n_{t}}{n_{i}}"></iv-equation-box>
                    <br>
                    From this we can see that given a certain refractive index ratio, the outgoing direction of a wave can be det...
                    So Snell's Law combined with boundary conditions allows us to calculate reflected and refractive waves given...

            </iv-sidebar-section>
         </iv-sidebar-content>
      </iv-pane>
‎

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.

Common Errors

Variables Not Defined Or Already Defined

Getting errors such as 'xInputTransformed' is not defined may be a result of the usage of the keyword var to define variables. Changing var to let may fix these errors. This is often due to var and let having different scopes.

Some old visualisations may be written poorly so that var is required as variables are used globally and changing to let will result in "variable not defined" errors in other places; to solve this quickly you can write let variable; in the outermost scope, then remove the var/lets from the variable each time it is used. A better fix would be to rewrite so that the variables are used correctly however this can often be time consuming.

WebGL Not Enabled

If you have a 3D plotly plot in your visualisation, you may encounter an issue where your graph displays an error message about webGL not being defined on your browser. This can be solved by replacing import Plotly from 'plotly.js'; with import Plotly from 'plotly.js/dist/plotly.min.js';

Variable Defined But Never Used

These errors are caused by the default linter (ESLint) having stricter requirements than default javascript. Try to remove any variables which are actually unused, however sometimes ESLint gets confused or does not recognise usage correctly. In this case you may disable ESLint on a specific line by pasting the comment // eslint-disable-line no-unused-vars next to the line.

Scrolling Past Panes Allowed

In the style set html{ overflow: hidden; }.