DEV Community: Samsung Internet

Immersive Web, Docker and problem with symbolic links for SSL certificates.

Sylwester Mielniczuk — Fri, 10 Jun 2022 09:53:19 +0000

Interactive Wall at GAM in Turin

As an Immersive Web Developer from time to time, there is a need to play the role of DevOps engineer. Mostly because the prototype of my research project needed to be deployed to production cloud infrastructure (5G EVE).

Despite the complexity of the overall 5G research, my web application is relatively weak, called "Interactive Wall" is designed for a multi-device experience with blazing fast animation purposes WebGL canvas (PixiJS). Depending on the provided parameters there are two types of UIs:

For students (kids or other pupils) - (multiplayer)
The teacher(s) (or other guardians) - (single user)

The first one is displayed on the wall via projector, the second can be opened via QR code on the mobile device, wearable or any other desktop running Chromium-based browsers. Realtime communication between both interfaces is established via WebSocket server.

The GIF above showcases a WebSocket connection between 2 tabs of the browser, mobile and wearable device. The latency between them is about and above 30ms but depends on the hardware and network characteristics. We were aiming to measure all the advantages of having 20 times faster connections than 4G.

Connecting to uncommon HID devices.

Paired and connected via Bluetooth thanks to WebHID API - old good and forgotten almighty Nintendo Wiimote. Its camera for direction reports is calibrated by IR Bar, and all the motion, acceleration and input data from 11 buttons are sent via Bluetooth to the browser.

What is actually WebHID?

^{"HID consists of two fundamental concepts: reports and report descriptors. Reports are the data that is exchanged between a device and a software client. The report descriptor describes the format and meaning of data that the device supports.

An HID (Human Interface Device) is a type of device that takes input from or provides output to humans. It also refers to the HID protocol, a standard for bi-directional communication between a host and a device that is designed to simplify the installation procedure. The HID protocol was originally developed for USB devices, but has since been implemented over many other protocols, including Bluetooth." - https://web.dev/hid/}

I was able to use simultaneously more than 4 controllers. Originally developed for one Wiimote by a former colleague at Samsung Kevin Picchi. I have developed a multiuser version for 5G Tours consortium. It's a really long story.

Portable Deployment

In general, the browser UI can be statically provided separately from the WebSocket server but for the sake of portability, decided to pack everything all together as Node.JS project, perfect for scalable web applications. Portable deployment should be easy with Docker. There is super simple tutorial how to do bake nodejs-docker-webapp. Basic use of Docker is free and you can install it on Mac, Windows and Linux. You need to write a relatively simple Dockerfile.

# The name of the image for your container
FROM node:16

# Create app directory, copy configuration assets
WORKDIR /usr/src/app
COPY package*.json ./

# Install npm
RUN npm install

# Bundle app source
COPY . .

# Optional exposed app ports
EXPOSE 8080

# Available commands from CLI
CMD [ "node", "index-wall.js" ]

To build the image run this command from the folder where your Dockerfile and assets are located.
$ docker build . -t flaboy/node-wall
flaboy/node-wall is the given name of image, when it's created you can push and pull this like git repo to the docker.io repository.

$ docker push flaboy/node-wall

If you need to share image file this is the way you can export tarball:
$ docker save flaboy/node-wall > node-vr.tar

Later someone can load the archived image as follows:
$ docker load < node-vr.tar

Deploying such an image seems to be super simple. On the server with a fully qualified domain and web server and reverse proxy Nginx).

The only little problem is those files required by server web application via HTTPS, ie SSL certificates. Where they are located? It depends on how you managed such certificates. I use letsEncrypt Certbot.

Your browser lock at the location bar says:

These chains of trust hierarchy technically have this structure:

Let's Encrypt Certbot hints

Installation:
$ sudo apt install certbot python3-certbot-nginx

Get your domain SSL certificates:
$ sudo certbot --nginx -d your.domain.name

The architecture is organized by certbot in this folder: /etc/letsencrypt

And the domain name specific files are saved to /etc/letsencrypt/archive/your.domain.name

So these files are archived under the following numbers (because certbot already renewed cert files so far several times). The latest ones are exposed to the /etc/letsencrypt/live/ folder. as symbolic links (symlinks) without numbers in their names.

^{- Symbolic links are interpreted at run time as if the contents of the link had been substituted into the path being followed to find a file or directory. - Symbolic links may contain .. path components, which (if used at the start of the link) refer to the parent directories of that in which the link resides. - A symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one; the latter case is known as a dangling link..}

root [letsencrypt] $ more /etc/letsencrypt/live/your.domain.name/README 
This directory contains your keys and certificates.

`privkey.pem`  : the private key for your certificate.
`fullchain.pem`: the certificate file used in most server software.
`chain.pem`    : used for OCSP stapling in Nginx >=1.3.7.
`cert.pem`     : will break many server configurations, and should not be used
                 without reading further documentation (see link below).

WARNING: DO NOT MOVE OR RENAME THESE FILES!
         Certbot expects these files to remain in this location in order
         to function properly!

We recommend not moving these files. For more information, see the Certbot
User Guide at https://certbot.eff.org/docs/using.html#where-are-my-certificates.

Coming back to the Docker. We have pulled the image and we would love to run the web app. The problem is that the container needs to read SSL certificates (exposed as symbolic links) from the outside of the Docker virtual container. They are required to run the web app securely via HTTPS. The paths to the key and certificate are provided in the main Node.js app file: index-wall.js

const server = https.createServer({
    key: fs.readFileSync('/ssl/privkey.pem'),
    cert: fs.readFileSync('/ssl/fullchain.pem')
}, app);

Here is how it can not be run with mounted volumes -v ( --volume).

$ docker run -v /etc/letsencrypt/live/your.domain.name:/ssl -d -p 4444:8080 flaboy/node-wall node index-wall.js

Docker unfortunately is not able to read symlinks from provided volumes (-v). You can check the error logs this way:
$ docker logs containerid

root [letsencrypt] $ docker logs 8d2b81a25359
node:internal/fs/utils:345
    throw err;
    ^

Error: ENOENT: no such file or directory, open '/ssl/privkey.pem'
    at Object.openSync (node:fs:585:3)
    at Object.readFileSync (node:fs:453:35)
    at Object.<anonymous> (/usr/src/app/index-wall.js:18:13)
    at Module._compile (node:internal/modules/cjs/loader:1105:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1159:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:77:12)
    at node:internal/main/run_main_module:17:47 {
  errno: -2,
  syscall: 'open',
  code: 'ENOENT',
  path: '/ssl/privkey.pem'
}

You need to use bind mounts

What are bind mounts? As per Docker documentation, we can read that:

[...] Bind mounts have limited functionality compared to volumes. When you use a bind mount, a file or directory on the host machine is mounted into a container. The file or directory is referenced by its absolute path on the host machine. By contrast, when you use a volume, a new directory is created within Docker’s storage directory on the host machine, and Docker manages that directory’s contents.

Detailed instruction on the bind mounts syntax:

