Tutorial on HTML element positioning

[TobyKLight]

Deep dive on CSS position modes

This will be a little crash course on the CSS position property, with end goal to understand how HTML elements can be placed on top of a canvas. For some cases Cables.gl handles this seamlessly, but other times, particularly when embedding, you might need to get your hands dirty with HTML and CSS to understand what's going on.

There is lots of info on the web already but I felt I should make a tutorial for cables.gl users because this is one of the times where we are in the deep end of the 'dynamic web content' swimming pool. Lots of the existing tutorials on this topic just cover the cases for basic web development and it's not clear how it comes together to make accessible content for cables.gl.

This tutorial assumes you are already familiar with:

• HTML elements
• The DOM (parent child relationships in HTML)
• CSS applied as classes from a stylesheet and as inline styles

---

Codepen interactive tutorials

Reference info is below but it may be easier to learn incrementally with some tutorials.
Here is a little series I made on codepen.

Start with the first tutorial here
Collection of all the tutorials

---

CSS Position

The CSS position property can be confusing because each of its values controls several separate behaviours:

• Sets if a HTML element can be moved in relation to an anchor
• Sets what the anchor for the current element is
• Sets if the element reserves space in a flow of elements
• Starts a new flow for child elements

To add further confusion position settings can also influence and be influenced by element size.

I will only cover the cases necessary for typical use in cables.gl.

position:static

position: static; 

Static is the default position setting for HTML elements.
Static means a HTML element takes its layout from the normal flow of a document. We have to understand this as the baseline even if we will rarely use it in cables.gl.

Normal Flow is actually quite a complicated concept.
We will only worry about regular blocks, not inline-blocks as that's not so important for cables.gl.

In brief:

• Most Elements in normal flow are blocks
• By default they take their size from their content (e.g text, images) + their styling (e.g. padding)
  • size can also be set manually
• Elements take their starting position from the next available position, after taking into account size of content above
• Elements in normal flow do not have to have size. They can be only organisational. e.g only for containing child elements.
  • If this is intended you should make sure such elements don't contain their own direct content and don't have any other styling that would cause them to have size. (eg padding)
• Child elements will effectively be part of the same normal flow as their parent

position:Absolute

position: absolute; 

• The element takes its start position from a specific anchor position
• The anchor that the element is offset from is either:
  • an ancestor element with position: set to anything other than static
  • if there is no such element then the anchor will be the HTML body tag, which is effectively means the anchor is the top of the page
• From that start position you can offset the elements position.
  • e.g. you can move the element in 2D space in relation to that start position
  • You don't have to offset it though, you can set position:absolute without shifting position.
• Absolute elements do not reserve space in the flow.
  • Meaning it's our responsibility completely to ensure it doesn't overlap other content.
  • Or in the case of cables.gl we do want it to intentionally overlap the canvas
• As per the above point, absolutely positioned element can act as a new anchor for any descendant absolutely positioned elements
• Child elements will start a new normal flow.

Ok that sounds like something we can use, we do want HTML elements to overlap our canvas.
In order to use it properly we have to use position:relative as well.

position:Relative

position: relative; 

Relative position means that

• The element takes its start position from the normal flow, just like static elements
• From that start position you can offset the elements position.
  • e.g. you can move the element in 2D space in relation to that start position
  • You don't have to move it though, you can set position:relative without shifting position. You may want position:relative for its other effects, see below.
• With position:relative the SIZE of the element remains in the normal flow is as if it WAS NOT MOVED. So although the element moves visually it leaves a 'footprint' of its original size and position in the layout. The next normal flow element will be drawn as normal as if the relative element has not been moved.
  • You can imagine a simple usecase for position:relative where you have a bunch of elements in normal flow and you want to shift one only a litte. without affecting the others. The element keeps its original 'footprint' in the normal flow despite being shifted.
  • see this illustrated example from digital ocean.
• As per the note above, position:relative elements will act as an anchor to any descendent position:absolute elements.
  • This is useful because it allows you to arbitrarily say that element X or Y in the normal flow should act as an anchor
• Child elements will start a new normal flow.

All of this adds up to some honestly arcane and confusing behaviour.
You can blame the iterative nature of decades of web development. We've got to deal with it.

Bringing it together in cables.gl

As the last step in the codepen tutorial demonstrated, the key to aligning HTML elements with the canvas is:

• The canvas and elements share a common parent that acts as a position anchor
  • This can be the HTML body for a fullscreen app
  • Or a specific HTML element with position:relative for a canvas embedded in content on a page
• Then each HTML element created by the cables.gl app should:
  • have position:absolute and
  • be located in the DOM as a sibling (or child of a sibling) next to the canvas.
• The goal is that these absolute HTML elements are offset from the same top left point the canvas is drawn from
• Then when the elements are offset by pixel values these correspond to pixel locations on the canvas.

To ind the parent element of the canvas and set your new dynamic elements as siblings of the canvas see this patch.
See this example for how to set the DOM order of HTML elements

To actually dynamically set the offset positions of elements in a cables patch use the op TransformElement.
If you inspect a cables patch where you are using this you will see it dynamically sets the top and left css properties of the specific elements.
See the example patch for TransformElement here

To get HTML elements perfectly aligned with content drawn on the canvas see the op TransformElementWorldRect from AccessExt team.
This will also allow you to set size of elements dynamically taking into account camera perspective.
Check the documentation and example for TransformElementWorldRect here

References for CSS positioning.

See the MDN article on CSS position
MDN article on 'normal flow' of web pages
A good introduction video to CSS position
A good deep dive video on CSS position

[pandrr]

great tutorial! thank you