Help on HTML, CSS, JS and JS libraries

HTML

HTML is less of a language and more of a collection of blocks or ‘elements’ that define what goes on your page. These elements are defined using opening and closing tags. For example, if I wanted to have an element displaying “hello world,” I would have an open <div> tag, followed by the text, followed by a closing </div> tag. So overall, the element looks like:

<div>hello world</div>

When constructing your own HTML, it is likely to be composed of two sections: a head and a body. In the Head, all of your external packages apart from your JavaScript file(s). For example, if I were using MathJax to write my equations, I would put the MathJax importing script into the Head. The body contains the actual elements that appear on the page. Then, you should import your JavaScript (or JS) files at the end of the body. This is done because if the JS files were in the Head, they might reference things that aren’t defined yet.

For more tutorials on HTML, here are a few useful resources:

• W3 Schools: https://www.w3schools.com/html/html_intro.asp
• CodeAcademy: https://www.codecademy.com/learn/learn-html

Cascading Style Sheet

Cascading Style Sheet, or CSS, is how we style almost everything on a given web page. CSS is a series of properties and their corresponding values describing all the stylistic features of an HTML element. For example, the following piece of code can set the width, height, and text colour of a div: 0

width:100%; height: 100%; colour: “#003E74”;

Everything from colour to size to animations is defined using CSS. One way of defining an HTML elements style using CSS is to embed the CSS directly into the element. An example of embedding CSS directly in an HTML element is:

<div class = “textbox” id = “theory” style = “width:100%; height: 100%; colour: “#003E74”;”> Hello world! <\div>

Note: If you don’t understand the above code, it may be useful to look at the HTML section in the Functionality Guidelines document!

Alternatively, an element's style can be inherited from a class or ID, with the actual CSS written in a separate standalone file. An example for the HTML in this case is: <div class = “textbox” id = “theory”> Hello world! <\div> With the separate stylesheet containing the following CSS:

• .textbox{
• width: 100%;
• height: 100%;
• }And

• #theory{
• Colour: “#003E74”;
• }

A typical visualisation will have a basic inherited style from one of two global stylesheets: skeleton.css and style.css. Any further detailed styling by a developer is typically done directly in the HTML file. For more on CSS, visit: W3 Schools: https://www.w3schools.com/css/css_intro.asp

Note on Sizes:When defining a class's dimensions in a CSS file, this can be done using absolute or relative units. Note that in the first line of example code in the document, relative units have been used (height and width defined in percent). Another way of using relative units would be to write height in terms of "vh" (view height) and width in terms of "vw" (view width); e.g.:width:75vw; height: 85vh;. Here, 1vw means 1% of the width of the viewport (the user's visible area of a web page) and the same for vh.

Absolute sizes are generally defined in pixels, e.g.:width:550px; height: 300px;. The disadvantage of this method of defining sizes is that certain elements will end up being different sizes, depending on the user's screen's resolution. For this reason, when defining div sizes, it is strongly recommended you use relative units.

JavaScript

For the most part, JavsScript (JS) is structurally similar to Python; it has functions that take input variables equal to a String, Float, Integer, or Boolean. However, if you are coming from a Python background, there are a few significant differences to note:

• Defining variables for the first time needs to be preceded with either Let, Var, or Const. For example, the start of your JS code could say const g = 9.8. The difference between these variable declarations is:
  • Let exists in a block-scoped namespace. I.e., if it is defined in a function, then it stays in that function.
  • Var is very wishy-washy. Please do not use it.
  • Const is also block-scoped, but cannot be reassigned.
• Rather than using indentation to define where a for loop/function is, JS uses curly brackets. For example:
  • This function returns the square of the input value:function square(x) {return(x*x);};
  • This for loop counts from 1 to 10: for (let i=0; i<10; i++ {console.log(i);};
  • This if statement prints ‘yay’ if happy is true and ‘aww’ if happy is false:if(happy===true){console.log(“yay”)}else{console.log(“aww”)};Note that although you don't need indentation to write JavaScript code, you are able to indent it however you like. Consistent

Plotly package

Plotly is a plotting package based on the D3 library. Most interactive plots in our visualisations have been made using Plotly, due to its simplicity and great style right out of the box. After including Plotly in your HTML head, you will mostly be dealing with Plotly through three functions:

• plotly.newplot(graph_id,data,layout)This function creates a plot in a previously unoccupied div with id graph_id. The data and layout inputs define what data is plotted and how the plot looks. Use this to initialise your plot.

• plotly.animate(graph_id, frames,animation_attributes)This function updates the data of an already existing plot in the element with id = graph_id. The frame variable defines the new set of data. Use this for animating a constant set of points or a line, for example.

• plotly.react(graph_id, data, layout)This function updates both the data and layout of an existing plot with id=graph_id. Use this if you need to animate axis sizes, for example, or if your new data set has different dimensions to the old one.

Notice how in all three functions, there is either a data or layout variable (or both). These are the two most essential variables in Plotly, and have a basic dictionary-like structure that is super intuitive! Let’s take a look at a data example first:

var data=[{type:"scatter",mode:"lines",x: [0,2,5,7,3],y: [1,6,3,7,8],line:{color:"#960078", width:3, dash: "dashed"}, },];

As you can see, data is a list of dictionaries, where the dictionaries’ entries are properties of a dataset, properties such as x, y, and data label. Data is a list because Plotly allows for the addition of multiple datasets at once onto a plot.

Now let’s look at a layout example:

const layout = {autosize: true,margin: {l:30, r:30, t:30, b:30},hovermode: "closest",showlegend: false,xaxis: {range: [-10,10], zeroline: true, title: "x"},yaxis: {range: [-10,10], zeroline: true, title: "y"},aspectratio: {x:1, y:1}};

As you can see, the layout is a single dictionary defining stylistic features of the plot, such as its size and margins. For more on how you should style a Plotly graph, visit the style guidelines page. For more on Plotly, the two most important resources are:

1. Function reference - https://plot.ly/javascript/plotlyjs-function-reference/
2. Full reference -https://plot.ly/javascript/reference/

Important note: Plotly can often be the reason a given page is slow or unoptimized. Look out for slow ways of updating a graph, such as plotly.purge() and plotly.newplot().