--mount: Consists of multiple key-value pairs, separated by commas and each consisting of a <key>=<value> tuple. - The --mount syntax is more verbose than -v or --volume, but the order of the keys is not significant, and the value of the flag is easier to understand.

The type of the mount, which can be bind, volume, or tmpfs. [...] The type is always bind.

The source of the mount. For bind mounts, this is the path to the file or directory on the Docker daemon host. May be specified as source or src.

The destination takes as its value the path where the file or directory is mounted in the container. May be specified as destination, dst, or target.

The readonly option, if present, causes the bind mount to be mounted into the container as read-only.

The bind-propagation option, if present, changes the bind propagation. May be one of rprivate, private, rshared, shared, rslave, slave.

The --mount flag does not support z or Z options for modifying selinux labels.

So let's try to mount 2 cert files (sources):
/etc/letsencrypt/live/your.domain.name/privkey.pem
and /etc/letsencrypt/live/your.domain.name/fullchain.pem as they would exist inside docker container inside /ssl/ folder (target).

$ docker run --mount type=bind,source=/etc/letsencrypt/live/your.domain.name/privkey.pem,target=/ssl/privkey.pem --mount type=bind,source=/etc/letsencrypt/live/your.domain.name/fullchain.pem,target=/ssl/fullchain.pem -d -p 4444:8080 flaboy/node-wall node index-wall.js

Is the app running?
$ docker ps -a

9990433c624d   flaboy/node-wall   "docker-entrypoint.s…"   4 minutes ago   Up 4 minutes                 0.0.0.0:4444->8080/tcp, :::4444->8080/tcp   hardcore_nash

Yes! That's all people!

Here is my video on how it did not work properly with -v

And here is working properly with the latest SSL

If you would love to play with Interactive Wall, it's deployed to: https://xr.workwork.fun:4444

The app works on Mac, and Windows (you might need also Nintendo
emulator Dolphin). You just need a Chromium-based browser (Edge, Brave, Chrome), also get your original Wiimote(s) Plus (cheap, the third party rather does not work). Do not forget to charge your batteries. Infrared direction calibrator Mayflash W010 Dolphin Bar is necessary, get it from the Amazon. The WebHID API and amount of Bluetooth devices might be limited on Windows but Bluetooth standard might allow connecting lots of devices so having multiple input devices connected to the web browser interface at the same time is an amazing opportunity for multiplayer experiences without any game-server involved. Just think about this a little bit!

The Students UI
https://xr.workwork.fun:4444

The Teachers UI (open from provided QR code)
https://xr.workwork.fun:4444/?u=teacher&p=pass1

More about 5GTours project you can find in D4.4 public document on http://5gtours.eu/deliverables/

From Bootstrap to Grid

Lola — Thu, 21 Apr 2022 16:43:13 +0000

The Bootstrap Way
The Problem
CSS-Grid
display: flex
Combining CSS-Grid with Flexbox
Conclusion
Further Watching

This post isn't going to be a CSS-grid tutorial, there are loads out there, Jo even wrote one and since, CSS Grid has emerged as vita tool to enable responsive design. This is a post about how to understand the difference between traditional CSS layout frameworks (Bootstrap, Tailwind, Foundation, etc) & CSS-grid.

I’ve been building things on the web for almost 8yrs & in that time, Bootstrap has been my layout framework of choice. When I began developing on the web, creating responsive layouts in vanilla CSS was intimidating, especially as a Ruby, predominately back-end, engineer but thankfully, CSS has continued to evolve in that time and now we have CSS-grid. Despite this though, many developers still opt to use frameworks which impact the load of their websites and web apps when they don’t need to. I know for me, CSS-grid was still intimidating, I didn’t understand when to use that vs when to use flexbox or if I could use them together. In this post I’m going to try to explain how CSS-grid (& flexbox) work if you’re coming from a framework such as Bootstrap.

To learn and understand CSS-grid I decided to create a grid for my website since the layout is fairly simple and there are few elements on the screen. I marked up the grid and any sub-grids I used to get a clear understanding of where the elements are positioned. The red dashed lines are are the main grid while the yellow marks the sub-grid.

Without the use of any layout framework, the elements use the original HTML flow

I was able to recreate the layout, with only two changes (the positioning of the header) and make it fully responsive to width without any media queries.

The Bootstrap Way

Bootstrap typically work by defining a fixed, 12 column grid, while this number and the fixed width has historical context it’s mostly arbitrary, especially now considering the diversity in viewport dimensions. With this fixed width column system, you define how many columns your elements should take up at various viewport widths within a container e.g.

<div class="container">
    <div class="col-3-lg">
        ...
    </div>
</div>

This example defines a container then says the child element should take up 3 columns on a large screen, which in Bootstrap is a screen width of ≥992px. Other frameworks approach this in a different way, for example Tailwind actually uses CSS-grid under the hood. Bootstrap is also mobile-first and in the most recent version, if you have child elements that should take up an equal amount of space, regardless of device width, you don’t have to specify a unit e.g.

<div class="container">
    <div class="col">
        ...
    </div>
    <div class="col">
        ...
    </div>
    <div class="col">
        ...
    </div>
</div>

In the past Boostrap used CSS floats under the hood, however the current version, Bootstrap 5.1 uses flexbox (which I’ll go into more detail later).

The Problem

Bootstrap is a good way to quickly create a layout, especially if that layout is one of the few basic layouts that are used on the web. It has an extensive list of class definitions for developers to choose from, the documentation is robust and it’s free to use, there’s a place for Bootstrap. But choosing to use it should be intentional and not because you’re intimidated by CSS-grid.

Inflexiblity

In Ruby on Rails development, the methodology is “convention over configuration” which is to say it’s easier (read: better) to do things as they’re defined than it is to try and customise the framework to meet your needs. I think most frameworks, regardless of language, work in this way. While Bootstrap is robust, it isn’t flexible. The minute you want to create layouts that don’t follow the rules of a 12 column grid, or have elements doing interesting things like overlapping, or even decide to adjust the layout dependent on height instead of width, things begin to get complicated.

Obscures the CSS

The job of a framework is to create a sort of instruction manual of using a language in a certain way to build certain things. So, yes, frameworks will naturally obstruct the vanilla language being used to construct them however, Bootstrap goes an extra mile to redefine things that can be easily defined in one rule, for example:

.d-flex {
  display: flex !important;
}

This is a rule that can easily be defined within the custom CSS, without the !important keyword.

On the topic of !important this is another place where CSS is obscured, the keyword is litered all through the framework and should you be using Bootstrap in conjuction with another stylesheet, especially on big projects, you will have to be careful and aware of the order of how your stylesheets are being loaded and where styles may be overwritten.

Overbloat

Because Bootstrap tries to cover many basis, there are inevitably rules and styles you won’t end up using but these styles will still be loaded into the site. Bootstrap also comes with a visual identity, there are styles for all kinds of elements, buttons, navs, leads, etc but even if you elect to just include the grid in your project, you won’t be using all aspects of the grid. In fact, it’s possible you may just use 3 or 4 grid properties but will still be loading a 53KB file (if only using bootstrap-grid.min.css ), my custom grid.css file for this project ended up being only 881bytes without being minified and is only 62 lines long.

CSS-Grid

Learning CSS-grid requires unlearning Bootstrap (or which framework you’re using if it’s not using grid under the hood). Before I get into the minutiae, it’s important to note that CSS-grid encourages you to have multiple grids on a page where as Bootstrap assumes you have one main grid which you nest elements within. CSS-Grid says apply the grid where you need it, which really encourages you to think about the default display of elements (which elements are block, which are inline and do you need to flex anything?).

What is a Column, What is a Row, What is a Cell?

Any grid framework or understanding works on a x-axis and a y-axis, it’s 2-dimensional in that way, this may seem like an obvious fact but is important to remember. Within Bootstrap, columns and rows work in the traditional way. A row is horizontal space while a column is a vertical space. In the image below the green dotted line around the perimeter of the elements indicates the row while the dotted line down the middle separates the columns. So there is one row and two columns.

This would be defined in the HTML as

<div class="row">
    <div class="col">
        <img>
    </div>
    <div class="col">
        <p></p>
    </div>
</div>

Which is to say both the row and the column refer to the space between the lines of the grid, rather than the lines themselves. In other words, we define the row and column on the page and fill both with content.

CSS-grid also uses rows and columns but not in the same way. In grid, the columns and rows refer to the lines rather than the space between the lines.

Although difficult to see, each line is numbered. The numbers in this image refer to the rows and columns, so the first vertical line is column 1, the second is column 2, and the first horizontal line is row 1 and the second is row 2. The space in between these lines, the cell, contains the image. Similarly, the block of text starts at horizontal line 2 i.e. column 2 and ends at horizontal line 3 i.e. column 3 and also starts at vertical line 1 i.e. row 1 and ends at vertical line 2, i.e. row 2.

And when the page collapses into a single column the image is still starts at column 1 and ends at column 2 and starts at row 1 and ends at row 2 but the block of text now also starts tarts at column 1 and ends at column 2 but sits between row 2 & 3.

The space between the rows and columns is called a cell. So the image sits in a cell that between two columns and two rows.

The CSS and HTML for this aren’t complex

<main>
      <!--Grid cell 1 -->
      <img>
      <!-- Grid cell 2 -->
      <div class="about">
      </div>
</main>

main {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(50ch, 1fr));
}

I will go into detail about grid-template-columns a little later but the important thing here is that I’m defining a grid on the parent element (similarly to how you might define a container in bootstrap) and then telling the CSS how I want the grid to look i.e. how I want elements to occupy the available space.

If I want the elements to span multiple columns or rows, I can define that in the CSS


main {
    display: grid;
        ...
}

img {
    grid-column: 1 / 3;
}

img {
    grid-row: 1 / 3;
}

This will cause the image to start at column 1/row1 and end at column 3/row3, which will occupy 2 cells. If I wanted to have an element occupy 2 cells with Bootstrap, I’d give the element a .col-2 however, remember that Bootstrap works on a fixed-width grid and CSS-grid doesn’t. Play with this on MDN to really get to grips with it.

You can also define a grid-area which is a combination of the rows and columns.

Fractions (aka FR)

With CSS-grid comes a new unit to define how much space elements should take up. While it’s entirely fine to use px, ch, em, rem, %, etc fr (fraction) is a little more flexible in the context of grid.

main {
    display: grid;
    grid-template-columns: 1fr 1fr;
}

As mentioned earlier, the grid-template-columns defines the vertical space the elements in my grid should occupy. I can define the same for rows with grid-template-rows but for now let’s focus on columns. In the CSS above, I’ve said that each column should take one fraction of the available grid space. Regardless of the viewport width, the grid cells will only take up 1 fraction of space in the grid.

So even on smaller devices the elements will still try to take up 1 fraction of the available grid. Of course, you can use any fraction here, 2fr, 7fr, etc and mix and match. You can also tailor to consider how many cells will be in the grid and define those too, so if my grid had 4 cells I could say grid-template-columns: 1fr 1fr 1fr 1fr to say I want 4 cells and each should take up 1 fraction of the available grid space. You can also mix and match different units to get your ideal layout, have a go on MDN.

Gaps aka Gutters

The grid gutter in Bootstrap is the space between columns and rows, in the image below each column has a box around the perimeter and a space in the middle which is the gutter.

While the gutters in Bootstrap can be redefined, most users use the default gutters and don’t have to consider them. With grid, gutters are called gaps and you also may not have to define gaps on grid dependent on the units you choose to define the columns but implementing gaps is straight-forward. You have the option of defining the column-gap, row-gap or for if you want both the vertical and horizontal gaps to be the same then gap.

Gaps can also be used to define the space within flex elements, so if you plan to nest grids within flex elements, and are defining gaps on both the grid and flex element, you may find your gaps are slightly wider than you anticipate. The solution is to adjust them as you see fit. You can play with gaps on MDN.

Get Responsive without Media Queries

As I mentioned earlier, I was able to recreate the responsiveness of my original site without using media queries. This requires a combination of rules to create the fluidity of a responsive web page.

First up, repeat

main {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
}

This says create 2 columns each taking up 1 fraction of space in the grid, the issue here is that on smaller viewports, there will be 2 squished cells which isn’t want we want.

To overcome this hurdle, we can define the minimum width for the columns using minmax

main {
    display: grid;
    grid-template-columns: repeat(2, minmax(50ch, 1fr));
}

Here we’re saying we want 2 columns, with a minimum of 50ch width, taking up 1fr of the available space.

This presents a new problem, when we’re on devices with a viewport width that’s smaller than the available row space, the content will overflow. This is also unideal, so there’s one more part to enable the cells collapsing like we expect.

auto-fit/ auto-fill:

main {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(50ch, 1fr));
}

I’ve decided to use auto-fit here which collapses the columns into rows as we expect. auto-fit and auto-fill have similar functions in that they both look at the available space in a row and assign column space to the available cells. Sara Soueidan explains the difference as:

auto-fill FILLS the row with as many columns as it can fit. So it creates implicit columns whenever a new column can fit, because it’s trying to FILL the row with as many columns as it can. The newly added columns can and may be empty, but they will still occupy a designated space in the row.
auto-fit FITS the CURRENTLY AVAILABLE columns into the space by expanding them so that they take up any available space. The browser does that after FILLING that extra space with extra columns (as with auto-fill ) and then collapsing the empty ones.

I recommend reading the full explainer to really get your head around the difference.

The combination of repeat, minmax and auto-fit/ auto-fill creates a layout that’s responsive to width without media queries and in one line.

`display: flex`

Flexbox deserves its own post so I won’t go into too much detail here but it’s important to know how it fits in with grid. Many people aren’t only intimidated by CSS-grid, but also by Flexbox and the difference is between the two. Coming from Bootstrap, it’s tricky to know when to use either. The good news is you can use both but they do serve different purposes.

As I mentioned before CSS-grid works along the X-axis and Y-axis, it’s 2-dimensional. Flexbox only works along the X-axis, which is the horizontal axis and so it’s 1-dimensional. Adding elements to a flex element will cause the elements to flow horizontally.

In the example above, I have a ul element which usually stacks its list items vertically, however, since I’ve given the element a display: flex the elements are lined up horizontally. It’s possible to allow flex elements to stack vertically to avoid overflow with flex-wrap: wrap as I’ve done for the list of buttons here:

The CSS for this is two lines

ul {
    display: flex;
    flex-wrap: wrap;
}

Justify & Align Content

The super power of Flexbox is being able to justify and align content the way we want. Aligning content positions the element along its own y-axis, while justify position an element along its own x-axis.

Combining CSS-Grid with Flexbox

Okay, so we can kinda grasp CSS-Grid and Flexbox how and why would we put them together? Let’s revisit my very first image with the Bootstrap grid outlines:

To recap, the red dashed lines are the main grid and the yellow lines are the subgrid. Breaking this down I can see that I think I want 2 columns and 3 rows for the main grid, however CSS-Grid forces us to only use the grid where necessary. This is where personal preference comes into play, there aren’t any concrete rules here, it’s entirely up to me and how I want to lay this out. Bootstrap’s approach to this would be to make all the columns flex elements and wrap them as necessary and not use the grid at all.

The method I ended up going with was a combination of CSS-Grid and Flexbox.

I changed my mind about the layout to be a little more accesible. The previous layout would have screenreaders reading the image before the title which isn’t ideal. I’ve moved the title into a header with the nav, and since neither the header or the footer needs to work on a 2-dimensional level (or can just without changing the native display properties of the elements), I’ve decided to only apply the grid to the main content. The red dashed line shows 3 columns, 2 rows which create space for 2 cells.

I’ve moved the title into a header with the nav, and since neither the header or the footer needs to work on a 2-dimensional level (or can just without changing the native display properties of the elements), I’ve decided to only apply the grid to the main content. The red dashed line shows 3 columns, 2 rows which create space for 2 cells.

I’ve decided to use flex for elements which normally have a display: block so that they can flow horizontally, wrap if necessary and are justified and aligned as expected on all screen sizes.

Conclusion

CSS-Grid is very robust and there are definitions that I didn’t cover here, such as grid-template-areas which allows you to define sections of a page with different grids to create a layout, it also allows for empty cells (without defining empty HTML elements). Or grid ordering which lets you define the order of cells within a grid in the CSS.

One of the qualities of Bootstrap is that there’s the option to create sub-grids fairly easily and while it’s possible to nest grids with CSS-grid, there is a dedicated sub-grid ruleset on its way.

Further Watching

The Trouble with `has_one`

Lola — Tue, 10 Aug 2021 13:19:27 +0000

Recently I was working on my dissertation and came across an interesting problem with using the has_one association in Rails. But before we get into that, let’s take a step back to understand a little about how associations work in Rails.

Rails Associations

I’m not going to assume everyone reading this knows or understands in depth about databases and object relational mappers so I’ll try to keep this brief and simple. If you want a more in depth understanding, the Rails docs are a good starting point to understanding this in that specific context.

Let’s say you want to build a content site where different creators can create posts, you’d have a relational database with two tables Creator and Post that may look something like this:

Your creator table has an ID and Name column for every item that gets created and your post table has an ID, Title, Type and Body column for every item. In each column, the primary key will be the ID column since that’s going to be the unique identifier for each record. The primary key is important when creating associations because it acts as the foreign key in the associated table.

Now we need to decide what kind of relationship the two tables will have with each other since we’d likely want to know which creators created which posts. There are a few different kinds of associations you can create but I’ll only touch on two.

has_many

A has_many association, says one item in a table can be associated with many items in another table. For example, if our system is a standard content creation system then a creator can have many posts since one creator can create many posts in which case, the association in Rails would look like:

class Creator < ApplicationRecord
  has_many :posts
end
class Post < ApplicationRecord
  belongs_to :creator
end

And our database would look like:

The creator_id would be pulled from the id column, which is the primary key in the creator table and act as a foreign key in the post table. So if you wanted to find all the posts created by Tiffany Pollard, you’d do a search on the post table where the creator_id matches Tiffany Pollard’s id in the creator table.

has_one

A has_one relationship says one item in a table can only be associated with one item in another table, no more than one. We may want to create a system where a creator can only ever create one post in which case, our Rails code would look like:

class Creator < ApplicationRecord
  has_one :post
end
class Post < ApplicationRecord
  belongs_to :creator
end

A creator has_one post and a post belongs_to a creator. The database looks the same as before:

And just like with has_many the creator_id is the foreign key for the creator’s id in the post table.

Okay, so now onto the problem.

...

The Problem

In Rails when you create a has_one association, understandably the assumption is that a creator can only ever have one post. So what happens when a creator tries to create another post? You’d hope that it’d check to see if a post exists and ask the creator if they want to replace the post or just replace the post with the assumption that that’s the intention of the creator. But that’s not what happens, instead, you get this error:

This is a common error with has_one and is summed up nicely in this issue:

This is because prior to deleting, the foreign key of the target association is set to nil and a save operation is performed on the target.

It’s unclear why this happens, if you go through the issue you’ll notice it was created in 2014 and the discussion is still ongoing. It seems this started out as a bug but may have evolved to become the desired functionality.

The Fix

There are a number of ways to fix this and it all depends on your system. Essentially, you want to make sure the old association is deleted before you try to create a new one. So, you can do this in your model:

class Creator < ApplicationRecord
  has_one :post, dependent: :destroy
end
class Post < ApplicationRecord
  belongs_to :creator
end

Or in the method where you create your resource (either in your controller or specific lib file) you can run something like:

creator = Creator.find_by_id(id)
creator.post&.delete

before you create any post. Andy Croll from Coverage Book recommends rolling things up in a transaction and there are more suggestions in the GitHub issue too.

Making an AR Game with AFrame

Ada Rose Cannon 🏳️‍🌈 — Thu, 14 Jan 2021 16:57:37 +0000

Making an AR Game with AFrame

Using AFRAME, THREE.js and WebXR to build a game during a 4.5hr live stream.

Here is a .gif (jiff?) of the final game, click here to play the game. It uses the WebXR DOM Overlay API, and the WebXR Hit Test API. So right now the best way to play it is in Mobile Chrome or Samsung Internet Beta.

A virtual ball being shot into a virtual basketball hoop.

If you want to watch all four-plus hours of the live stream the URLs are here:

If you want to just look through the source code here it is:
AdaRoseCannon/basketball-demo
Playbasket ball in AR with Aframe and the WebXR device API GitHub is home to over 50 million developers working… github.com

This was my first time live streaming a whole project from start to finish. It was fun I think I would do it again for small projects like this. In this blog post I will talk about what tools I used to make it and some of the tricks that went into it.

Setting up AFrame

First thing first is to create a new HTML file. index.html and put in some HTML boilerplate. I do this in VSCode using the Emmet Abbreviation ! to auto-fill some basic HTML.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My AR Game</title>
</head>
<body>

</body>
</html>

Next to add the AFrame script I copy and paste the script tag from the AFrame docs.

<script src="[https://aframe.io/releases/1.1.0/aframe.min.js](https://aframe.io/releases/1.1.0/aframe.min.js)"></script>

And paste the AFrame hello world into the body:

<a-scene>
  <a-box position="-1 0.5 -3" rotation="0 45 0" color="#4CC3D9">
  </a-box>
  <a-sphere position="0 1.25 -5" radius="1.25" color="#EF2D5E">
  </a-sphere>
  <a-cylinder position="1 0.75 -3" radius="0.5" height="1.5" color="#FFC65D">
  </a-cylinder>
  <a-plane position="0 0 -4" rotation="-90 0 0" width="4" height="4" color="#7BC8A4">
  </a-plane>
  <a-sky color="#ECECEC"></a-sky>
</a-scene>

Testing

To test it I start a local http server to let me display it on my computer. I use the node http-server module. If you don’t have node environment to hand a couple of other options are the Chrome Web Server extension or building it on a website like glitch.com

WebXR requires a secure origin to run. Secure origins usually begin with https:// a special secure origin is http://localhost which lets you access local a http server.

If you are using Glitch you can just open the URL on the your phone to test it.

Unfortunately the requirement for a secure origin makes things tricky for testing a local server on external devices. Normally I would access the server on my development computer via IP address like so: http://192.168.0.10:8080 but since it’s not a secure origin it can’t be used for WebXR.

To test it on my phone there are two options which work well, the most convenient option is to plug in my phone using USB and use Chrome’s remote debugging to forward the port of the http server. Open chrome://inspect in Chrome to access this feature:

chrome://inspect

Once that is set up you can then open up http://localhost:8080 (replace 8080 with whatever port you are using) on your phone and test like you would on your computer.

During my live streams I couldn’t get this working since I was using my phone’s USB-C port to capture the HDMI. So I used https://ngrok.com/ to get a real https: enabled URL for my local server.

Enabling AR features

The first thing to notice when you try AR in our AFRame scene is that you’ll see through the device camera briefly before it gets obscured when the scene gets shown. This is because the element covers the whole scene.

To solve this we’ll add a new AFrame component to hide objects when the scene goes into AR. This code is from work done by Klaus Weidner in one of the AFrame demos:

AFRAME.registerComponent('hide-in-ar-mode', {
  init: function () {
    this.el.sceneEl.addEventListener('enter-vr', (ev) => {
    if (this.el.sceneEl.is('ar-mode')) {
      this.el.setAttribute('visible', false);
    }
    });
    this.el.sceneEl.addEventListener('exit-vr', (ev) => {
    this.el.setAttribute('visible', true);
    });
  }
})

I included this snippet in a little library of useful components I copy from project to project. As well as some other useful parts so I will just add that script to the page:

<script src="[https://ada.is/basketball-demo/ar-components.js](https://ada.is/basketball-demo/ar-components.js)"></script>

This adds a hide-in-ar-mode component and an ar-hit-test we can use in Aframe. We add the hide-in-ar-mode component to HTML elements I want to hide in AR such as the so it now looks like this:

<a-sky color="#ECECEC" hide-in-ar-mode></a-sky>

The other issue is the scale. The AFrame hello world example is designed for VR. In VR where physically large scenes work well because you can take advantage of the unlimited space. In the AFrame Hello World Example the content is placed 5 meters from the user and is 2.5m tall. This is very large and looks impressive in VR but in AR is much too big to fit in many people’s real environment.

When designing AR scenes, try to avoid having the content larger than 0.5m to enable people to fit it in their environment.

When designing AR scenes, try to avoid having the content larger than 0.5m to enable people to fit it in their environment. I say this as someone who lives in a small apartment.

The times when you want to break this rule is when the AR scene is designed to only be used outside where space is more available or when the virtual object is a stand in for a real object which has specific dimensions. Such as if they are buying a particular piece of furniture and want to see how well it fits in their house.

To update the scene I made all the objects in the scene 10% of their original size. All of the units in WebXR and AFrame are in meters so I turned 1.25m into 0.125m (12.5cm or about 6 inches.)

Adding hit testing

Hit testing allows you cast rays from the virtual content into the real world. So you can place virtual objects inline with real world objects such as the floor, tables and walls.

It will get you both the position and normal of where it hits letting objects be placed on services both vertical and horizontal.

The hit-test feature is one which is not available by default in WebXR because it lets you get additional information about a user’s environment.

But you can request it when the XR session is started in AFrame you add it to your element using the webxr component like so:

<a-scene webxr="optionalFeatures: hit-test;">

To assist in how it’s used I made a component to help with it in the library I mentioned earlier:

<script src="[https://ada.is/basketball-demo/ar-components.js](https://ada.is/basketball-demo/ar-components.js)"></script>

The ar-hit-test component will continuously do hit-testing using the most relevant user input available assisting you to build something which works on a variety of hardware. Such as it will default from using the headset position but will use a VR controller or hand tracking if it is available.

Wherever the hit lands it will place the object. This makes it handy for being a targeting reticle in AR.

We’ll make a 20cm square to use for the guiding reticle:

<a-plane
 rotation="-90 0 0"
 width="0.2"
 height="0.2"
 src="./arrow.png"
 material="transparent:true;"
></a-plane>

arrow.png

Like <div> is for HTML for AFrame it is <a-entity>. This is a plain element with no additional properties such as 3D models. We will make a new which uses the ar-hit-test component to be positioned by hit-testing.

<a-entity ar-hit-test="doHitTest:false" visible="false">

Reticle HTML goes here ...

</a-entity>

We’ve also made it invisible since the ar-hit-test component will make it visible again when it’s able to do hit-testing.

Creating the Basketball Hoop

Now we have some way of getting the position of real world objects we want to create the hoop to go on the wall.

Objects placed on surfaces using hit testing have their y-axis (the up and down axis) aligned with the normal of the surface they are being placed on. This means that objects placed on the floor should appear pretty normal but on surfaces like walls or ceilings they will get rotated. The objects are usually also rotated around this normal to face the hit-test source but this behaviour is not in the spec and so may vary.

Since an object placed on the wall will be rotated 90 degrees we will start it off with some initial rotation as we design it. So the encapsulating entity #hoop will have rotation="90 0 0" which is similar to an object placed on a wall. If we were placing it on the floor a rotation of 0 0 0 would suffice. This rotation will be reset when we place the object against the wall to what ever the orientation of the normal of the wall is.

The hoop will be made of 3 simple shapes, a plane for the back board a torus for the hoop and an open ended cone for the net:

<a-entity id="hoop" rotation="90 0 0" position="0 2 -1.8"> 

    <a-torus scale="0.6 0.6 0.6" position="0 0.173 -0.1" color="#43A367" radius="0.25" radius-tubular="0.005"></a-torus>

    <a-plane
     scale="0.6 0.6 0.6"
     position="0 0 -0.3"
     rotation="-90 0 0"
     width="0.9"
     height="0.9"
     material="transparent: true; side: double;"
     src="./backboard.png"
    ></a-plane>

    <a-cone scale="0.6 0.6 0.6" position="0 0.173 -0.010" color="tomato" radius-bottom="0.25" radius-top="0.3" material="side: double; opacity:0.5; transparent: true;" geometry="height: 0.29; openEnded: true" rotation="90 0 0"></a-cone>

</a-entity>

The end result is simple but should be clear what is.

The basketball hoop created by the code earlier

Positioning the hoop

We want the player to be able to position the hoop on their wall. We can get their chosen position by copying the location from the reticle:

const reticle = document.querySelector("[ar-hit-test]");

function positionHoop() {

    hoop.setAttribute("visible", true);
    hoop.setAttribute("position", reticle.getAttribute("position"));
    hoop.setAttribute("rotation", reticle.getAttribute("rotation"));
}

reticle.addEventListener('select', function (e) {
    positionHoop();
});

This very simple function will make the hoop visible and position the hoop at the same position and rotation as the reticle when a select is made. This naive function will often make the hoop a bit crooked though as it will be tilted to face the hit-test origin but lining it up is hard. So we will need to do some Vector Math to ensure the z direction of the hoop lines up with the y-axis.

const upVector = new THREE.Vector3(0, 1, 0);
const tempVector = new THREE.Vector3();
const tempQuaternion = new THREE.Quaternion();

function positionHoop() {

    hoop.setAttribute("position", reticle.getAttribute("position"));
    hoop.setAttribute("visible", true);

    tempVector.set(0, 0 ,-1);
    tempVector.applyQuaternion(reticle.object3D.quaternion);
    tempQuaternion.setFromUnitVectors(tempVector, upVector);
    hoop.object3D.quaternion.multiplyQuaternions(tempQuaternion, reticle.object3D.quaternion);
};

This slightly more complicated function will work out the Quaternion rotation needed to rotate the reticle into an upright position. It will then set the quaternion rotation of the hoop to multiplication of that rotation with the reticle’s rotation. Resulting in a hoop that is facing the right way but twisted slightly so that it points up.

Adding physics to the scene

Physics is handled by the very useful aframe-physics-system this allows you to make the objects in the scene behave in physically realistic ways.

There are two types of physics objects:

Static Bodies, these do not move or react to being hit by other objects they effectively have infinite mass and are unaffected by gravity. They are cheap to use but cannot move. Anything that should not move should be a static body such as Floors and Walls and in our case the basketball hoop.
Dynamic Bodies, these have mass and will fall with constant acceleration under gravity. They can bounce off static bodies or collide with other dynamic bodies. The only dynamic body in the scene is the ball itself.

To set up the physics system we will include the script after the A-Frame script and add the physics component to our scene element:

<script src="https://cdn.jsdelivr.net/gh/n5ro/aframe-physics-system@v4.0.1/dist/aframe-physics-system.min.js"></script>

...

<a-scene physics="debug: false">

To help setting up your scene it can be worth while to set debug to true so that you can see the shapes it has made outlined in red.

Next we add a sphere with the dynamic-body component to be the ball:

<a-sphere id="ball" dynamic-body radius="0.1" color="orange" position="0.1 2.36 -1.5"></a-sphere>

If we reload the page the ball should fall indefinitely.

The next step is to add static-body to the floor plane so that something can stop the ball, I also made it much larger as the ball will roll when it hits it.

<a-plane
    rotation="-90 0 0"
    width="20"
    height="20"
    color="#43A367"
    static-body
    hide-in-ar-mode
></a-plane>

When we play the game we want to interact with the hoop. So next we will add static-body to the backboard plane.

What do we do about the hoop? This is a lot more complicated. The hoop is a convex object it has a pretty complex topology and the 3D model has many vertices which makes the physics very expensive.

The trick here is to have an invisible torus with as few polygons as we can manage, we make it a static body but make it invisible and place it on top of the high resolution model. This is a common trick in video games to have the physics objects with much simpler geometry than the visible objects.

<a-torus scale="0.6 0.6 0.6" static-body="shape: mesh;" position="0 0.173 -0.1" visible="false" radius="0.27" radius-tubular="0.02" geometry="radius: 0.29; segmentsRadial: 5; segmentsTubular: 12">
</a-torus>

By having the static objects of the hoop inside the hoop entity they will be kept inline with the visible objects.

AFrame Physics System also has a JavaScript API for detecting when two objects collide or setting velocities of objects. It is available on the body property of the entity we want to control as long it is a static or dynamic body.

If we want to set the position and velocity of an object such as the ball we use this method. Here is how we launch the ball from the currently active controller:

const ball = document.getElementById('ball');

  reticle.addEventListener('select', function (e) {

  // Set the ball location to the controller position
  const pose = e.detail.pose;
  ball.body.position.copy(pose.transform.position);  // {x, y, z}

  // Have an initial velocity vector of 5ms into the screen
  tempVector.set(0, 0 ,-5);

  // Set our velocity vector direction to the controller orientation
  // {x, y, z, w}
  tempVector.applyQuaternion(pose.transform.orientation);

  // set the velocity of the ball to our velocity vector
  ball.body.velocity.copy(tempVector);
});

Dom Overlay

The last thing we need is to make some UI so that the user can say when they have set the hoop position and are ready to play. We can build a normal HTML interface for this:

<div id="overlay" class="container">
  <h1>Welcome To Basketball</h1>
  <section class="overlay-content">
    <p id="instructions">Place the basket along a wall</p>
  </section>
  <div style="display: flex; justify-content: space-between; align-self: stretch;">
    <button id="go-button">Ready to Play!</button>
    <button id="exit-button">Stop AR</button>
  </div>
</div>

Then you can use it by declaring it on the WebXR component on the scene object:

<a-scene webxr="optionalFeatures: hit-test, dom-overlay; overlayElement:#overlay;" >

Using real HTML buttons and text has many benefits for the user such as working with accessibility tools, being more readable. It can be styled with regular CSS and can be coded with normal JavaScript.

Something to bear in mind though is that when the user taps on DOM Overlay Elements they will fire input events such as 'click' 'mousedown' and 'touchstart' events as usual but in addition will fire WebXR 'select' events first!

So you may need to use something like a setTimeout in your 'select' events to ensure that a button has not been pushed if you are waiting for input from the HTML buttons.

You can detect support for DOM Overlay by looking for xrsession.domOverlayState.type . If domOverlayState is not set then domOverlay is not present in the browser. If type is not set then the current hardware/browser configuration does not support DOM Overlay so you can use the following function to detect it:

function hasDomOverlay(xrsession) {
  if (!xrsession.domOverlayState) {
    // DOM Overlay is not supported
    return false;
  }

  if (!xrsession.domOverlayState.type) {
    // DOM Overlay is not in use
    return false;
  }

  return true;
}

If you are using DOM Overlay for essential paths through the code then you can use this to detect availability and provide fall back behaviors.

Read the source code to the finished demo

Here is the source code to the demo, I hope this guide helps you make sense of it and some of the decisions that were made. If you have further questions feel free to reach out to me through Twitter.

Thank you so much for reading!
AdaRoseCannon/basketball-demo
Playbasket ball in AR with Aframe and the WebXR device API - AdaRoseCannon/basketball-demo github.com

Promises for Rubyists

Lola — Mon, 07 Dec 2020 10:57:42 +0000

The Soundtrack

I tried to write a post about JavaScript Promises using Ciara - Promise, but it didn't work so instead have this genre-agnostic playlist of 10 songs with the title Promise. Don't let my hard work be in vain & have a listen.

The Background

JavaScript and Ruby are both single-threaded programming languages, they can really only do one thing at a time, in a particular order. This also means they're both synchronous. They run in a queue-like way, the first operation or function to get called is the first to be performed before any other operation is performed, this presents a problem the moment you want to do anything that requires multi-tasking. Both languages have workarounds, modules, gems and in-built features that can allow you to write asynchronous code, e.g. JavaScript's Web Workers or background jobs in Ruby. JavaScript also has promises, the topic of today, which Ruby doesn't have an in-built match for at the moment, so I'm going to try my best to recreate what this could look like.

The Promise

It's a commitment to give you something later, it'll either be the thing you ask for or an error but you'll definitely get something.

Essentially, a promise is a returned object to which you attach callbacks, instead of passing callbacks into a function.

-https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises

Callbacks in Ruby

In Ruby, we really mainly deal with callbacks in the context of Rails (or other web framework) when we're manipulating objects during their creation phase. You might have used a before_create: :do_thing in a model, this is generally what callbacks are in Rails (not necessarily Ruby), and there are a list of them. But using plain old Ruby, you'd have a method that you could pass a block to:

  def add_one(n)
     total = n + 1
     yield total
  end

  add_one(5) { |total|
    puts "the total is #{total}"
  }

The callback here is the block we pass to add_one(5) which is then called with our yield in the definition of the method. So here we're passing the callback to the method.

Callbacks in JavaScript

Unlike Ruby, JavaScript functions can accept functions as arguments but not blocks which means you'd create dedicated callback functions in a JS context.

  function getTotal(t) {
    return "the total is ${total}"
  }

  function addOne(n, callback) {
    const t = n + 1;
    callback(t);
  }

  addOne(5, getTotal);

Here we're also passing the callback to the function, similar to the Ruby implementation. This is synchronous since a blocking operation (the addOne) needs to happen first before the callback can happen.

Implementation

There isn't a native way to write promises in Ruby but just to illustrate the functionality, imagine being able to send data between your controller and view without refreshing the page in Ruby, with no JavaScript. It's the stuff dreams are made of but in the real world we need JavaScript.

I've been working on the Samsung's Global Goals PWA and in this I've had to use promises to interact with Stripe and the Payment Request API. Let's see a real world example of this:


  async function fetchPaymentIntentClientSecret(amount){
    const fetchedPaymentIntentCS = await fetch(`/fetchPaymentIntent/${amount}`);
    const clientSecretObj = await fetchedPaymentIntentCS.json();

    return clientSecretObj.clientSecret;
}

 fetchPaymentIntentClientSecret(amount).then((clientSecret) => {
        confirmPayment(paymentRequest, clientSecret);
    }).catch((err) => {
        console.log(err);
    });

The fetchPaymentIntentClientSecret function is defined using the keyword async, in the function we make a call to the server using await and fetch this call then gives us back some data which we return. The async and await functions are important here:

The async and await keywords enable asynchronous, promise-based behaviour to be written in a asynchronous style, avoiding the need to explicitly configure promise chains.

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function

The function could also be written like this:

    function fetchPaymentIntentClientSecret(amount){
       return fetch(`/fetchPaymentIntent/${amount}`)
        .then(response => response.json()) // response.json also returns a promise since it has to wait for the response to finish before it can parse it
        .then(clientSecretObj => clientSecretObj.clientSecret); // extract the thing you need from the response
}
const fetchPaymentIntentCSPromise = fetchPaymentIntentClientSecret(amount)
    .then(clientSecret => confirmPayment(paymentRequest, clientSecret));

This means that fetchPaymentIntentClientSecret actually returns a promise. async and await are just syntactic sugar for the promises syntax. Using these keywords together, along with fetch allows us to make the asynchronous call to the server. So when we actually call the function, because it's a promise, we can chain the callbacks and really take advantage of the asynchronous nature. The clientSecret is returned from the server and we can pass that to the next function that needs it if the call is successful and if it's not, we can log the error instead.

All without the page being refreshed or modified.

A Note

You might have seen promise syntax that looks like

   function myFancyFunc() {
      // does something
   }

  const myFancyFuncPromise = new Promise(myFancyFunc)

and you're wondering why I haven't done that here. Well, the syntax is different if you're working with a promise-based API, which I am. In our example fetch returns a promise as does response.json so we need to treat them as such. new Promise is used to make promises out of async APIs which are not promise based, e.g. the callback based functions we defined earlier.

Why?

Within the context web development, promises are unique to JavaScript in that they're native. Coming from a Ruby background I found them strange, why not just do these things in a background job? But honestly, a small action like retrieving a client secret doesn't need to be done in a job (and probably shouldn't be) and it's probably not the best user experience to reload the page just to get a client secret, especially if the user hasn't triggered it.

Promises can also be quite complex to get your head around, this post is a primer but I'd encourage you to read more:

(Using Promises)[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises]
(Promise)[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise]

HTML and Templates & JavaScript Template Literals

Ada Rose Cannon 🏳️‍🌈 — Tue, 27 Oct 2020 09:01:45 +0000

HTML and Templates & JavaScript Template Literals

HTML in the Web is often made of reusable components, composed by templates, making it convenient to edit the different parts that make up a website. There are many templating languages used in the web such as handlebars, Pug, Vue and JSX; these are primarily used for composing HTML. Modern JavaScript has templating syntax built in which can use for all kinds of purposes including composing HTML.

In this post I will introduce the JavaScript syntax for templating and then show how it can be used in the real world for sanitising HTML and introducing some of the frameworks which use template literals for their templating.

Template Literals are a really nice JavaScript feature you may not have used much yet, they look a bit like strings:

const message = `Hello World`;

message === "Hello World"

You can include new lines:

const message = `Hello
World`;

message === "Hello\nWorld"

You can use the dollar-curly-brace ${} syntax to inject variables:

const name = 'Ada';

const message = `Hello ${name}`;

This works really well when combined with Arrow Function Expressions to make templating functions, which turn the arguments into a string:

const messageFn = name => `Hello ${name}`;

const message = messageFn("Ada");

Tagged Template Literals

You can put a tag on a template to transform the template before it gets turned into a string.

The tag is a function which is called with the first argument being an array of the rest of the arguments are the values of the place holders. In the example below we use the rest parameter to put all of the place holder arguments into an array.

There is always one more string than the number of placeholders. You can reassemble the output by interleaving these Arrays such that for a template with N placeholders the output is:

strings[0] + placeholders[0] + strings[1] + placeholders[1] + … + strings[N] + placeholders[N] + strings[N+1];

This is what is looks like in JavaScript:

function myTag(strings, ...placeholders) {
  const N = placeholders.length;
  let out = '';
  for (let i=0; i<N;i++) {
   out += strings[i] + placeholders[i];
  }
  out += strings[N];
  return out;
}

const message = myTag`Hello ${1} world ${2}.`

This function is equivalent to the String.raw function which is the default behaviour for template literals.


const message = String.raw`Hello ${1} world ${2}.`

You can also use String.raw inside your custom template tag to regenerate a string. In the example below we check the input to make sure it’s a string then use String.raw to output the data as a String.

function myTag(strings, ...placeholders) {

  for (const placeholder of placeholders) {
    if (typeof placeholder !== 'string') {
      throw Error('Invalid input');
    }
  }

  return String.raw(strings, ...placeholders);
}

Your tagged template literal doesn’t have to return a String it can return what ever you need, here is a very simple tag which measures the length of the input:

function myTag(a, ...b) {
  return String.raw(a, ...b).length;
}

HTML & Tagged Template Literals

Template literals are great for HTML because you can add newlines and very cleanly have dynamic classes and other attributes.

const myHTMLTemplate = (title, class) => `
  <!DOCTYPE html>
  <html>
    <head><title>${title}</title></head>
    <body class="${class}">
      ...
`;

If you use Visual Studio Code the Lit-HTML extension will add syntax highlighting and HTML intellisense features and emmet shortcuts for templates tagged with a tag called html . The html tag doesn’t have to be the one from the lit-html library even using String.raw will give you the really nice features of HTML inside a JavaScript or TypeScript file.

HTML syntax highlighting in a JS file

Sanitising HTML with a Tagged Template Literal

When you are outputting HTML that may contain user generated content you have to be careful about malicious JavaScript users may try into inject into all kinds of elements, these kinds of attacks are known as cross-site scripting aka XSS.

It’s best to strip out dangerous elements and attributes. You can do that in a template literal tag using a library like html-parser2.

We want to have two types of input into the placeholder, raw text strings which needs sanitising and safe HTML which is either authored by us or has been put through the sanitiser. This class just stores a string and we can use it to mark strings that are safe.

class SafeHTML {
    constructor (inStr) {
        this.string = inStr;
        this[Symbol.toPrimitive] = function (hint) {
            return this.string;
        }
    }
}

Then we have our template literal tag function, this does nothing to SafeHTML objects and sanitises raw strings returning a new SafeHTML from our template literal.

const html = (stringArray,...placeholders)=>{
    const sanitisedHTMLArray = placeholders.map(
        p => p instanceof SafeHTML ? p : stripHTML(p)
    );
    const out = String.raw(stringArray, ...sanitisedHTMLArray);
    return new SafeHTML(out);
}

To strip the HTML first I listed all the elements I wanted to allow and the attributes which are safe, these are mostly all used for formatting or semantics.

const allowedTagAttributes = {
 a: ["href"],
 b: [],
 i: [],
 img: ["src", "alt", "title"],
 abbr: ["title"],
 ul: [],
 li: [],
 h1: [],
 h2: [],
 h3: [],
 h4: [],
 h5: [],
 h6: [],
 hr: [],
 figure: [],
 figcaption: [],
 p: [],
 u: [],
 s: [],
 ruby: [],
 small: [],
 span: [],
 del: [],
 strong: [],
 table: [],
 thead: [],
 tbody: [],
 tr: [],
 td: [],
 time: [],
 ol: [],
};

const allowedTags = *Object*.keys(allowedTagAttributes);

Then we use htmlparser2 to go through the input text string and rebuild the HTML string using just the allowed elements:

function stripHTML(inStr) {
 const textOut = [];
 const parser = new htmlparser2.Parser(
  {

   onopentag(tagname, attribs) {
    if (allowedTags.includes(tagname)) {
     const allowedAttribs = allowedTagAttributes[tagname];
     if (tagname === "a") {
      attribs.href = sanitiseURL(attribs.href);
     }

     textOut.push(
      `<${tagname} ${
       allowedAttribs
       .map((key) => attribs[key] ? `${key}=${attribs[key]}` : "")
       .join(" ")}>`
     );
    }
   },

   ontext(text) {
    textOut.push(text);
   },

   onclosetag(tagname) {
    if (allowedTags.includes(tagname)) {
     textOut.push(`</${tagname}>`);
    }
   },

  },
  { decodeEntities: false }
 );

 parser.write(inStr);
 parser.end();
 return textOut.join("");
}

When we use the html tag function we just created we can now seperate our authored HTML from users unsafe HTML.

const unsafe = `<img onmouseenter="location.href='[https://example.com'](https://example.com')" src="[http://placekitten.com/200/300](http://placekitten.com/200/300)" />`;

const safeHTML = html`

<style>
div {
  color: red;
}
</style>

<div>User Content: ${unsafe}.</div>

`;

Using template literals with JS frameworks

If you need more functionality than basic templating there are some really light and fast frameworks which use template literals.

lit-html is pretty well known and designed to work with the polymer web component framework.
Polymer/lit-html
Efficient, Expressive, Extensible HTML templates in JavaScript Full documentation is available at… github.com

lighter-html is designed to be really fast and very small. It’s really well featured and a great way to build a really fast web site.
WebReflection/lighterhtml
Social Media Photo by Kristine Weilert on Unsplash The hyperHTML strength & experience without its complexity 🎉 I am… github.com

By Ada Rose Cannon on October 6, 2020.

Canonical link

DEV Community: Samsung Internet

Immersive Web, Docker and problem with symbolic links for SSL certificates.

Interactive Wall at GAM in Turin

Connecting to uncommon HID devices.

Portable Deployment

Let's Encrypt Certbot hints

You need to use bind mounts

Yes! That's all people!

From Bootstrap to Grid

Contents

The Bootstrap Way

The Problem

Inflexiblity

Obscures the CSS

Overbloat

CSS-Grid

What is a Column, What is a Row, What is a Cell?

Fractions (aka FR)

Gaps aka Gutters

Get Responsive without Media Queries

display: flex

Justify & Align Content

Combining CSS-Grid with Flexbox

Conclusion

Further Watching

The Trouble with `has_one`

Rails Associations

has_many

has_one

The Problem

The Fix

Further Reading

Making an AR Game with AFrame

Making an AR Game with AFrame

Setting up AFrame

Testing

Enabling AR features

When designing AR scenes, try to avoid having the content larger than 0.5m to enable people to fit it in their environment.

Adding hit testing

Creating the Basketball Hoop

Positioning the hoop

Adding physics to the scene

Dom Overlay

Read the source code to the finished demo

Promises for Rubyists

The Soundtrack

The Background

The Promise

Callbacks in Ruby

Callbacks in JavaScript

Implementation

A Note

Why?

HTML and Templates & JavaScript Template Literals

HTML and Templates & JavaScript Template Literals

Tagged Template Literals

HTML & Tagged Template Literals

Sanitising HTML with a Tagged Template Literal

Using template literals with JS frameworks

`display: flex`