What are Angular interceptors?

Interceptors are unique Angular services that we can implement to add behavior to HTTP requests in our application. HttpInterceptor provides a way to intercept HTTP requests and responses. In this sense, each interceptor can handle the request entirely by itself.

As the diagram above shows, the interceptors are always in the middle of an HTTP request. As middlemen, they allow us to perform operations on the requests on their way to and back from the server, making it a perfect place to centralize code for things like adding headers, passing tokens, caching, and error handling.

What is an error interceptor?

An error interceptor is a special kind of interceptor used for handling errors that happen when making HTTP requests. Errors come either from the client-side (browser) or the server-side when the request fails for some reason. If the request fails on the server, HttpClient returns an error object instead of a successful response. When an error occurs, you can inform the user by reacting to the error details, or in some cases, you might want to retry the request.

If you are looking into more ways of using interceptors, then this article has plenty of them:

• Top 10 ways to use Interceptors in Angular

Implementing the interceptor

To create an interceptor, declare a class that implements the intercept() method of the HttpInterceptor interface:

import {Injectable} from '@angular/core';
import {HttpEvent, HttpInterceptor, HttpHandler, HttpRequest} from '@angular/common/http';
import {Observable} from 'rxjs';

@Injectable()
export class ErrorInterceptor implements HttpInterceptor {

  intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    return next.handle(request);
  }
}

The intercept() method lets us inspect or alter a request. The next object represents the next interceptor in the chain of interceptors.

Providing the interceptor

The ErrorInterceptor is a service that we must provide before the app can use it:

@NgModule({
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: ErrorInterceptor, multi: true }
  ]
})
export class AppModule {}

Now that we set up the interceptor, we can start powering it up with some error handling capabilities.

The retry strategy

As an alternative to re-throwing errors, we can retry to subscribe to the errored out Observable. For example, network interruptions can happen in mobile scenarios, and trying again can produce a successful result. RxJS offers several retry operators. For example, the retry() operator automatically re-subscribes a specified number of times, in effect reissuing the HTTP request. The following example shows how to retry a failed request:

import {Injectable} from '@angular/core';
import {HttpEvent, HttpInterceptor, HttpHandler, HttpRequest} from '@angular/common/http';
import {Observable} from 'rxjs';
import {retry} from 'rxjs/operators';

@Injectable()
export class ErrorInterceptor implements HttpInterceptor {

  intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    return next.handle(request)
      .pipe(retry(3)); // Retry failed request up to 3 times.
  }
}

This strategy might save us from a few errors, but more often than not, it creates unneeded requests. Let’s see how we can minimize them.

Retry when?

To make our retry strategy smarter, we can use retryWhen(), which provides a mechanism for retrying errors based on custom criteria. We have three conditions for our smart retry:

• Retry twice at most
• Only retry 500 internal server errors
• Wait before retrying

With these conditions, we figure we give whatever is causing the exception a chance to recover and only retry to errors that can succeed if we try again.

import {Injectable} from '@angular/core';
import {HttpEvent, HttpHandler, HttpInterceptor, HttpRequest} from '@angular/common/http';
import {Observable, of, throwError} from 'rxjs';
import {mergeMap, delay, retryWhen} from 'rxjs/operators';

export const maxRetries = 2;
export const delayMs = 2000;

@Injectable()
export class ErrorInterceptor implements HttpInterceptor {

  intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> {
    return next.handle(request).pipe(
      retryWhen((error) => 
        return error.pipe(
          mergeMap((error, index) => {
            if (index < maxRetries && error.status == 500) {
              return of(error).pipe(delay(delayMs));
            }

            throw error;
          })
        )
      )
    )
  }
}

The index from mergeMap() tells us which try we are on to stop retrying when we reach our limit. We can then check the status of the exception. And depending on the error status, we can decide what to do. In this example, we retry twice with a delay when we get the error status 500. All remaining errors are re-thrown for further handling.

If you are interested in the whole picture, check out my article:

• Expecting the Unexpected — Best practices for Error handling in Angular

Conclusion

In this guide, we looked at different ways to handle failed HTTP requests using the power of RxJS. Applying different retry strategies can help us specify what should happen and when if the unexpected happens. All this might seem like a small detail, but saving users from errors will make both them, the support personnel, and in the end, the developers happy.

The form

We create a simplified form without any validation to add and edit medals. The medal has three properties:

export interface Medal {
  name: string;
  type: string;
  sport: string;
}

With reactive forms, the [formGroup] is a directive that we bind to and pass the form object in:

<h1 *ngIf="!medal">Add Medal</h1>
<h1 *ngIf="medal">Edit Medal</h1>

<form [formGroup]="form" (ngSubmit)="submit()">
  <label>Name</label>
  <input type="text" formControlName="name" /><br />

  <label>Type</label>
  <input type="text" formControlName="type" /><br />

  <label>Sport</label>
  <input type="text" formControlName="sport" /><br />

  <button type="submit">Submit</button>
</form>

We inject the FormBuilder service and use the group() method to create the form controls matching the template:

import { 
  ChangeDetectionStrategy, Component, EventEmitter, 
  Input, OnInit, OnChanges, Output, SimpleChanges
} from '@angular/core';
import { FormGroup, FormBuilder } from '@angular/forms';
import { Medal } from '../app.component';

@Component({
  selector: 'medal-form',
  templateUrl: 'medal-form.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class MedalFormComponent implements OnInit, OnChanges {
  @Input() medal: Medal;
  @Output() submitted = new EventEmitter<Medal>();
  form: FormGroup;

  constructor(private fb: FormBuilder) {}

  ngOnInit() {
    this.form = this.fb.group({
      name: [''],
      type: [null],
      sport: [null],
    });
  }

  ngOnChanges(changes: SimpleChanges) {
    if (changes.medal?.currentValue) {
      this.form?.patchValue(this.medal);
    }
  }

  submit() {
    this.submitted.emit(this.form.getRawValue());
    this.form.reset();
  }
}

We use the Input() decorator for the medal property. Then we use it when we have data that we can send to the child component. To watch for changes on an Input() property, we use the OnChanges lifecycle hook. Whenever it detects changes to the medal property, we populate the form with patchValue(). When submit is pressed, we emit the form values through the Output() property submitted.

We have implemented our reusable form component as a dumb component. Now let us talk more about the architecture we chose and how we use the form component we created.

The problem area

Let us first consider why we want to split into these two components. When using only one, we need to subscribe() to the observable data that Angular is keen for us to use. There are disadvantages to manually subscribing to observables. Some can lead to bugs that can be hard to debug. Using subscribe() also requires us to unsubscribe at the end of the component lifecycle to avoid memory leaks.

Subscribing to the observable manually in the ngOnInit() doesn't always work with the preferred OnPush change detection strategy out of the box. We sometimes need to tell Angular change detection manually when we want it to run. Needless to say, when someone comes to me for help with code where the data is not updating for some reason, the first thing I do is look for a subscribe() in the code.

Async pipe to the rescue?

The next, better solution is to use the async pipe. But, this also has some downsides. Objects have to be unwrapped, sometimes multiple times, in the template using *ngIf="data$ | async as data".

Properties unwrapped using *ngIf or *ngFor are not accessible in the component's methods. We have to pass these properties to the methods from the template as method parameters which makes the code harder to read. And let me not get started about the testing.

So how can we then solve this better?

Smart/dumb components

For a better architecture, we split components into two types of specialized components:

• Smart components: also known as container components.
• Dumb components: also known as presentation components.

The responsibility of the dumb component is to present the data, while the smart one is responsible for fetching and managing the data. Presentation components should be child components of the container components on your page.

Interaction between smart and dumb components is done by:

• Input -presentation component receives data from parent
• Output -presentation component triggers actions that parent listens to

By doing this, the presentation component remains isolated from the parent container component via a clearly defined interface.

Using the form

For the final piece of the puzzle, here are the ways we can use our presentational form as a create form:

<medal-form
  (submitted)="onSubmitted($event)"
></medal-form>

We don't send any data in, so we get an empty form from which we get notified when it is submitted. Then the only thing left for us to do is call the backend through our store or service.

In the edit form we fetch the data and send it into the form through an async pipe:

<medal-form 
  [medal]="medal$ | async"
  (submitted)="onSubmitted($event)"
></medal-form>

Now, we let the framework handle the subscriptions for us. The presentational component manages the data as objects instead of observables.

I have created a playground for you to play with the code. There is no data fetching or async pipe used, but it gives you an idea of how it works.

Conclusion

In this article, we combined two forms by making a presentational component. When we send it data with an async pipe, it receives the unwrapped object and populates the form with it. This architecture gives us a cleaner, more robust solution that hopefully keeps the bugs away.

Check out the code in my GitHub repository js-breakout or play the game!

If you like JavaScript games, you might like my article about Tetris:

• Learning Modern JavaScript with Tetris

When we talk about legendary games, Breakout is on the list. And not only because it is Atari’s single-player sequel to Pong, but also because both Steve Jobs and Steve Wozniak worked on it and later founded Apple with some of the money. By modern standards, the game is pretty simple but in 1976, the year I was born, it was revolutionary. Ten years later, the concept found new legs with Taito’s 1986 Arkanoid, which itself spawned dozens of imitators. The genre is known as block breaker games.

The game’s success continues to this day, and Atari continues to port it to new platforms. Indeed, you can find an official port on Android, iPhone, and iPad. Breakout is one of the most cloned games of all time. Let’s see if we can add to that statistics with the help of this course.

Game design

All Breakout-style games have at least three things in common — each contains paddles, balls, and bricks.

The player has to break through rows of brick walls by bouncing a ball against it with a paddle. The bricks are in different colors. Depending on the color, bricks can award more points and be harder to break. And to make the game more challenging, at some points in the game, the speed might increase. And as the final hurdle, the paddle can decrease its size when the player breaks through the last row. If the player loses the ball three times, it’s game over.

Getting started

Before starting with the game’s functionality, we need to create a basic structure to render the game inside. We can do this with HTML and the <canvas> element.

It’s good practice to split code into different files even if the project is not that big:

• index.html — The main file with links to the others. The order of the scripts that we add at the end is essential.
• styles.css — Contains the styles.
• breakout.js — JavaScript code for the game.

We can consider splitting the JavaScript into multiple files when it grows bigger.

HTML and CSS

The HTML document structure is quite simple, as the game renders on the <canvas> element. The only other part that we need to worry about is the button that starts the game.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Breakout Game</title>
  <link rel="stylesheet" type="text/css" href="styles.css" />
</head>
<body>
  <canvas id="breakout" width="600" height="400"></canvas>
  <br/>
  <button id="play-button" onclick="play()">Play</button>

  <script type="text/javascript" src="breakout.js"></script>
</body>
</html>

#breakout {
  background-color: black;
}

#play-button {
  background-color: green;
  padding: 0.5rem 1rem;
  cursor: pointer;
}

The JavaScript

At the end of the HTML file, we add references to our JavaScript files. <script> elements contain JavaScript code executed by the browser.

For now, we can add an empty function corresponding to the onclick event that we add to the play button:

function play() {}

With this, we have our game container styled and ready, awaiting code.

Canvas

Drawing graphics and creating animations in the browser can be done in a few different ways. In this course, we use HTML5 Canvas, with a feature set ideal for producing 2D and 3D games. The canvas element is defined in HTML code using width and height attributes. Then we can use the HTML5 Canvas API by writing JavaScript. We access the canvas through drawing functions to dynamically generate graphics.

Canvas context

The canvas has a 2D drawing context used for drawing shapes, text, images, and other objects. First, we choose the color and brush, and then we paint. We can change the brush and color before drawing or continue with what we have.

The HTMLCanvasElement.getContext() method returns a drawing context, where we render the graphics. By supplying '2d' as the argument we get the canvas 2D rendering context:

const ctx = canvas.getContext('2d');

There are other available contexts, like webgl for a three-dimensional rendering context, outside the scope of this article.

Coordinate system

The HTML canvas is a two-dimensional grid. The upper-left corner of the canvas has the coordinates (0, 0).

If you are interested in more detail about the Canvas, you can check my article:

• How to Get Started with Canvas Animations in JavaScript

Graphics

We can draw the ball using an image for a better-looking game. But, before we do that, we need to keep track of the position and other values connected to the ball. To do this, we can define a ball object. We start by defining the only constant value we know at the moment it will have, the radius:

const ball = {  
  radius: 10  
}

When the game starts, we want to give the ball some initial values, like its position. We define the starting x and y coordinates of the ball to the bottom center part of the canvas in the function resetBall() that we then call from the play() function:

function resetBall() {  
  ball.x = canvas.width / 2,  
  ball.y = canvas.height — 100  
}

It will be helpful later on to have a function for resetting the starting values for the ball instead of defining them in the ball object.

Next, we define the images we use for the ball and background. For each object property, we first create it as a new Image() and then set its src to the files we are using:

let images = {  
  background: new Image(),  
  ball: new Image()  
}

images.background.src = 'bg-space.webp';  
images.ball.src = 'ball.webp';

The images are in the WebP format, yielding smaller files of the same quality as PNG or JPEG.

To draw the images, we use drawImage(), which provides different ways to draw an image onto the canvas:

ctx.drawImage(image, x, y, width, height);

We provide the coordinates to the top left corner of the image and then the size of the image. For the background, we use the width and height of the canvas to have the background image cover the whole playing field. For the ball, we double the radius to get the diameter, which acts as both the width and height of the ball image:

// draw background  
ctx.drawImage(images.background, 0, 0, canvas.width, canvas.height);

// draw ball  
ctx.drawImage(images.ball, ball.x, ball.y, 2*ball.radius, 2*ball.radius);

Animation

Now that we know how to draw on the canvas, we are ready to take the next step — making the ball move. To do this, we paint the ball on the screen, clear it, and then draw it again in a different position. Doing animations on Canvas is like making a stop-motion movie. We move the objects a little bit in each frame to animate them.

Drawing loop

Canvas uses immediate rendering — when we draw, it immediately renders on the screen. But, it is a fire-and-forget system. After we paint something, the canvas forgets about the object and only knows it as pixels. So there is no object that we can move. Instead, we have to draw it again.

To do this, we need to define a drawing function that runs with a different set of variable values each time. We can run functions over and over again using a JavaScript timing function such as requestAnimationFrame(), which has some clear benefits over setInterval():

• It enables browser optimizations.
• It handles the frame rate.
• Animations only run when visible.

The way to animate with requestAnimationFrame() is to create a function that paints a frame and then schedules itself to invoke again. By doing this, we get an asynchronous loop that executes when we draw on the canvas. We invoke the paint() function repeatedly until we decide to stop.

function play() {
  // Start loop
  animate();
}

function animate() {
  // Paint frame
  paint();

  // Schedule next frame
  requestAnimationFrame(animate); 
}

We must remember to use the cancelAnimationFrame() method to cancel previously scheduled requests. If we forget to do this, we will notice the game going faster every time we press play since we will have more and more animation loops running in our code.

We can add the requestId to the game object and check for a value before running a new animation. And then, we set this variable each time we run a new requestAnimationFrame:

function play() {
  cancelAnimationFrame(game.requestId);
  resetBall();

  animate();
}

function animate() {
  paint();
  update();

  game.requestId = requestAnimationFrame(animate);
}

There is one more thing to do. We need to calculate how often the animation will progress a frame, otherwise the animation will run faster on high refresh rate screens.

Timer

We call the requestAnimationFrame() function when it’s time to update the animation for the next repaint. But to account for different screen refresh rates, we need to calculate if we should update our game at this call.

requestAnimationFrame(callback);

The callback function is passed one single argument, a DOMHighResTimeStamp similar to the one returned by performance.now(), indicating the point in time when requestAnimationFrame() starts to execute callback functions. We can use this timestamp to calculate when to paint and update our game.

First, we add a time object to keep track of everything related and set it in the resetGame() function:

function resetGame() {  
  game.time = {  
    start: performance.now(),  
    elapsed: 0,  
    refreshRate: 16  
  };  
}

We add a call to resetGame() in the play() function. Then in the animate loop, we add code that checks if the 16ms of the refreshRate have passed to see if it’s time to paint another frame:

function animate(timestamp) { 
  game.time.elapsed = timestamp - game.time.start;
  if (game.time.elapsed > game.time.refreshRate) {
    game.time.start = timestamp;

    paint();
    update();
  }    

  game.requestId = requestAnimationFrame(animate);
}

Now that we have a loop that keeps drawing the game at each frame, we need to change the position before the next paint.

Moving the ball

We defined the starting point at the bottom-center part of the Canvas with the coordinates of the ball object. After drawing the ball, we want to change the x and y to move it to a new position.

Without going too much into the math behind it we can use dx and dy to define the change. The larger the value of the change, the faster the ball moves.

The Greek letter Δ (delta) means the change in a variable.

We need a speed setting as a base for other movement-related variables. To speed up the game, we change this property.

When we launch the ball, it should be in a random upwards direction. If we always have the same trajectory, the game would get predictable fast. The ball moves upwards when dy has a negative value, so we set it to -speed. With Math.Random(), we can randomize the direction on the x-axis the ball shoots off:

function resetGame() {
  game.speed = 7;
  game.time = {start: performance.now(), elapsed: 0, refreshRate: 16};
}

function resetBall() {
  ball.x = canvas.width / 2;
  ball.y = canvas.height - 100;
  ball.dx = game.speed * (Math.random() * 2 - 1);  // Random trajectory
  ball.dy = -game.speed; // Up
}

Then we update x and y with with the change on every frame. The ball will be painted in the new position on every update. Adding these two lines gives us this update() function:

function update() {  
  ball.x += ball.dx;  
  ball.y += ball.dy;  
}

We call update() from the animate() function after painting the current frame. This way, we are prepared with the new positions for the next paint.

Before each new frame, we need to clear the canvas. We can do this with the CanvasRenderingContext2D.clearRect() method, which erases the pixels in a rectangular area by setting them to transparent black. But instead, we can start each new frame by drawing the background, which also clears everything from the previous frame. To keep our animate function clean, we can add all the code that has to do with drawing objects to the canvas to a paint() function:

function paint() {
  ctx.drawImage(images.background, 0, 0, canvas.width, canvas.height);
  ctx.drawImage(images.ball, ball.x, ball.y, 2*ball.radius, 2*ball.radius);
}

function animate() {
  paint();
  update();

  game.requestId = requestAnimationFrame(animate);
}

Each frame canvas clears by painting the background. Then we draw the ball before updating the x and y values for the next frame. By scheduling a new run of the animate() function with requestAnimationFrame() we create an animation loop.

Collision detection

In the previous chapter, we got the ball moving. But it quickly travels off the screen and ends the fun. We need to implement collision detection to make the ball bounce off the walls.

First, we need to calculate when a collision happens. After that, we need to think about which direction we were moving when we hit the target object. Then we can send the ball the opposite way after the hit.

Boundaries

For the ball to be inside the game field, all three of the following statements need to be true:

• X of the ball is greater than x of the left wall.
• X of the ball is less than x of the right wall.
• Y of the ball is greater than y of the roof.

The ball is drawn to the canvas at coordinates from the upper left corner. We need to consider the width of the ball. Therefore, we need to consider the ball width when checking for collisions on the opposing sides. The width, or the diameter, equals two times the radius of the ball (2r).

Detecting collisions

The first wall that the ball flies through is the right one. We can detect when the ball collides with it by checking when x is larger than the width of the canvas. In this case, we need to add 2*ball.radius since the collision happens with the right side of the ball.

When the collision happens, we make the ball move in the opposite direction by reversing the movement on the x-axis by negating the delta x (dx):

if (ball.x + 2 * ball.radius > canvas.width) {  
  ball.dx = -ball.dx;  
}

When we hit the left wall, we reverse the direction of the x-axis again. This time we check for when x is less than zero, where the x-axis starts. In this case, the collision happens with the left side of the ball, meaning we don’t need to change the x value:

if (ball.x < 0) {  
  ball.dx = -ball.dx;  
}

Lastly, we need to bounce off the roof. In this case, we reverse the movement on the y-axis when the y value goes below zero. The horizontal movement on the y-axis is represented by delta y:

if (ball.y < 0) {  
  ball.dy = -ball.dy;  
}

We add all these checks together into the function detectCollision():

function animate(timestamp) {
  game.time.elapsed = timestamp - game.time.start;
  if (game.time.elapsed > game.time.refreshRate) {
    game.time.start = timestamp;

    paint();
    detectCollision();
    update();
  }    

  game.requestId = requestAnimationFrame(animate);
}

function detectCollision() {
  if(ball.x + 2 * ball.radius > canvas.width || ball.x < 0) {
    ball.dx = -ball.dx;
  }

  if(ball.y < 0) {
    ball.dy = -ball.dy;
  }
}

This code does what it is supposed to, but it can be hard to read. To increase readability, we add function expressions that return the calculations. We also need to make sure the coordinates aren’t outside the playing area. So we make sure to move the coordinates back to the wall:

function detectCollision() {
  const hitTop = () => ball.y < 0;
  const hitLeftWall = () => ball.x < 0;
  const hitRightWall = () => ball.x + 2 * ball.radius > canvas.width;

  if (hitLeftWall()) {
    ball.dx = -ball.dx;
    ball.x = 0;
  }        
  if (hitRightWall()) {
    ball.dx = -ball.dx;
    ball.x = canvas.width - 2 * ball.radius;
    }
  if (hitTop()) {
    ball.dy = -ball.dy;
    ball.y = 0;
  }
}

That’s better! With this code implemented we have taken care of all the walls that we need the ball to bounce off. But as you might have noticed there is one collision that we have not taken care of yet.

Game over

When the ball falls down the floor, we don’t want it to bounce back, but instead, this is when we lose the game — Game over.

Before we schedule the next run of animate(), we check if the ball went out of bounds at the bottom of the court. If the game is lost, we show a message to the user. We write text on the screen by setting the fillStyle and telling what and where we want it with fillText(). Here, we compute the message to be in the middle of the canvas:

function animate(timestamp) { 
  game.time.elapsed = timestamp - game.time.start;
  if (game.time.elapsed > game.time.refreshRate) {
    game.time.start = timestamp;

    paint();
    update();
    detectCollision();

    if (isGameOver()) return;
  }

  requestId = requestAnimationFrame(animate);
}

function isGameOver() {
  const isBallLost = () => ball.y > canvas.height;

  if (isBallLost()) {
    gameOver();
    return true;
  }  
  return false;
}

function gameOver() {
  ctx.font = '40px Arial';
  ctx.fillStyle = 'red';
  ctx.fillText('GAME OVER', canvas.width / 2 - 100, canvas.height / 2);
}

We use the return statement to short-circuit the animate() loop. If isGameOver() returns true, we don’t request the next frame. Now, if we run the code, the ball bounces off the walls as it should, and we get a game over screen when the ball falls out of bounds.

Paddle

Now that we have a ball bouncing off the walls, it’s time to evolve this demo into a game by adding player interaction. Let’s add a paddle that the player can control and bounce the ball off!

As per usual we start by adding some variables to define a paddle object:

let paddle = {
  height: 20,
  width: 100,
  get y() { 
    return canvas.height - this.height; 
  }
}

The paddle moves at the bottom of the court, so the value on the y-axis is constant. There is a dependency on the height property of the same object, which means we need to use a getter.

However, we need to keep track of where on the x-axis the paddle is at each moment. We want the paddle to start in the middle of the court every time we start a new life or level, so we define a function resetPaddle() where we compute the x value:

function resetPaddle() {
  paddle.x = (canvas.width - paddle.width) / 2;
  paddle.dx = game.speed + 7;
}

Finally, the paddle has to be faster than the ball so that we have a chance to catch it, so we set dx for the paddle to an increment of the game speed.

Drawing the paddle

Next, we add the code needed to draw the paddle at each frame. We add a paddle property to our images object and set the src to the image of the paddle. Then we use drawImage() as with the background and ball in the paint() function to draw the paddle in the correct position on each frame:

let images = {
  background: new Image(),
  ball: new Image(),
  paddle: new Image() // New
}

images.background.src = 'bg-space.webp';
images.ball.src = 'ball.webp';
images.paddle.src = 'paddle.webp'; // New

function paint() {
  ctx.drawImage(images.background, 0, 0, canvas.width, canvas.height);
  ctx.drawImage(images.ball, ball.x, ball.y, 2 * ball.radius, 2 * ball.radius);
  ctx.drawImage(images.paddle, paddle.x, paddle.y, paddle.width, paddle.height); // New
}

Controlling the paddle

Now that we have added the drawing logic, we can start with the fun part — giving the user control over the paddle! We should hold the left and right arrow keys down to move the paddle. To achieve this, we need the following:

• Variables to store the state of the left and right keys.
• Event listeners to know when the keys are pressed and released.

We can add leftKey and rightKey to our game object with the default value of false since the buttons will not be pressed at the beginning of the game:

let game = {  
  speed: 8,  
  requestId: null,  
  leftKey: false,  
  rightKey: false
}

Next, we add event listeners for the keydown and keyup events. These will be listening for key presses and releases:

document.addEventListener('keydown', keyDownHandler);  
document.addEventListener('keyup', keyUpHandler);

When you press a key on your keyboard, the keydown event fires and invokes the keyDownHandler() function. As the key is released, the keyup event fires and invokes the keyUpHandler() function. The following code defines these functions and the keys we use for the left and right movements:

function keyDownHandler(e) {
  if (e.key === 'ArrowRight') {
    game.rightKey = true;
  } else if (e.key === 'ArrowLeft') {
    game.leftKey = true;
  }
}

function keyUpHandler(e) {
  if (e.key === 'ArrowRight') {
    game.rightKey = false;
  } else if (e.key === 'ArrowLeft') {
    game.leftKey = false;
  }
}

Both functions take an event as a parameter, represented by the e variable. The key property holds the information about the key that was pressed. Modern browsers use ArrowRight and ArrowLeft for the left/right arrow keys. When we press a key down, the relevant variable is set to true. When the key is released, the variable is changed back to false.

Moving the paddle

Now that we have set up the variables, events, and functions to update the variables, we can use these pressed variables to update the x position of the paddle to move it on the screen. We can do this in the update() function where we change the x coordinate if the left or right keys are pressed:

function update() {
  ball.x += ball.dx;
  ball.y += ball.dy;

  if (game.rightKey) {
    paddle.x += paddle.dx;
    if (paddle.x + paddle.width > canvas.width){
      paddle.x = canvas.width - paddle.width;
    }
  } 
  if (game.leftKey) {
    paddle.x -= paddle.dx;
    if (paddle.x < 0){
      paddle.x = 0;
    }
  }

If the keys are pressed, we update the paddle.x variable by adding or subtracting the paddle.dx. We also need to check if we have reached the walls, and in those cases, we keep the x variable at these minimum and maximum values.

Bounce ball off the paddle

Lastly, we have to add collision detection for the paddle. When the ball hits the paddle, it should bounce off it back into the playing area.

To do this, we can check whether the ball has reached the paddle and is between the left and right edges of the paddle. Since we measure the ball from the top-left corner, we need to add 2*radius when we check whether the ball has reached the paddle or not. This is why we must update the values for the coordinates before checking for collisions. Likewise, when we check if the ball is hitting the paddle on the horizontal plane, we must remember the radius in our calculations:

function detectCollision() {
  const hitTop = () => ball.y < 0;
  const hitLeftWall = () => ball.x < 0;
  const hitRightWall = () => ball.x + 2 * ball.radius > canvas.width;
  const hitPaddle = () =>
    ball.y + 2 * ball.radius > canvas.height - paddle.height &&
    ball.y + ball.radius < canvas.height && 
    ball.x + ball.radius > paddle.x &&
    ball.x + ball.radius < paddle.x + paddle.width;

  if (hitLeftWall()) {
    ball.dx = -ball.dx;
    ball.x = 0;
  }        
  if (hitRightWall()) {
    ball.dx = -ball.dx;
    ball.x = canvas.width - 2 * ball.radius;
  }
  if (hitTop()) {
    ball.dy = -ball.dy;
    ball.y = 0;
  }
  if (hitPaddle()) {
    ball.dy = -ball.dy;
    ball.y = canvas.height - paddle.height - 2 * ball.radius;
  }
}

Running the code, we can control the paddle and use it to bounce the ball.

Bricks

Bouncing the ball off the walls is fun and all but gets boring fast. What we need is something to destroy! And this is what we are doing in this lesson by creating a field of bricks.

Defining the bricks

First, we need to set up some variables to define the bricks. Add the following lines to your code to create a brick configuration object:

let brick = {  
  rows: 5,  
  cols: 10,  
  get width() {  
    return canvas.width / this.cols;  
  },  
  height: 30  
}

Here we define the number of rows and columns of bricks and their height. We use a getter to compute the width of the bricks depending on the number of columns.

Brick field

We hold all our bricks in an array called brickField. It contains all the brick objects with position and size to paint each brick on the screen. We initialize the array with row and column loops. Then we add a brick to the brickField array in each iteration with the following properties:

• x position
• y position
• height
• width
• color
• points
• hitsLeft

We calculate the x and y coordinates from the row and column together with the width and height of bricks. The topMargin leaves some space at the top of the canvas that we will be using later.

Here we set the color by the row, but we could be even more creative when creating new levels. The points are also dependent on the row, giving more points for each row of bricks we get through. Bricks can withstand hits and sometimes require more than one hit before being destroyed. Here we set the bricks on the top row to disappear after two hits with the hitsLeft property:

function initBricks() {
  brickField = [];
  const topMargin = 30;
  const colors = ['red', 'orange', 'yellow', 'blue', 'green'];

  for(let row = 0; row < brick.rows; row++) {
    for(let col = 0; col < brick.cols; col++) {
      brickField.push({
        x: col * brick.width,
        y: row * brick.height + topMargin,
        height: brick.height,
        width: brick.width,
        color: colors[row],
        points: (5 - row) * 2,
        hitsLeft: row === 0 ? 2 : 1
      });
    }
  }
}

The code above will loop through the rows and columns and create the new brick objects that we add into the array of bricks.

Drawing the bricks

Now let’s create a function to draw the bricks. First, we check if hitsLeft is more than zero, which means the brick is still visible. If it has hits left, it’s drawn on the screen. We then set the color from the brick properties before using fillRectangle() and strokeRectangle() to paint the bricks:

function drawBricks() {
  brickField.forEach((brick) => {
    if (brick.hitsLeft) {
      ctx.fillStyle = brick.color;
      ctx.fillRect(brick.x, brick.y, brick.width, brick.height);
      ctx.strokeRect(brick.x, brick.y, brick.width, brick.height);
    }
  });
}

Then we need to add a call to drawBricks() in the paint() function to draw the field of bricks in every frame.

Brick collisions

Now that we have made the bricks appear on the screen, it’s time to make them disappear when we hit them with the ball.

When we check for collisions between the ball and bricks, we first check if the ball is inside the brick. Then we check from which direction the ball hit the brick to know what direction change to make.

For the ball to be inside the brick, all four of the following statements need to be true:

• The x position of the ball is greater than the x position of the brick.
• The x position of the ball is less than the x position of the brick plus its width.
• The y position of the ball is greater than the y position of the brick.
• The y position of the ball is less than the y position of the brick plus its height.

To start, we want to create a collision detection function that loops through all the bricks, comparing the ball with its position. For better readability of the code, we define a function expression isBallInsideBrick with all our calculations:

function detectBrickCollision() {
  const isBallInsideBrick = (brick) => 
    ball.x + 2 * ball.radius > brick.x &&
    ball.x < brick.x + brick.width && 
    ball.y + 2 * ball.radius > brick.y && 
    ball.y < brick.y + brick.height;

  brickField.forEach((brick) => {
    if (brick.hitsLeft && isBallInsideBrick(brick)) {
      brick.hitsLeft--;
      if (brick.hitsLeft === 1) {
        brick.color = 'darkgray';
      }
    }
  });
}

As we saw earlier, when we drew the bricks, we know if the brick is visible or not with the hitsLeft property. We decrease it when the brick gets hit. We also set the color to grey for the top row that requires two hits before being destroyed.

We have the bricks disappearing now when we hit them, but it would also be nice if the ball changes direction as we do so.

Collision direction

To bounce the ball in the right direction after a collision, we need to know what side of the brick the ball hit.

We can calculate if the ball was coming from the left or right by removing the change ball.dx and find out if the ball was on the left or right side of the brick before impact. If this is true, we negate the dx to make the ball bounce back from where it was coming:

// Check if ball is inside from left side
ball.x + 2 * ball.radius            > brick x
// Decrease by dx and check if position was on left side of brick x
ball.x + 2 * ball.radius - ball.dx <= brick.x;

// Similarly for right side
ball.x            < brick.x + brick.width
ball.x - ball.dx >= brick.x + brick.width

If neither of these cases is true, then we know that the ball hit the brick on the top or bottom, and in that case, we negate ball.dy to make the ball bounce back.

Sometimes we hit multiple bricks in the same frame. If we, for example, hit two bricks from the bottom and change the direction twice, the ball will be traveling right through the bricks. For this reason, we need to have a variable directionChanged that keeps track so that we only change direction once per frame:

function detectBrickCollision() {
  let directionChanged = false;
  const isBallInsideBrick = (brick) =>
    ball.x + 2 * ball.radius > brick.x &&
    ball.x < brick.x + brick.width && 
    ball.y + 2 * ball.radius > brick.y && 
    ball.y < brick.y + brick.height;

  brickField.forEach((brick) => {
    if (brick.hitsLeft && isBallInsideBrick(brick)) {
      brick.hitsLeft--;
      if (brick.hitsLeft === 1) {
        brick.color = 'darkgray';
      }

      if (!directionChanged) {
        directionChanged = true;
        detectCollisionDirection(brick);
      }
    }
  });
}

function detectCollisionDirection(brick) {
  const hitFromLeft = () => ball.x + 2 * ball.radius - ball.dx <= brick.x;
  const hitFromRight = () => ball.x - ball.dx >= brick.x + brick.width;

  if (hitFromLeft() || hitFromRight()) {
    ball.dx = -ball.dx;
  } else { // Hit from above or below
    ball.dy = -ball.dy;
  }
}

The last thing to do is to add a call to the detectBrickCollision() function to our animate() function, just below the collisionDetection() call. With these changes, we can break bricks. And when we hit one, the ball bounces as expected.

Score, levels, and lives

Now that we can destroy the bricks, the game is ready to award points for hitting them and keep a count of the total score. And when all the bricks get obliterated, the game should continue to the next level. And wouldn’t it be nice to have more than one life to get another chance when we can’t catch the ball?

Game variables

To keep track of all of these new states in the game, we add them to the game object. Since these values need to reset at the start of each game, we add them to the resetGame() function:

function resetGame() {  
  game.speed = 8;  
  game.score = 0;  
  game.level = 1;  
  game.lives = 3;
}

Display text

Drawing text on a canvas is similar to drawing a shape. First, we set the size and type of the font. Next, we use fillStyle to set the color of the font and finally fillText() to tell what text and where we want to display on the canvas.

The next step is to show all these new variables on the screen so that the player has current information available at all times. Let’s add a drawScore() function that creates and updates the display with the level and score:

function drawScore() {
  ctx.font = '16px Arial';
  ctx. fillStyle = 'white';
  const { level, score } = game;
  ctx.fillText(`Level: ${level}`, 5, 20);
  ctx.fillText(`Score: ${score}`, canvas.width / 2 - 50, 20);
}

The code above prints the current level and the number of points at the top of the screen.

Lives left

We could also write the lives with text, but to make it fancier, we can show a tiny paddle for each life that we have remaining. We can do this by using the same image as for the paddle and drawing it for each life we have left:

function drawLives() {
  if (game.lives > 2) ctx.drawImage(images.paddle, canvas.width - 150, 9, 40, 13);
  if (game.lives > 1) ctx.drawImage(images.paddle, canvas.width - 100, 9, 40, 13);
  if (game.lives > 0) ctx.drawImage(images.paddle, canvas.width - 50, 9, 40, 13);
}

Now, a small paddle shows up on the right top of the screen for each of our lives. To use the functions we created for the game information, we add calls to them in the draw() function:

function draw() {
  ctx.drawImage(images.background, 0, 0, canvas.width, canvas.height);
  ctx.drawImage(images.ball, ball.x, ball.y, 2 * ball.radius, 2 * ball.radius);
  ctx.drawImage(images.paddle, paddle.x, paddle.y, paddle.width, paddle.height);
  drawBricks();
  drawScore(); // New
  drawLives(); // New
}

Updating values

Now that we display all of our variables on the screen, we need to update them to add to the score and levels while at the same time keeping track of the lives we lose.

Score

Remember when we added what each brick is worth in points in the last chapter? The time has come to add those to our total score each time we destroy one.

To increase the score, we add the points that the brick is worth every time we hit one in detectBrickCollisions():

game.score += brick.points;

Now, that was easy! The next value is a bit more complicated.

If you want to add a high score list, read my article:

• How to Save High Scores in Local Storage

Levels

When there are no more bricks, we proceed to the next level. There are no more bricks left when all the bricks have hitsLeft equal to zero. How can we check all elements in an array for a specific value of a property?

The array method best suited for this is every(). It can check whether all elements in the array pass the tests we provide. Check for when there are no bricks left, and in that case, go to the next level:

function isLevelCompleted() {
  const levelComplete = brickField.every((b) => b.hitsLeft === 0);

  if (levelComplete) {
    initNextLevel();
    resetBall();
    resetPaddle();
    initBricks();
    game.timeoutId = setTimeout(() => animate(), 3000);

    return true;
  }
  return false;
}

function initNextLevel() {
  game.level++;
  game.speed++;
  ctx.font = '40px Arial';
  ctx.fillStyle = 'yellow';
  ctx.fillText(`LEVEL ${game.level}!`, canvas.width / 2 - 80, canvas.height / 2);
}

We add a call to isLevelCompleted() in the animate() function that exits before requesting a new frame if the level has been completed:

if (isLevelCompleted() || isGameOver()) return;

When we have no more bricks left, we increase the game.level. When we get better at Breakout, the starting speed gets too easy. And too easy means boring. We increase the difficulty by increasing the game.speed when we advance levels.

Then we reset the playing field, with the result that the ball and paddle move a bit faster on the new level. Remember that we stop the animations if the level completes? The reason is that we want to show a screen for a few seconds before continuing the game. We use setTimeout() and set the number of milliseconds to pause before continuing the game.

Similarly, as we did with cancelAnimationFrame(), we add clearTimeout(game.timeoutId) to the beginning of the play() function to make it possible to start a new game between levels without another animation loop starting up.

Lives

Lastly, we alter the gameOver() function to check whether we have lives left before going to the game over. We decrease lives, and when we reach zero, the game is over. Otherwise, we get a new ball by calling resetBall():

function isGameOver() {
  const isBallLost = () => ball.y - ball.radius > canvas.height;

  if (isBallLost()) {
    game.lives -= 1;
    if (game.lives === 0) {
      gameOver();
      return true;
    }
    resetBall();
    resetPaddle();
  }
  return false;
}

Sound

No game is complete until we at least add some sound effects. There are many free websites to find sound samples to use. I selected some from freesound.org.

We are going to add sound effects for:

• The ball hitting the paddle
• The ball hitting a brick
• Ball launch
• Game over
• Level completed

The Audio() constructor creates and returns a new HTMLAudioElement which can be used to play the audio:

const audioElement = new Audio(url);  
audioElement.play();

An optional DOMString contains the URL of the audio file:

const sounds = {
  ballLost: new Audio('./sounds/ball-lost.mp3'),
  breakout: new Audio('./sounds/breakout.mp3'),
  brick: new Audio('./sounds/brick.mp3'),
  gameOver: new Audio('./sounds/game-over.mp3'),
  levelCompleted: new Audio('./sounds/level-completed.mp3'),
  music: new Audio('./sounds/music.mp3'),
  paddle: new Audio('./sounds/paddle.mp3')
}

We add sounds similar to how we created images, except we can add the URL in the constructor.

Now we can play these elements when finding where in the code they belong. For example, we add the gameOver sound to the gameOver() function. Sometimes we hit multiple bricks. To start the sound over when we hit the next brick, we set currentTime to zero:

sounds.brick.currentTime = 0;  
sounds.brick.play();

You might have noticed that we added music in the sounds object. The game music starts when we press start and ends at game over. Since we don’t want the music to end we set it to repeat:

sounds.music.loop = true;

We can set the volume of the audio between 0 and 1. To be sure the music is not too loud at the start we can set it a bit lower than max:

sounds.music.volume = 0.5;

We could also add some keyboard triggers into the keyDownHandler to toggle the music on and off and to control the volume. With all the sounds in place, we truly have something starting to resemble a complete game.

Conclusion

Today we learned how to create a complete game with the HTML Canvas and JavaScript. I hope you enjoyed the article and learned something new.

Resources

• GitHub repository with js-breakout.
• How to Get Started with Canvas Animations in JavaScript
• How to Save High Scores in Local Storage
• Learning Modern JavaScript with Tetris

With baby steps. 👣

In this article, we learn to draw and animate objects using HTML5 Canvas and JavaScript before we optimize for performance.

“Animation is not the art of drawings that move but the art of movements that are drawn.” — Norman McLaren

Banner photo by Justin Lim on Unsplash

Introduction

Apple introduced canvas in 2004 to power applications and the Safari browser. A few years later it was standardized by the WHATWG. It comes with finer-grained control over rendering but with the cost of having to manage every detail manually. In other words, it can handle many objects, but we need to code everything in detail.

The canvas has a 2D drawing context used for drawing shapes, text, images, and other objects. First, we choose the color and brush, and then we paint. We can change the brush and color before every new drawing, or we can continue with what we have.

Canvas uses immediate rendering: When we draw, it immediately renders on the screen. But, it is a fire-and-forget system. After we paint something, the canvas forgets about the object and only knows it as pixels. So there is no object that we can move. Instead, we have to draw it again.

Doing animations on Canvas is like making a stop-motion movie. In every frame need to move the objects a little bit to animate them.

Canvas element

The HTML <canvas> element provides a blank container on which we can draw graphics. We can draw shapes and lines on it via the Canvas API, which allows for drawing graphics via JavaScript.

A canvas is a rectangular area on an HTML page that by default has no border or content. The default size of the canvas is 300 pixels × 150 pixels (width × height). However, custom sizes can be defined using the HTML height and width property:

<canvas id="canvas" width="600" height="300"></canvas>

Specify the id attribute to be able to refer to it from a script. To add a border, use the style attribute or use CSS with the class attribute:

<canvas id="canvas" width="600" height="300" style="border: 2px solid"></canvas>
<button onclick="animate()">Play</button>

Now that we added the border we see the size of our empty canvas on the screen. We also have a button with an onclick event to run our animate() function when we click it.

We can place our JavaScript code in <script> elements that we place into the document <body> after the <canvas> element:

<script type="text/javascript" src="canvas.js"></script>

We get a reference to the HTML <canvas> element in the DOM (Document Object Model) with the getElementById() method:

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

Now we have the canvas element available but cannot draw directly on it. Instead, the canvas has rendering contexts that we can use.

Canvas context

The canvas has a 2D drawing context used for drawing shapes, text, images, and other objects. First, we choose the color and brush, and then we paint. We can change the brush and color before every new drawing, or we can continue with what we have.

The HTMLCanvasElement.getContext() method returns a drawing context, where we render the graphics. By supplying '2d' as the argument we get the canvas 2D rendering context:

const ctx = canvas.getContext('2d');

There are other available contexts, like webgl for a three-dimensional rendering context, that is outside the scope of this article.

The CanvasRenderingContext2D has a variety of methods for drawing lines and shapes on the canvas. To set the color of the line we use strokeStyle and to set the thickness we use lineWidth:

ctx.strokeStyle = 'black';
ctx.lineWidth = 5;

Now, we are ready to draw our first line on the canvas. But, before we do that we need to understand how we tell the canvas where to draw. The HTML canvas is a two-dimensional grid. The upper-left corner of the canvas has the coordinates (0, 0).

   X →
Y [(0,0), (1,0), (2,0), (3,0), (4,0), (5,0)]
↓ [(0,1), (1,1), (2,1), (3,1), (4,1), (5,1)]
  [(0,2), (1,2), (2,2), (3,2), (4,2), (5,2)]

So, when we say we want to moveTo(4, 1) on the canvas it means we start at the upper-left corner (0,0) and move four columns to the right and one row down.

Drawing 🔵

Once we have a canvas context, we can draw on it using the canvas context API. The method lineTo() adds a straight line to the current sub-path by connecting its last point to the specified (x, y) coordinates. Like other methods that modify the current path, this method does not directly render anything. To draw the path onto a canvas, you can use the fill() or stroke() methods.

ctx.beginPath();      // Start a new path
ctx.moveTo(100, 50);  // Move the pen to x=100, y=50.
ctx.lineTo(300, 150); // Draw a line to x=300, y=150.
ctx.stroke();         // Render the path

We can use fillRect() to draw a filled rectangle. Setting the fillStyle determines the color used when filling drawn shapes:

ctx.fillStyle = 'blue';
ctx.fillRect(100, 100, 30, 30); // (x, y, width, height);

This draws a filled blue rectangle:

Animation 🎥

Now, let's see if we can get our block to move on the canvas. We start by setting the size of the square to 30. Then, we can move the x value to the right with steps of size and draw the object over and over again. We move the block to the right until it reaches the canvas end:

const size = 30;
ctx.fillStyle = 'blue';

for (let x = 0; x < canvas.width; x += size) {
  ctx.fillRect(x, 50, size, size);
}

OK, we were able to draw the square as we wanted. But we have two issues:

1. We are not cleaning up after ourselves.
2. It's too fast to see the animation.

We need to clear away the old block. What we can do is erase the pixels in a rectangular area with clearRect(). By using the width and height of the canvas, we can clean it between paints.

for (let x = 0; x < canvas.width; x += size) {
  ctx.clearRect(0, 0, canvas.width, canvas.height); // Clean up
  ctx.fillRect(x, 50, size, size);
}

Great! We fixed the first problem. Now let's try to slow down the painting so we can see the animation.

You might be familiar with setInterval(function, delay). It starts repeatedly executing the specified function every delay milliseconds. I set the interval to 200 ms, which means the code runs five times a second.

let x = 0;
const id = setInterval(() => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);      
  ctx.fillRect(x, 50, size, size);
  x += size;

  if (x >= canvas.width) {
    clearInterval(id);
  }
}, 200);

To stop a timer created by setInterval(), we need to call clearInterval() and give it the identifier for the interval to cancel. The id to use is the one that is returned by setInterval(), and this is why we need to store it.

We can now see that if we press the button, we get a square that moves from left to right. But, if we press the play button several times, we can see that there is a problem animating multiple squares at the same time.

Every square gets its interval that clears the board and paints the square. It's all over the place! Let's see how we can fix this.

Multiple objects

To be able to run the animations for several blocks, we need to rethink the logic. As of now, each block gets its animation method with setInterval(). Instead, we should manage the moving objects before sending them to be drawn, all at once.

We can add a variable started to only start setInterval() on the first button click. Every time we press the play button, we add a new value 0 to a squares array. This is enough for this simple animation but for something more complex we could create a Square object with the coordinates and eventual other properties like color.

let squares = [];
let started = false;

function play() {
  // Add 0 as x value for object to start from the left.
  squares.push(0);

  if (!started) {
      started = true;
      setInterval(() => {
        tick();
      }, 200)
  }
}

function tick() {
  // Clear canvas
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  // Paint objects
  squares.forEach(x => ctx.fillRect(x, 50, size, size));

  squares = squares.map(x => x += size) // move x to right
      .filter(x => x < canvas.width);  // remove when at end
}

The tick() function clears the screen and paints all the objects in the array every 200ms. And by having only one interval, we avoid the flicker we had before. And now we get better animations:

What we did here is the first step of making a game loop. This loop is the heart of every game. It's a controlled infinite loop that keeps your game running ;  it's the place where all your little pieces get updated and drawn on the screen.

🚶Optimize animations 🏃

Another option for animating is to use requestAnimationFrame(). It tells the browser that you wish to perform an animation and requests the browser to call a function to update an animation before the next repaint. In other words, we tell the browser: "Next time you paint on the screen, also run this function because I want to paint something too."

The way to animate with requestAnimationFrame() is to create a function that paints a frame and then schedules itself to invoke again. With this, we get an asynchronous loop that executes when we draw on the canvas. We invoke the animate method over and over again until we decide to stop. So, now we instead call the animate() function:

function play() {
  // Add 0 as x value for object to start from the left.
  squares.push(0);

  if (!started) {
      animate();
  }
}

function animate() {
  tick();
  requestAnimationFrame(animate);  
}

If we try this out we notice that we can see the animation, which was not the case with setInterval(), even though it's super fast. The number of callbacks is usually 60 times per second.

The requestAnimationFrame() method returns an id that we use for canceling the scheduled animation frame. To cancel a scheduled animation frame, you can use the cancelAnimationFrame(id) method.

To slow down the animation we need a timer to check the elapsed time since the last time we called the tick() function. To help us, the callback function is passed an argument, a DOMHighResTimeStamp, indicating the point in time when requestAnimationFrame() starts to execute callback functions.

let start = 0;

function animate(timestamp) {    
  const elapsed  = timestamp - start;
  if (elapsed > 200) {
    start = timestamp;
    tick();
  }
  requestAnimationFrame(animate);  
}

With this, we have the same functionality as we had earlier with setInterval().

So, in conclusion, why should we use requestAnimationFrame() instead of setInterval()?

• It enables browser optimizations.
• It handles the frame rate.
• Animations only run when visible.

Conclusion

In this article, we created an HTML5 Canvas and used its 2D rendering context and JavaScript to draw on the canvas. We got introduced to some of the methods available in the canvas context and used them to render different shapes.

Finally, we were able to animate multiple objects on the canvas. We learned how to use setInterval() to create an animation loop that manages and draws the objects on the screen. We also learned how to optimize animations with requestAnimationFrame().

With this intro to canvas animations, we have taken our first steps into game development. We are ready to start on a real game next:

1. Converting to numbers

JavaScript is a loosely typed language, meaning we don't have to explicitly specify types of variables. JavaScript also freely type-converts values into a type depending on the context of their use.

Converting values to numbers, especially strings to numbers, is a common requirement and many methods can be used.

Unary + operator

The most concise method for type-converting strings into numbers is the unary + operator:

+"42"  // 42

A unary operation is an operation with only one operand. This operand comes either before or after the operator.

The unary plus operator precedes its operand and evaluates to its operand but attempts to convert it into a number if it isn't already. Here are a few more examples of how it behaves:

+true  // 1
+false // 0
+null  // 0

But, what if we want to be more explicit in our code?

Number

Number is a primitive wrapper object used to represent and manipulate numbers. When used as a function, Number(value) converts a string or other value to the Number type. If the value can't be converted, it returns NaN (Not a Number).

Number('42')   // 42
Number('1.3')  // 1.3
Number('tax')  // NaN

parseInt

parseInt() takes a String as a first argument and a base to which that String will be converted to. This method always returns an integer.

parseInt('1234', 10)       // 1234
parseInt('11 players', 10) // 11
parseInt('player 2', 10)   // NaN
parseInt('10.81', 10)      // 10

parseInt() tries to get a number from a string that does not only contain a number, but if the string does not start with a number, you’ll get NaN.

parseFloat

If we want to retain the decimal part and not just the integer part, we can use parseFloat() that takes a String as an argument and returns the Float point number equivalent.

parseFloat('10.42') // 10.42
parseFloat('10.00') // 10

There are a few more ways to convert to numbers but these are the more common ones.

2. Managing objects

Destructuring is a huge part of ES6 and something you're probably going to be using often. It allows us to extract data from objects, and assigning the extracted data into variables:

const rectangle = { h: 100, w: 200 };
const { h, w } = rectangle;

We can rename the variables if we want to:

const { h: height, w: width} = rectangle;
console.log(height); // 100

Another handy thing we could do is to destructure the returned object by a function and pick and choose what values we want to use:

function getPerson() {
  return {
    firstName: 'Max',
    lastName: 'Best',
    age: 42
  }
}

const { age } = getPerson();
console.log(age); // 42

So, with destructuring, we can return multiple values from a function by returning an object and choosing the pieces we want to be returned.

Removing a property in an immutable way requires a little trick provided by spread’s counterpart, the rest operator, which is written with three dots (...) like spread. However, in this case, we spread the remaining properties into a new object.

const { age:_ , ...person } = getPerson();

console.log(person); // {firstName: "Max", lastName: "Best"}

Now the person object holds all properties from the original person object except age.

3. Swapping two variables

Using what we learned in the last trick makes swapping variables as easy as:

let me = 'happy', you = 'sad';
[me, you] = [you, me];
// me = 'sad', you = 'happy'

The above code creates an array of [you, me] and immediately destructures them into the opposite variables.

No need for temp variables anymore!

4. Setting defaults

We have all seen them. The endless if statements checking if the values have been set. What if I said there was a better way? Well, that's exactly what I'm saying, default values.

Variables

The nullish coalescing operator (??) is a logical operator that returns its right-hand side operand when its left-hand side operand is null or undefined and otherwise returns its left-hand side operand. We can use this to set default values, for example when we receive a list that has not been set to an array yet:

const bookList = receivedBooks ?? [];

Parameters

We could use the null coalescing operator to set defaults for variables in functions but there is a better way, default parameters:

function calculateArea(width, height = 100) {
    return width * height;
}

const area = calculateArea(50);
console.log(area); // 5000

Here we set the default value for height to 100 and calculate the area by only sending in the width.

Objects

Another trick when destructruring objects is setting default values:

const rectangle = { height: 400 };
const { height = 750, width = 500 } = rectangle;
console.log(height); // 400 - comes from rectangle object
console.log(width);  // 500 - fallback to default

ES6 destructuring default values only kick in if the value is undefined.

5. Random number from interval

There are times when we need a random number to be generated within a range. The Math.random() function helps us generate a random number, and then we can transform it to the range we want:

const randomIntFromInterval = (min, max) => Math.floor(Math.random() * (max - min + 1) + min);

There's another trick baked into this one if you look at how the function is constructed.

6. Remove array duplicates

The Set object type introduced in ES6 lets you store unique values. Together with the spread operator (...), we can use it to create a new array with only the unique values:

const uniqueArray = [...new Set(array)]

We create a Set from an array and because each value in the Set has to be unique we remove all duplicates. We then convert the Set back to a new array using the spread operator.

7. Dynamic property names

ES6 brought us computed property names that allow property keys of object literals to use expressions. By surrounding the key with brackets [], we can use variables as property keys:

const type = "fruit";
const item = {
  [type]: "kiwi"
};

console.log(item); // {fruit: "kiwi"}

This is useful in a situation where you want the key to be created on the fly.

We can access the value with bracket notation:

item[type];   // "kiwi"
item["fruit"] // "kiwi"

Or with dot notation:

item.fruit; // "kiwi"

8. Bonus trick

If we want to add a new item to an array without mutation (which we usually want to avoid), we can create a new array using the ES6 spread operator and slice.

const insert = (arr, index, newItem) => [
  ...arr.slice(0, index), // first half of array
  newItem,                // new item
  ...arr.slice(index)     // rest of array
];

const items = ['S', 'L', 'C', 'E']

const result = insert(items, 2, 'I');

console.log(result); // ["S", "L", "I", "C", "E"]

9.

Why was 6 afraid of 7?

Because 7 ate 9.

Conclusion

I hope you find some of these JavaScript tricks useful and worth adding to your everyday arsenal. And remember, being responsible is far more important than being efficient.

We go through the three ways one by one with examples to discover how JavaScript has evolved in this area in recent years. However, before looking into these techniques, let’s look into the difference between synchronous and asynchronous code.

Synchronous code

JavaScript is a single-threaded programming language, which means only one thing can happen at a time. While a single thread simplifies writing and reasoning about code, this also has some drawbacks.

Imagine we do a long-running task like fetching a resource over the network. Now we block the browser until the resource is downloaded. This can make for a bad user experience and might result in the user leaving our page.

When we execute code synchronously, we wait for it to finish before moving to the next task. Nothing else can happen while each operation is being processed — rendering is paused.

Let’s write some code to clarify:

function logFunction() {
  console.log('in logFunction');
}

console.log('Start');
logFunction();
console.log('End');

// -> Start
// -> in logFunction
// -> End

This code executes as expected.

1. We log “Start”.
2. We execute the function which logs “in logFunction”
3. We log “End”.

So, synchronous tasks must be aware of one another and be executed in sequence.

Asynchronous code

That’s where asynchronous JavaScript comes into play. Using asynchronous JavaScript, we can perform long-lasting tasks without blocking the main thread. When we execute something asynchronously, we can move to another task before it finishes.

The event loop is the secret behind JavaScript’s asynchronous programming. JavaScript executes all operations on a single thread, but using a few clever data structures gives us the illusion of multi-threading. If you want to understand what happens under the hood in the following examples, you should read more about the concurrency model and the event loop.

Let’s do another example, this time using setTimeout(), that allows us to wait a defined number of milliseconds before running its code:

console.log('Start');

setTimeout(() => {
  console.log('In timeout');
}, 1000); // Wait 1s to run

console.log('End');

// -> Start
// -> End
// -> In timeout

Did you expect “In timeout” to be logged before “End”? We are not blocking the code execution but instead, we continue and come back to run the code inside setTimeout one second later.

Let’s look at another example. When we fetch an image from a server, we can’t return the result immediately. That means that the following wouldn’t work:

let response = fetch('myImage.png'); // fetch is asynchronous
let blob = response.blob();

That’s because we don’t know how long the image takes to download, so when we run the second line, it throws an error because the response is not yet available. Instead, we need to wait until the response returns before using it.

Let’s look at how we would solve this with asynchronous code.

Callbacks

This approach to asynchronous programming is to make slow-performing actions take an extra argument, a callback function. When the slow action finishes, the callback function is called with the result.

As an example, the setTimeout function waits a given number of milliseconds before calling a function. We can simulate slow asynchronous tasks without calling the backend this way:

setTimeout(() => console.log('One second later.'), 1000);

While the concept of callbacks is great in theory, it can lead to confusing and difficult-to-read code. Just imagine making callback after callback:

getData(function(a) {
  getMoreData(a, function(b) {
    getMoreData(b, function(c) { 
      getMoreData(c, function(d) { 
       // ...
      });
    });
  });
});

Nested callbacks going several levels deep are sometimes called callback hell. Each new callback level makes the code more difficult to understand and maintain. Using callbacks is not common these days, but if we get unlucky we might find them in legacy code bases.

Next, we look into how modern JavaScript has tried to solve this problem.

Promises

Promises, introduced with ES6, are a new way of dealing with asynchronous operations in JavaScript. A promise is an object that might produce a value in the future. Just like in real life, we don’t know if the promise will be kept and we use the promise object as a placeholder while we wait for the outcome.

const promise = new Promise();

Having an object as a proxy for future values lets us write the code in a synchronous manner. We get the promise object and continue executing the code. But, there is a bit more to it, as we will see.

The promise constructor takes one argument, a callback with two parameters, one for success (resolve) and one for fail (reject). We need to either resolve a promise if it’s fulfilled or reject it if it failed:

const promise = new Promise((resolve, reject) => { 

  // Do stuff

  if (/* fulfilled */) {
    resolve('It worked!');
  } else {
    reject(Error('It failed!'));
  } 
});

States

A promise in JavaScript is similar to a promise in real life. It will either be kept, (fulfilled), or it won’t (rejected).

A promise can be:

• pending — Initial state, not fulfilled or rejected yet.

• fulfilled — The operation succeeded. resolve() was called.

• rejected — The operation failed. reject() was called.

• settled— Has fulfilled or rejected.

After a promise is settled it can not change its state anymore.

Resolve

Let’s create a promise and resolve it:

const promise = new Promise((resolve, reject) => {
  resolve('We are done.');
});

console.log(promise);
// -> Promise {<fulfilled>: "We are done."}

We can see that resolving the promise resulted in a fulfilled state.

Now that we have created a promise, let’s see how to use it.

Then

To access the value passed by the resolve or reject functions, we can use then(). It takes two optional arguments, a callback for a resolved case and another for a rejected one.

In this case, we get its resolved value by using the then() method:

const promise = new Promise((resolve, reject) => {
  resolve('We are done.');
});

promise.then((result) => console.log(result));
// -> We are done.

A promise can only resolve or reject once.

Chaining

Since then() returns a new promise, it can be chained. Like synchronous code, chaining results in a sequence that runs in serial.

Consider this simplified example where we fetch some data:

fetch(url)
 .then(processData)
 .then(saveData)
 .catch(handleErrors);

Assuming each function returns a promise, saveData() waits for processData() to complete before starting, which in turn waits for fetch() to complete. handleErrors() only runs if any of the previous promises reject.

The possibility of chaining is one of the advantages of using Promises compared to callbacks.

Error handling

When a promise rejects, the control jumps to the closest rejection handler. The catch() doesn’t have to be immediately after, it may instead appear after one or multiple then().

const promise = new Promise((resolve, reject) => {
  reject('We failed.');
});

promise
  .then((response) => response.json())
  .catch((error) => console.log(error));
// -> We failed.

We should end all promise chains with a catch().

Promises are commonly used when fetching data over a network or doing other kinds of asynchronous programming in JavaScript and have become an integral part of modern JavaScript.

Next, let’s take a look at async/await.

Async and Await

Async functions and the await keyword, new additions with ECMAScript 2017, act as syntactic sugar on top of promises allowing us to write synchronous-looking code while performing asynchronous tasks behind the scenes.

Async

First, we have the async keyword. We put it in front of a function declaration to turn it into an async function.

async function getData(url) {}

Invoking the function now returns a promise. This is one of the traits of async functions — their return values are converted to promises.

Async functions enable us to write promise-based code as if it were synchronous, but without blocking the execution thread and instead operating asynchronously.

However, async alone does not make the magic happen. The next step is to use the await keyword inside the function.

Await

The real advantage of async functions becomes apparent when you combine them with the await keyword. Await can only be used inside an async block, where it makes JavaScript wait until a promise returns a result.

let value = await promise

The keyword await makes JavaScript pause at that line until the promise settles and returns its result, and then resumes code execution.

It’s a more elegant syntax of getting the result from a promise than promise.then().

Fetch

fetch() allows us to make network requests similar to XMLHttpRequest (XHR). The main difference is that the Fetch API uses promises, which enables a simpler and cleaner API, avoiding callbacks.

The simplest use of fetch() takes one argument — the path to the resource — and returns a promise containing the response.

async getData(url) {
 const data = await fetch(url);
 return data;
}

In our code, we now wait for fetch() to return with the data before we return it from the function.

Now, we have our function ready. Remember, since it returns a promise, we need to use then() to get hold of the value.

getData(url).then((data) => console.log(data));

Or we could even write this shorthand:

getData(url).then(console.log);

We have all the basics of expected behavior figured out now, but what if something unexpected happens?

Error handling

If await promise is rejected, it throws the error, just as if there were a throw statement at that line. We can catch that error using try/catch, the same way as in regular code where an error is thrown.

async getData(url) {
  try {
    const data = await fetch(url);
    return data;
  } catch(error) {
    // Handle error
  }
}

If we don’t have the try/catch, the promise generated by calling the async function becomes rejected. We can append catch() to handle it:

getData(url).catch(alert);

If we don’t add a catch(), we get an unhandled promise error. We could catch such errors using a global error handler.

Example with fetch

For testing purposes, it’s often a good idea to start by making the data available locally. We can do this by creating a json file with the data. Since we can use fetch() to get the data from it just like we would do with a remote call it’s easy to replace the URL from local to remote.

We can’t use fetch directly on the file system so we need to run a webserver to serve our file.

Http-server

If we don’t have a web server on our machine, we can use the simple, zero-configuration command-line http-server. You need Node.js installed on your machine. Npx is a tool for executing Node packages, and we can use it to run our server:

npx http-server

It serves files from the folder we run the command from. When the server starts, it tells you which address to go to in your browser to run the application:

Now that we are serving the file, we can start the actual coding.

Fetch

First, we create a file data.json where we can save the data in JSON format. Next, we write an async function `getData()` to get the data from the local json file:

async function getData() {
  const data = await fetch('data.json')
    .then((response) => response.json())
    .catch((error) => console.log(error))
  || [] // Default if file is empty;

  return data;
}

The response from fetch is an HTTP response, not the actual JSON. To extract the JSON body content from the response, we use the json() method. Running the code retrieves the data from the local file.

Conclusion

When we have code that doesn’t complete immediately, we need to wait for it to finish before continuing. This is where asynchronous JavaScript comes in. We looked into the differences between synchronous and asynchronous JavaScript and how we first tried solving it with callbacks.

Next, we learned about promises, and how they solve some of the problems we had with callbacks. Promises are commonly used when fetching data over a network or doing other kinds of asynchronous programming in JavaScript. They have become an integral part of modern JavaScript and as such, are important for JavaScript developers to master.

Async/await provides a nice, simplified way to write async code that is simpler to read and maintain. The async keyword tells that functions return a promise rather than directly returning the value. The await keyword can only be used inside an async block, where it makes JavaScript wait until a promise returns a result.

I hope that after reading this, you have a better understanding of asynchronous JavaScript and the different techniques we can use to implement it.

We then set up an application with Angular internationalization and go through the complete process from marking texts for translation, extracting them to translation files, and how we manage these files to get the application deployed and maintained while keeping users all over the world happy with our translations.

And speaking of international, if you prefer reading in Spanish:

• Cómo mantener las traducciones de una app Angular con i18n

Illustration by Vero Karén

Internationalization and localization

It’s easy to get confused with the terms internationalization (i18n) and localization (i10n), and where to draw the line between them. Internationalization is the process of designing your application so that it can be adapted to different locales around the world while localization is the process of building the versions of the applications to different locales.

Together they help us in adapting software to different languages and local variations in the look and feel expected by the target audience.

How localization works with Ivy

The new localization process of Angular Ivy is based on the concept of tagged templates. Tags allow you to parse template literals with a function. The tag used here is the global identifier $localize. Instead of translating the strings, the Ivy template compiler converts all template text marked with i18n attributes to $localize tagged strings.

So when we add:

<h1 i18n>Hello World!</h1>

It will be compiled to $localize calls and somewhere in the compiled code we will be able to find:

$localize`Hello World!`

The way the tagged template works is that you put the function that you want to run against the string before the template. Instead of function(), you have function`` or as in this case $localize`` .

When this step is done we have two choices:

• compile-time inlining: the $localize tag is transformed at compile time by a transpiler, removing the tag and replacing the template literal string with the translation.

• run-time evaluation: the $localize tag is a run-time function that replaces the template literal string with translations loaded at run-time.

In this article, we use compile-time inlining to achieve our goals. At the very end of the build process, we run a step for the translation files by providing an option flag to get a localized application for the languages. Since we are doing the translations compile-time we get one application per locale.

At the end of the article, we take a further look into run-time evaluation.

Because the application does not need to be built again for each locale, the build process is much faster than before v9 of Angular.

You can read more about this in Angular localization with Ivy from where this picture is.

Now that we understand the process of building the application we start to get an understanding of what it entails.

The good and the bad

The standard Angular internationalization and localization are designed to produce one compiled application per language. By doing this we get optimal performance since there is no overhead of loading translation files and compiling them at run-time. But, this also means that each language has to be deployed to a separate URL:

www.mydomain.com/en
www.mydomain.com/nb
www.mydomain.com/fi

This means we need to do a bit more set up on our webserver. A limitation with ng serve is that it only works with one language at a time and to run different languages also needs some configuration. To run all languages locally we need to use a local webserver. We look into how we do all this in this article.

Angular i18n uses XLIFF and XMB formats that are XML-based, more verbose formats than JSON. But since these files are used at compile-time it doesn’t matter. It makes sense to use JSON when we load the translation files at run-time to keep the file sizes smaller. The formats chosen for the built-in i18n are used by translation software which helps us with our translations as we will see.

The number one drawback that people find with this solution is that you need to reload the application when you switch languages. But, is this really going to be a problem for you? People usually switch languages once if ever. And that couple of seconds it takes to reload applications will not be a problem.

Having one bundle per language is not a problem for a web SPA other than that you have to configure your web server for this. But for standalone apps, this means you got to make the user download every translated bundle, or distribute a different app for every version.

It’s important to understand your requirements before deciding which route to take.

Transloco

If the standard Angular i18n doesn’t give you what you want then the best alternative today in my opinion is Transloco. It’s being actively maintained and has an active community. It will get you up and running faster and is more flexible than the built-in solution. Since Transloco is runtime translation you have just www.mydoman.com and can change localization on the fly.

So, before choosing which way to go in such a fundamental choice you should check Transloco out to see if it would be a better fit for you.

OK, enough technicalities let’s see some code!

Add localize to Angular project

@angular/localize package was released with Angular 9 and supports i18n in Ivy applications. This package requires a global $localize symbol to exist. The symbol is loaded by importing the @angular/localize/init module.

To add the localization features provided by Angular, we need to add the @angular/localize package to our project:

ng add @angular/localize

This command:

• Updates package.json and installs the package.

• Updates polyfills.tsto import the @angular/localize package.

If you try using i18n without adding this package you get a self-explanatory error message reminding us to run ng add @angular/localize.

Translating templates

To translate templates in our application, we need first to prepare the texts by marking them with the i18n attribute.

i18n is a custom attribute from the WebExtensions API. It’s recognized by Angular tools and compilers. During the compilation, it is removed, and the tag content is replaced with the translations.

We mark the text like this:

<span i18n>Welcome</span>

This <span> tag is now marked and ready for the next step in the translation process.

Translating TypeScript files

NB! You need Angular 10.1 or later to extract strings from source code (.ts) files.

It’s not only our templates that need to be translated. Sometimes we have code in our TypeScript files that also need a translation. To localize a string in the source code, we use the $localize template literal:

title = $localize`My page`;

Note that template literals use the backtick (`) character instead of double or single quotes.

Extracting texts

When our application is prepared to be translated, we can use the extract-i18n command to extract the marked texts into a source language file named messages.xlf.

The command options we can use are:

• --output-path: Change the location of the source language file.

• --outFile: Change the file name.

• --format: Change file format. Possible formats are XLIFF 1.2 (default), XLIFF 2, and XML Message Bundle (XMB).

Running this command from the root directory of the project:

ng extract-i18n

We get the messages.xlf file looking like this:

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en-US" datatype="plaintext" original="ng2.template">
    <body>
      <trans-unit id="3492007542396725315" datatype="html">
        <source>Welcome</source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">7</context>
        </context-group>
      </trans-unit>
      <trans-unit id="5513198529962479337" datatype="html">
        <source>My page</source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.ts</context>
          <context context-type="linenumber">9</context>
        </context-group>
      </trans-unit>
    </body>
  </file>
</xliff>

We can see that we have the texts “Welcome” and “My page” in the file but what does it all mean?

• trans-unit is the tag containing a single translation. id is a translation identifier that extract-i18n generates so don’t modify it!

• source contains translation source text.

• context-group specifies where the given translation can be found.

• context-type="sourcefile" shows the file where translation is from.

• context-type="linenumber" tells the line of code of the translation.

Now that we have extracted the source file, how do we get files with the languages we want to translate?

Create translation files

After we have generated the messages.xlf file, we can add new languages by copying it and naming the new file accordingly with the associated locale.

To store Norwegian translations we rename the copied file to messages.nb.xlf. Then we send this file to the translator so that he can do the translations with an XLIFF editor. But, let’s not get ahead of us and first do a manual translation to get a better understanding of the translation files.

Translating files manually

Open the file and find the <trans-unit> element, representing the translation of the <h1> greeting tag that was previously marked with the i18n attribute. Duplicate the <source>...</source> element in the text node, rename it to target, and then replace its content with the Norwegian text:

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en-US" datatype="plaintext" original="ng2.template">
    <body>
      <trans-unit id="3492007542396725315" datatype="html">
        <source>Welcome</source>
        <target>Velkommen</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">7</context>
        </context-group>
      </trans-unit>
      <trans-unit id="5513198529962479337" datatype="html">
        <source>my page</source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.ts</context>
          <context context-type="linenumber">9</context>
        </context-group>
      </trans-unit>
    </body>
  </file>
</xliff>

This is all that there is to it to add the translations to the files. Let’s see how we do it with an editor.

Translating files with an editor

Before we can use an editor, we need to provide the translation language. We can do this by adding the target-language attribute for the file tag so that translation software can detect the locale:

<file source-language="en-US" datatype="plaintext" original="ng2.template" target-language="nb">

Let’s open this file in a translation tool to see what we are working with. I’m using the free version of PoEdit in this article:

This looks much easier to work with than the manual way. We even get some suggestions for translations. Let’s translate “my page” and save the file. If we then open messages.nb.xlf we can see that it has added the translation in a target block like when we did it manually:

<source>My page</source>
<target state="translated">Min side</target>

We see that it added state="translated" to the target tag. This is an optional attribute that can have the values translated, needs-translation, or final. This helps us when using the editor to find the texts that are not yet translated.

This is a great start but before we try out the translations in our application, let’s see what more we can do by adding more information into the box in the screenshot named “Notes for translators”.

Notes for translators

Sometimes the translator needs more information about what they are translating. We can add a description of the translation as the value of the i18n attribute:

<span i18n="Welcome message">Welcome</span>

We can add even more context to the translator by adding the meaning of the text message. We can add the meaning together with the description and separate them with the | character: <meaning>|<description>. In this example we might want to let the translator know that this welcome message is located in the toolbar:

<span i18n="toolbar header|Welcome message">Welcome</span>

The last part that we can add to the value of the i18n attribute is an ID by using @@. Be sure to define unique custom ids. If you use the same id for two different text messages, only the first one is extracted, and its translation is used in place of both original text messages.

Here we add the ID toolbarHeader:

<span i18n="toolbar header|Welcome message@@toolbarHeader">Welcome</span>

If we don’t add an ID for the translation, Angular will generate a random ID as we saw earlier. Running ng extract-i18n again we can see that the helpful information has been added to our translation unit:

<trans-unit id="toolbarHeader" datatype="html">
  <source>Welcome</source>
  <context-group purpose="location">
    <context context-type="sourcefile">src/app/app.component.html</context>
    <context context-type="linenumber">7</context>
  </context-group>
  <note priority="1" from="description">Welcome message</note>
  <note priority="1" from="meaning">toolbar header</note>
</trans-unit>

• There are now a couple of note tags that provide the translation description and meaning and the id is no longer a random number.

If we copy these to the messages.ng.xlf file and open it in PoEdit we see that all these are now visible in “Notes for translators”:

Providing context in TypeScript files

Like with Angular templates you can provide more context to translators by providing meaning, description, and id in TypeScript files. The format is the same as used for i18n markers in the templates. Here are the different options as found in the Angular Docs:

$localize`:meaning|description@@id:source message text`;
$localize`:meaning|:source message text`;
$localize`:description:source message text`;
$localize`:@@id:source message text`;

Adding an id and description to our title could look like this:

title = $localize`:Header on first page@@firstPageTitle:My page`;

If the template literal string contains expressions, you can provide the placeholder name wrapped in : characters directly after the expression:

$localize`Hello ${person.name}:name:`;

Specialized use cases

There are some specialized use cases for translations that we need to look at. Attributes can easily be overlooked but are also important to translate, not least for accessibility.

Different languages have different pluralization rules and grammatical constructions that can make translation difficult. To simplify translation, we can use plural to mark the uses of plural numbers and select to mark alternate text choices.

Attributes

Apart from the usual suspects of HTML tags, we need to also be aware that we need to translate HTML attributes. This is especially important when we are making our applications accessible to all people.

Let’s take the example of an img tag. People using a screen reader would not see the picture but instead, the alt attribute would be read to them. For this reason and others, provide a useful value for alt whenever possible.

<img [src]="logo" alt="Welcome logo" />

To mark an attribute for translation, add i18n- followed by the attribute that is being translated. To mark the alt attribute on the img tag we add i18n-alt:

<img [src]="logo" i18n-alt alt="Welcome logo" />

In this case, the text “Welcome logo” will be extracted for translation.

You can also assign a meaning, description, and custom ID with the i18n-attribute="<meaning>|<description>@@<id>" syntax.

Plurals

Pluralization rules between languages differ. We need to account for all potential cases. We use the plural clause to mark expressions we want to translate depending on the number of subjects.

For example, imagine we do a search and want to show how many results were found. We want to show “nothing found” or the number of results appended with “items found”. And of course, let’s not forget about the case with only one result.

The following expression allows us to translate the different plurals:

<p i18n>
{itemCount, plural, =0 {nothing found} =1 {one item found} other {{{itemCount}} items found}}
</p>

• itemCount is a property with the number of items found.

• plural identifies the translation type.

• The third parameter lists all the possible cases (0, 1, other) and the corresponding text to display. Unmatched cases are caught by other. Angular supports more categories listed here.

When we translate plural expression we have two trans units: One for the regular text placed before the plural and one for the plural versions.

Alternates

If your text depends on the value of a variable, you need to translate all alternatives. Much like plural, we can use the select clause to mark choices of alternate texts. It allows you to choose one of the translations based on a value:

<p i18n>Color: {color, select, red {red} blue {blue} green {green}}</p>

Based on the value of color we display either “red”, “blue”, or “green”. Like when translating plural expressions we get two trans units:

<trans-unit id="7195591759695550088" datatype="html">
  <source>Color: <x id="ICU" equiv-text="{color, select, red {red} blue {blue} green {green}}"/></source>
  <context-group purpose="location">
    <context context-type="sourcefile">src/app/app.component.html</context>
    <context context-type="linenumber">12</context>
  </context-group>
</trans-unit>
<trans-unit id="3928679011634560837" datatype="html">
  <source>{VAR_SELECT, select, red {red} blue {blue} green {green}}</source>
  <context-group purpose="location">
    <context context-type="sourcefile">src/app/app.component.html</context>
    <context context-type="linenumber">12</context>
  </context-group>
</trans-unit>

The editors understand these units and help us with the translations:

Interpolation

Let’s combine a welcome message the title property:

<h1 i18n>Welcome to {{ title }}</h1>

This places the value of the title variable that we earlier translated in the text. When we extract this text we see how the interpolation is handled:

<source>Welcome to <x id="INTERPOLATION" equiv-text="{{ title }}"/></source>

For the translation the <x.../> stays the same for the target language:

<target>Velkommen til <x id="INTERPOLATION" equiv-text="{{ title }}"/></target>

And that’s the last example of translations that we are looking at. Now, let’s see how we can get this applications up and running with our new language!

Configuring locales

To be able to run our application in many languages we need to define the locales in the build configuration. In the angular.json file, we can define locales for a project under the i18n option and locales, that maps locale identifiers to translation files:

"projects": {
  "i18n-app": {
    "i18n": {
      "sourceLocale": "en-US",
      "locales": {
        "nb": "messages.nb.xlf"
      }
   }
}

Here we added the configuration for the Norwegian language. We provide the path for the translation file for the locale "nb". In our case, the file is still in the root directory.

The sourceLocale is the locale you use within the app source code. The default is en-US so we could leave this line out or we could change it to another language. Whatever value we use here is also used to build an application together with the locales we define.

To use your locale definition in the build configuration, use the "localize" option in angular.json to tell the CLI which locales to generate for the build configuration:

• Set "localize" to true for all the locales previously defined in the build configuration.

• Set "localize" to an array of a subset of the previously-defined locale identifiers to build only those locale versions.

The development server only supports localizing a single locale at a time. Setting the "localize" option to true will cause an error when using ng serve if more than one locale is defined. Setting the option to a specific locale, such as "localize": ["nb"], can work if you want to develop against a specific locale.

Since we want to be able to ng serve our application with a single language, we create a custom locale-specific configuration by specifying a single locale in angular.json as follows:

"build": {
  "configurations": {
    "nb": {
      "localize": ["nb"]
    }
  }
},
"serve": {
  "configurations": {
    "nb": {
      "browserTarget": "ng-i18n:build:nb"
    }
  }
}

With this change we can serve the Norwegian version of the app and make sure the translations are working by sending in nb to the configuration option:

ng serve --configuration=nb

We can also build the app with a specific locale:

ng build --configuration=production,nb

Or with all the locales at once:

ng build --prod --localize

In other words, it’s more flexible to configure it the way we did but we could also have just set localize and aot to true and be done with it.

Run multiple languages locally

For performance reasons, running ng serve only supports one locale at a time. As we saw earlier we can serve the specific languages by sending in the locale to the configuration option. But, how can we run the application with all the configured languages?

Multiple languages

To run all languages simultaneously we need first to build the project. We can build applications with the locales defined in the build configuration with the localize option:

ng build --prod --localize

When the build is localized and ready we need to set up a local webserver to serve the applications. Remember we have one application per language, which is what makes this a bit more complex.

In Angular Docs, there are a couple of examples of server-side code that we can use.

Nginx

To get our application up and running we need to:

1. Install Nginx

2. Add config from Angular Docs to conf/nginx.conf

3. Build our applications

4. Copy applications to the folder defined in root in nginx.conf.

5. Open browser in localhost

The port is set in listen and is normally set to 80. You change languages by changing the URL. We should now see our Norwegian application at localhost/nb.

Here is an example of the nginx.conf file:

events{}
http {
  types {
    module;
  }
  include /etc/nginx/mime.types;

  # Expires map for caching resources
  map $sent_http_content_type $expires {
    default                    off;
    text/html                  epoch;
    text/css                   max;
    application/javascript     max;
    ~image/                    max;
  }

  # Browser preferred language detection
  map $http_accept_language $accept_language {
    ~*^en en;
    ~*^nb nb;
  }

  server {
      listen       80;
    root         /usr/share/nginx/html;

    # Set cache expires from the map we defined.
    expires $expires;

    # Security. Don't send nginx version in Server header.
    server_tokens off;

    # Fallback to default language if no preference defined by browser
    if ($accept_language ~ "^$") {
      set $accept_language "nb";
    }

    # Redirect "/" to Angular app in browser's preferred language
    rewrite ^/$ /$accept_language permanent;

    # Everything under the Angular app is always redirected to Angular in the correct language
    location ~ ^/(en|nb) {
      try_files $uri /$1/index.html?$args;

      # Add security headers from separate file
      include /etc/nginx/security-headers.conf;
    }

    # Proxy for APIs.
    location /api {
      proxy_pass https://api.address.here;
    }
  }
}

If we use Nginx in production, it makes sense to also test our application locally with it.

Deploy to production

If you are using Nginx in production, then you already have the language configuration setup. If not, you need to find out what changes you need for your particular server configuration.

We have to take into consideration if we are running the application locally or in production. We can do this by using isDevMode, which returns whether Angular is in development mode:

isDevMode() ? '/' : `/${locale}/`;

So, when we are running the application locally with ng serve we don’t add the locale to the URL as we do when we have localized the application in the production build.

Maintaining the application

Usually, when the application has been deployed it’s time to end the article. This time I wanted to address a few more things before ending. Let’s start by looking into what challenges we run into when going into maintenance mode.

The biggest challenge is the handling of the translation files. We need to make sure that the marked texts find their way to the translators and back to the application before it’s deployed. To help with this we need to find a way to automate the generation of translation files and get notified when we have missing translations.

Generating the translation files

It’s not sustainable to keep merging the translation files manually. We need some automation! To implement this, I’m using a free tool called Xliffmerge.

Since this tool has old Angular versions as peerDependencies we need to use --legacy-peer-deps if we are using a new version of NPM (v7) that would otherwise fail on installation.

The documentation for Xliffmerge is targeting older versions of Angular, but after some experimentation, I found it enough to install the @ngx-i18nsupport/tooling package:

npm install -D @ngx-i18nsupport/tooling --legacy-peer-deps

Note that -D installs to devDependencies, and for use in a CI pipeline, you should omit it to use in dependencies.

Then we can add new languages to the configurations in angular.json under projects -> projectName -> architect -> xliffmerge.

"xliffmerge": {
  "builder": "@ngx-i18nsupport/tooling:xliffmerge",
  "options": {
    "xliffmergeOptions": {
      "defaultLanguage": "en-US",
      "languages": ["nb"]
    }
  }
}

After adding new translations, we can extract them and migrate them to our translation files by running this script:

ng extract-i18n && ng run projectName:xliffmerge

We get a couple of warnings running the script which tells us its working!

WARNING: merged 1 trans-units from master to "nb"
WARNING: please translate file "messages.nb.xlf" to target-language="nb"

After this, you can distribute the language files to the translators. And when the translations finish, the files need to be merged back into the project repository.

Just a word of caution that this library was not being actively maintained at the time of this writing, so you might want to look into other options. There is an Angular issue on merging translated files. Go and upvote it if you think this is something that we need!

Missing Translations

Another way to make sure the translations are valid is to get noticed if translations are missing. By default, the build succeeds but generates a warning of missing translations. We can configure the level of the warning generated by the Angular compiler:

• error: An error message is displayed, and the build process is aborted.

• warning (default): Show a Missing translation warning in the console or shell.

• ignore: Do nothing.

Specify the warning level in the options section for the build target of your Angular CLI configuration file, angular.json. The following example shows how to set the warning level to error:

"options": {
  "i18nMissingTranslation": "error"
}

If you run the application and no translation is found, the application displays the source-language text. We have to make a decision here on how important the translations are. If they are crucial then we should break the build to make sure we get all translations delivered.

Format data based on locale

Languages are not the only thing to take into consideration when localizing applications. A couple of the more obvious things we need to think about is how we present dates and numbers to our local customers.

In Angular, we provide the LOCALE_ID token to set the locale of the application and register locale data with registerLocaleData(). When we use the --localize option with ng build or run the --configuration flag with ng serve, the Angular CLI automatically includes the locale data and sets the LOCALE_ID value.

With the LOCALE_ID set to the correct locale, we can use the built-in pipes of Angular to format our data. Angular provides the following pipes:

• DatePipe: Formats a date value.

• CurrencyPipe: Transforms a number to a currency string.

• DecimalPipe: Transforms a number into a decimal number string.

• PercentPipe: Transforms a number to a percentage string.

For example, {{myDate | date}} uses DatePipe to display the date in the correct format. We can also use the pipes in TypeScript files as long as we provide them to the module.

Runtime translations

When we run ng serve --configuration=xx or ng build --localize then the application is compiled and translated before we run it. However, if we don’t tell Angular to localize our application, then the $localize tags are left in the code, and it’s possible to instead do the translation at runtime.

This means that we can ship a single application and load the translations that we want to use before the application starts. There is a function loadTranslations in @angular/localize that can be used to load translations, in the form of key/value pairs, before the application starts.

Since the translations have to be called before any module file is imported, we can put it in polyfills.ts. You could also use it in main.ts by using a dynamic import(...) for the module.

Here is an example of using loadTranslations in polyfills.ts:

import '@angular/localize/init';
import { loadTranslations } from '@angular/localize';

loadTranslations({
  'welcome': 'Velkommen'
});

Note that the outcome of this is effectively the same as translation at compile-time. The translation happens only once If you want to change the language at runtime then you must restart the whole application. Since $localize messages are only processed on the first encounter, they do not provide dynamic language changing without refreshing the browser.

The main benefit is allowing the project to deploy a single application with many translation files. The documentation on this part is still lacking, but hopefully, we get official documentation on how to best work with loadTranslations and $localize. There are 3rd party libraries like Soluling out there trying to bridge the gaps.

If a dynamic and runtime-friendly solution is what you are looking for, then you should use Transloco.

Conclusion

We started this article by looking into how the new Ivy engine changed the i18n and localizing of applications with Angular. We looked into what benefits and drawbacks this entails and if and when we should use alternative solutions.

We then looked into adding the built-in package to a solution and how we mark texts for translation. We learned how to configure the application for localization and added tooling to manage our translation files. When we used an editor for translating, we saw how adding context to translations helps.

Finally, after configuring and translating the application, we set up a web server to serve our application both locally and in production.

There are many parts to localizing an application and I hope that after reading this article, you have a better understanding of how you can create and manage multi-language applications with Angular.

Resources

• Angular Docs

• Angular localization with Ivy by Pete Bacon Darwin

• Internationalization with @angular/localize by Cédric Exbrayat

This article steps through how to save high scores in local storage and then how to present them on the screen for the player. If you want to read about the game that inspired this article you can read about it here:

• Learning Modern JavaScript with Tetris

Local storage

With local storage, we can store data in the browser in the form of key-value pairs, where both the key and the value are strings. The data is persisted across browser sessions and its scope is limited to the origin where the script that accesses local storage resides.

Different browsers use different storages, so data is not shared between different browsers on the same computer — each browser has its unique storage.

The following snippets show how we can use localStorage:

// Add data
localStorage.setItem('myCar', 'Tesla');

// Read data
const car = localStorage.getItem('myCar');

// Remove specific data
localStorage.removeItem('myCar');

// Remove all data
localStorage.clear();

With this knowledge, we can start implementing our solution.

Load high scores

Let’s start by defining a couple of constants:

const NO_OF_HIGH_SCORES = 10;
const HIGH_SCORES = 'highScores';

Since we want to store an array we need to translate the array into a string before we save it and back to an array when getting it. For this, we can use the JSON object that contains methods for parsing JSON and converting values to JSON.

We can parse the string that we get from localStorage. If we don’t have any scores saved yet we can use the OR operator || to give a default value of empty array:

const highScoreString = localStorage.getItem(HIGH_SCORES);
const highScores = JSON.parse(highScoreString) || [];

We now have the high scores parsed into an array. Next, we need to check if a score is good enough to make the high score list.

Check for a high score

To get the lowest score on the list we can take the score from the last position in the array with the help of our constant NO_OF_HIGH_SCORES. If we don’t have a full list yet we can use optional chaining with the Elvis operator (?) and return a zero:

const lowestScore = highScores[NO_OF_HIGH_SCORES — 1]?.score ?? 0;

We have enough now to create a function checkHighScore():

function checkHighScore(score) {
  const highScores = JSON.parse(localStorage.getItem(HIGH_SCORES)) || [];
  const lowestScore = highScores[NO_OF_HIGH_SCORES - 1]?.score ?? 0;

  if (score > lowestScore) {
    saveHighScore(score, highScores); // TODO
    showHighScores(); // TODO
  }
}

And add it to the gameOver() function:

function gameOver() {
  // Other game over logic.

  checkHighScore(account.score);
}

As you can see we have a couple of remaining functions marked with TODO that we need to take care of. If we have a score good enough to make the high score list we need to save it and refresh the list.

Save high score

Now, we need to save the scores when the game ends and the player gets a score that qualifies on the top list. In addition to the score we need a name so let’s ask for it:

const name = prompt(‘You got a high score! Enter name:’);

When we have the name and the score we can create an object to save in the list:

const newScore = { score, name };

And when we have the new score that qualifies into the list we can:

1. Add it to the list
2. Sort the list
3. Select the new high score list
4. Save it back to local storage

function saveHighScore(score, highScores) {
  const name = prompt('You got a highscore! Enter name:');
  const newScore = { score, name };

  // 1. Add to list
  highScores.push(newScore);

  // 2. Sort the list
  highScores.sort((a, b) => b.score - a.score);

  // 3. Select new list
  highScores.splice(NO_OF_HIGH_SCORES);

  // 4. Save to local storage
  localStorage.setItem(HIGH_SCORES, JSON.stringify(highScores));
};

So, now that we have all this logic figured out we need to show the scores on the screen.

Show high scores

To show the best scores we need an element in the HTML that we can hook into. Let’s add an ordered list element with the id set to highScores:

<h2>HIGH SCORES</h2>
<ol id=”highScores”></ol>

Now, we need to retrieve the high scores from localStorage and show them on the screen. We can do this by using the array method map. It lets us go through the array and add an HTML ordered list item to each score in the array.

highScores.map((score) => `<li>${score.score} — ${score.name}`);

We can then get the ordered list element and add the list items to its innerHTML:

const highScoreList = document.getElementById(HIGH_SCORES);

highScoreList.innerHTML = highScores.map((score) => 
  `<li>${score.score} - ${score.name}`
);

We can run this when we initialize the game and every time there is a new high score:

function showHighScores() {
  const highScores = JSON.parse(localStorage.getItem(HIGH_SCORES)) || [];
  const highScoreList = document.getElementById(HIGH_SCORES);

  highScoreList.innerHTML = highScores
    .map((score) => `<li>${score.score} - ${score.name}`)
    .join('');
}

Now, we have a functioning high score list!

Conclusion

In this article, we added the functionality to persist our high scores in local storage. To help us format the data that we load and save from local storage, we used the JSON object. And to show it on the screen we added an HTML element as a hook to the DOM.

The next step to truly persist our high scores would be to add the high scores to a database. Maybe I will write about that next.

While I do, go play the game that inspired this article and make a high score:

It can be confusing to have one syntax represent two different uses. In this article, we will try to clear up the confusion and look into the two ways of using Javascript’s three dots.

In short we could say that:

• spread operator unpacks elements.
• rest parameter packs elements.

Definitions

• argument— An argument is a value passed to a function.
• parameter — A Parameter is a variable used in the declaration of a function.
• iterable— A collection of something that we can iterate (loop) over. For example array, list, set, and string.

function print(params) {
  params.forEach(param => console.log(param));
}

print(['arg1', 'arg2']);
// -> arg1
// -> arg2

Spread Operator

The spread operator unpacks iterables into individual elements. Let’s look into different scenarios when this is useful.

Arrays

The spread operator unpacks an array into separate arguments:

const array = [1, 2, 3];

console.log(…array);
// -> 1 2 3

This comes in handy when a function expects a list of arguments and all you have is an array:

const array = [4, 2, 9, 5];

Math.max(…array); // -> 9

To copy an array we put the spread values into another array:

const arrayA = [1, 2, 3];
const arrayB = [...arrayA];

console.log(arrayB);
// -> [1, 2, 3]

This is a great way of cloning arrays. If we do changes to either of the arrays they will not affect the other.

The spread syntax can also be used to compose several values into one:

const arrayA = [1, 2, 3];
const arrayB = [0, ...arrayA, 4];

console.log(arrayB);
// -> [0, 1, 2, 3, 4]

This is useful when we want to add elements into an existing array. We can even merge two arrays:

const first = [1, 2];
const other = [3, 4];

const combo = [...first, ...other]; 
// [1, 2, 3, 4]

These operations are not only available for arrays but also other iterables like strings:

const word = 'test';

console.log([...word]);
// -> ["t", "e", "s", "t"]

Objects

The spread operator (…) with objects is used to create copies of existing objects with new or updated values or to make a copy of an object with more properties. Let’s take an example of how to use the spread operator on an object.

Here we are spreading the user object. All key-value pairs are copied into the clonedUser object.

const user = {
  name: 'Max',
  age: 42
};

const clonedUser = { ...user };

The spread syntax is useful for merging the properties and methods on objects into a new object:

const x = { x: 1 };
const y = { y: 2 };

const coord = {...x, ...y};
console.log(coord);
// {x: 1, y: 2}

Note: Spread syntax only does a shallow copy meaning nested arrays or objects will not copy properly. The deeper data is still linked to the original.

Rest Parameter

Where the spread operator unpacks the contents of an iterable into single elements, the rest parameter instead collects all the remaining elements into an array.

In JavaScript, it’s possible to call a function with any number of arguments. We can use the rest parameter when we don’t know how many arguments will be used or just want to collect some of them into an array.

Let’s try an example where we add together all the values sent into our function:

function sum(...args) {
  let result = 0;

  for (let arg of args) {
    result += arg;
  }

  return result
}

sum(4, 2) // -> 6
sum(3, 4, 5, 6) // -> 18

So, no matter how many numbers we send into the sum function they will be added together.

Let’s do another example:

function family(spouse, …children) {
  console.log(`Spouse: ${spouse}`);

  for(const child of children) {
    console.log(`Child: ${child}`);
  }
}

family('Veronica', 'Max', 'Jack');
// -> Spouse: Veronica
// -> Child: Max
// -> Child: Jack

As shown in the above example, the three dots collected all the elements after the spouse into the children array.

We can also use the rest syntax with objects together with destructuring:

const player = {
  name: 'Max Best',
  age: 42,
  game: 'Football'
}

const { name, ...rest } = player;
console.log(name); // -> Max Best
console.log(rest);
// -> {age: 42, game: 'Football'}

Note: Rest parameters have to be the last argument. This is because it collects all remaining arguments into an array.

Conclusion

• Rest Parameter collects all remaining elements into an array.
• Spread Operator expands collected elements such as arrays into single elements.
• The spread syntax only does a shallow copy one level deep.
• Only the last parameter can be a rest parameter.

The syntax is not much different from the old one at first glance:

const newWay = `is cool`;

Can you spot the difference? Instead of single '' or double "" quotes we use backticks ``.

String Interpolation

In ES5 you had string concatenation:

const name = 'Jack';
const old = 'My name is '+ name + '.';

Using + for both addition and concatenation can be confusing and even lead to unexpected bugs:

var a = 4;
var b = 2;

console.log('a + b = ' + a + b);
// -> a + b = 42

Template literals provide an easy way to interpolate variables and expressions into strings. The curly braces accept any valid JavaScript expression inside the ${}:

const name = 'Jack';
const str = `My name is ${name}.`;
console.log(str);
// -> My name is Jack.

const a = 4;
const b = 2;
console.log(`a + b = ${a + b}`);
// -> a + b = 6

Multiline

In ES5 you had to use the newline character \n explicitly for line breaks and the \ character at the end of a line to be able to write multi-line strings. This allows to create a string on two lines:

const concatenation = 'First line\n \
second line';

Template literals make multi-line strings simpler. Once a template literal is opened with the backtick, you press enter to create a new line, with no special characters, and it’s rendered as-is:

const interpolation = `This
is more fun!

We can add expressions!
a + b = ${a + b}`

Tagged Templates

A not as known feature that comes along with template literals, is the ability to tag them. A tagged template is a function that allows you to parse template literals, which allows us to control the string creation.

The way the tag template works is that you put the name of the function that you want to run against the string before the template. So instead of function() you have function`` .

function hi() {
  return 'TODO';
}

const name = 'Jack';
const tag = hi`My name is ${name}.`;
console.log(tag);
// -> 'TODO'

The tag template is equivalent to the following function call:

hi(['My name is ', '.'], name);

First, we get an array of all the string pieces from our literal. After that, we get all the interpolated values. Here we only have one, the name.

So then we would need to change our function to accept these arguments and return the string as we like it:

function hi(strings, name) {
  return `Hello ${name}!`;
}

const name = 'Jack';
const tag = hi`My name is ${name}.`
console.log(tag);
// -> 'Hello Jack!'

You can also alter the strings depending on the arguments, which is where the true power of tagged templates comes through. There are popular libraries like styled-components and lit-html using tagged components.

Conclusion

We have learned how template literals make strings easier to handle. They can take care of our variables and embedded expressions with ease. This is much more powerful than the old concatenation of strings and variables. And we also took a look into tagged templates and how they can let us manipulate the template literals before the browser exposes them to the world.

Syntax

A proxy is created using the new Proxy constructor with two required arguments: the target and the handler.

let proxy = new Proxy(target, handler)</span>

• target — The object we wrap.
• handler — An object that defines the methods (also called traps) to control the behaviors of the target.

A Proxy creates an undetectable barrier around the target object that redirects all operations to the handler object. If we send in an empty handler, the proxy is just an empty wrapper around the original object.

let user = { 
  name: 'Max', 
  age: 42
};

let proxyUser = new Proxy(user, {});

console.log(user.name); // -> Max
console.log(proxyUser.name); // -> Max

To give the proxy meaning, we need to add some functionality to the handler.

Traps

Whenever you interact with an object, you are calling an internal method. Proxies allow you to intercept the execution of a given internal method with traps.

So when we run user.name we are telling the JavaScript engine to call the internal [[GET]] method to retrieve the name property.

When we run proxyUser.name the get trap calls the get() function defined in the handler to execute before sending the call through to the original object.

Get

The get() method has two required parameters:

• target — Object passed to the proxy.
• property — Name of the accessed property.

To customize the proxy, we define functions on the handler object. Here we define the get method to log the access:

const handler = {
  get(target, property) {
    console.log(`GET ${property}`);
    return target[property];
  }
};

To let the call through, we return target[property].

Now, if we create a proxy with this handler and try to access the original object, we log the call:

const proxyUser = new Proxy(user, handler);

console.log(proxyUser.age);
// -> GET age
// -> 42

We can see that when we access a property of the user object via the proxyUser object, the get() method fires in the handler object.

Set

The set trap controls behavior when a property of the target object is assigned.

Let’s validate the input of the age value:

const handler = {
  set(target, property, value) {
    if(property === 'age' && typeof(value) !== 'number') {
      throw new TypeError('Age is just a number.');
    }

    target[property] = value;
    return true;
  }
}

If we try to assign a wrong type to age an error is thrown:

proxyUser.age = 'old';
// -> TypeError: Age is just a number.

In the line target[property] = value we set the age property of the user object.

The set() method should return a boolean value true to indicate that the assignment succeeded. If the JavaScript is run in strict mode, and a falsy value or nothing is returned, an error will be thrown.

Uncaught TypeError: ‘set’ on proxy: trap returned falsish for property 'age'

In addition to intercepting reads and modifications to properties, Proxy can intercept a total of 13 operations.

Conclusion

We have learned how we can use a proxy to spy on objects. You should now be able to add behaviors to them by using trap methods in the handler object. We have only dipped our toes into proxies with a couple of basic examples but it’s enough to get started and inspired to explore the possibilities!

Destructuring Arrays

In ES5 you could access items in an array by index:

var fruit = ['apple', 'banana', 'kiwi'];

var apple = fruit[0];
var banana = fruit[1];
var kiwi = fruit[2];

With ES6 destructuring, the code becomes simpler:

const [apple, banana, kiwi] = fruit;

Sometimes you might want to skip over items in the array being destructured:

const [,,kiwi] = ['apple', 'banana', 'kiwi'];

Or you can save the other items in an array with the rest pattern:

const [apple, …rest] = ['apple', 'banana', 'kiwi'];

console.log(rest); // -> ['banana', 'kiwi']

Note that the destructuring assignment pattern works for any iterable.

Destructuring Objects

Object destructuring lets you extract properties from objects and bind them to variables. Instead of accessing width through rectangle.width we can access the property and assign it to a variable:

const rectangle = { width: 5, height: 8 };

const { width } = rectangle;

What’s even better, object destructuring can extract multiple properties in one statement. This makes the code clearer. The order of the properties does not matter.

const { width, height } = rectangle;

If we want to change the name of the property we can do it using a colon:

const { width: w, height: h } = rectangle;

console.log(w); // -> 5

Here we assign the property width from rectangle to a variable named w.

Default Values

When you destructure on properties that are not defined, you get undefined:

const { password } = {};

console.log(password); // -> undefined

You can provide default values for when the property you are destructuring is not defined:

const [favorite = 'apple'] = [];
console.log(favorite); // -> apple

const { width = 100 } = {};
console.log(width); // -> 100

Examples

There are many places where we can use destructuring to make the code terser. Let’s see some examples!

String Manipulation

We could for example do some string manipulation on a name and directly assign to variables firstName and lastName:

const [firstName, lastName] = 'Max Best'.split(' ');

// firstName = 'Max', lastName = 'Best'

Swapping Variable Values

Let’s first do the ES5 swap:

var me = 'happy', you = 'sad';

var temp = me;
me = you;
you = temp;

// me = 'sad', you = 'happy'

And now let’s swap back with ES6 destructuring:

[me, you] = [you, me];

// me = 'happy', you = 'sad'

No more need for temporary variables!

Function Parameter Objects

When you are passing multiple parameters it often makes sense to do it as an object. We can use destructuring whenever we want to unpack its properties:

function calculateArea({ width, height }) {
  console.log('Area is ' + width * height);
}

calculateArea({ width: 5, height: 6 }); 
// -> Area is 30

We can also set default values and change variable names:

function calculateArea({ width: w = 10, height: h = 5 }) {
  console.log('Area is ' + w * h);
}

calculateArea({ height: 6 });
// -> Area is 60

Multiple Return Values

If you need to return multiple values from a function you can return an array or object and destructure the result:

function returnWidthAndHeight() {
  return [5, 10];
}

const [width, height] = returnWidthAndHeight();
// width = 5, height = 10

Conclusion

Destructuring is a JavaScript expression that allows us to extract data from arrays and objects. In this article, we have explored the syntax and various ways we can use it in our code. Destructuring of arrays and objects is something that will make your code a bit shorter and cleaner all over the place.

Syntax

The first factor that influenced the introduction of arrow functions was a shorter function syntax. The syntax can look a bit different depending on the function. Let’s see some options!

Here is a function written in ES5 syntax:

var sum = function(a, b) {
  return a + b;
}

sum(1, 2) // -> 3

And here is the same function as an arrow function:

const sum = (a, b) => a + b;

sum(1, 2) // -> 3

As we can see the arrow function makes the code much more concise when we have one-line expressions. Due to implicit return we can omit the curly braces and return keyword.

If we have multiple lines in the function we always have to use the curly braces and return:

const printSum = (a, b) => {
  const result = a + b;
  console.log('Answer: ' + result);

  return result;
}

const sum = printSum(1, 2); 
// -> Answer: 3

Parentheses are optional when only one parameter is present:

const square = n => n * n;

square(3); // -> 9

Arrow functions are sometimes called fat arrow functions, because of the token => that resembles a fat arrow.

A common use case for arrow functions is when using array methods. Here we create a new array with the ages of the players by mapping through the player array:

const players = [
  { name:'Michael', age:44},
  { name:'Karl', age:33},
  { name:'Lisa', age:37}
];

const ages = players.map(player => player.age); 
// [44, 33, 37]

Array functions really shine here!

This

We have seen how nice the new syntax can be but there is a another better reason to use arrow functions. And that is the sometimes confusing behavior of the this keyword in JavaScript. It doesn’t depend on where it’s declared but on how and where the function is called, the execution context.

In the global scope, value of this is always the window object.

Regular Functions

Functions have their own execution context and with it comes their own this. Understanding these concepts is not easy but they are important.

Some example code can hopefully make it clearer. To show the difference we use setTimeout, a native JavaScript function which calls a function after a set delay in milliseconds.

// ES5
function Age() {
  this.age = 42;
  setTimeout(function() {
    console.log(this.age); // -> undefined
  }, 1000);
}

var a = new Age();

If we run this code we get undefined logged to the console because the function inside setTimeout has its own execution context. So we are not accessing this.age of the Age function but of the one inside the function where we make the call. And that hasn’t assigned a value to age.

To access the context of the parent function developers often reassign this of the outer function to a variable commonly named that or self.

// ES5
function Age() {
  var that = this;
  that.age = 42;
  setTimeout(function() {
    console.log(that.age); // -> 42
  }, 1000);
}

var a = new Age();

In this way we can access the this of the parent function but you can see how it can be confusing.

Another option is to use function{}.bind(this).

Arrow Functions

Arrow functions however share the lexical scope with their parent. This means that it uses this from the code that contains the arrow function.

// ES6
function Age() {
  this.age = 42;
  setTimeout(() => {
    console.log(this.age); // -> 42
  }, 1000);
}

const a = new Age();

So, we can see how arrow functions help to make the code cleaner and easier to read.

Should we always use Arrow Functions?

Arrow functions are great but there is still use for regular functions. Let’s see some examples when we should not use arrow functions.

Methods

Arrow functions are best suited for non-method functions. Let’s see what happens when we try to use them as methods. In this example, we create an object blog with a method like.

const blog = {
  likes: 0,
  like: () => {
    this.likes++;
  }
}

One would think that every time we call blog.like() the attribute blog.likes increases by one. However, sadly the value of likes will remain at zero.

This time the parent scope is the window object and not the blog object. So invoking the method like() would attempt to increment the property likes on the window object.

If instead, we use the traditional syntax it will work as expected:

const blog = {
  likes: 0,
  like: function() {
    this.likes++;
  }
}

Even better, another new feature in ES6 is shorthand method syntax:

const blog = {
  likes: 0,
  like() {
    this.likes++;
  }
}

Notice here that we can omit the function keyword and colon.

Constructor

An arrow function cannot be used as a constructor. It will throw an error when used with new:

const PrintDouble = (x) => console.log(2 * x);

new PrintDouble(2);
// -> TypeError: PrintDouble is not a constructor

We can instead use a function expression:

const PrintDouble = function(x) {
  console.log(2 * x);
};

new PrintDouble (2); // -> 4

Conclusion

Arrow functions are a great new addition ES6 that brings us a syntactically compact alternative to a regular function. An arrow function does not have its own this. The this value of the enclosing lexical scope is used. Arrow functions are ill suited as methods, and they cannot be used as constructors.

// ES5 constructor function
function Car(brand) {
  this.brand = brand;
}

// Adding a method to the prototype
Car.prototype.getBrand = function() {
  return this.brand;
}

Classes, introduced with ES6 provide “syntactical sugar”, that is comparable to inheritance in object-oriented languages. Classes are special functions meant to mimic the class keyword from these other languages. In this article we go through how to use JavaScript classes.

Defining a Class

To define a class we use the class keyword followed by the name of the class. The body of a class is the part that is in curly braces {}:

class Car {
  // Body of the class
}

The code above defines a class Car. This syntax is named class declaration.

The new operator instantiates the class:

const myCar = new Car();

This is how we create a new object, an instance, of the Car class.

console.log(typeof Car); // -> function

And as you can see, in JavaScript, a class is a kind of function.

We don’t need to give the class a name. By using a class expression you can assign the class to a variable:

const Car = class {} // unnamed
const Car = class Car {} // named

Class expressions can be named or unnamed. The name given to a named class expression is local to the class’s body.

Hoisting

An important difference between function declarations and class declarations is that function declarations are hoisted and class declarations are not. Therefore you need to first declare the class before you can initialize objects with the new keyword.

Conceptually, for example, a strict definition of hoisting suggests that variable and function declarations are physically moved to the top of your code, but this is not in fact what happens. Instead, the variable and function declarations are put into memory during the compile phase, but stay exactly where you typed them in your code. — MDN

As you might remember variables declared with var are also hoisted. So, keeping with the “modern” way it makes then sense that classes just like variables declared with let or const are not hoisted.

Initialization

Classes in JavaScript have a special method called constructor that lets us set initial values for fields when the object is initialized. There can be only one constructor method.

Let’s create a Car class with a constructor that sets the initial value of the field brand:

class Car {
  constructor(brand) {
    this.brand = brand; 
  } 
}

The expression this.brand = brand creates a public field brand and assigns it an initial value. We can now create a new car object and access it’s brand property:

const car = new Car('Volvo');
console.log(car.brand); // -> Volvo

As you can see we can now access the brand field using a property accessor. There’s no restriction on the access of the public fields. You can read and modify the values of public fields inside the constructor, methods, and outside of the class.

The bodies of class declarations and class expressions are executed in strict mode.

Methods

Classes provide a cleaner and more elegant syntax for adding methods.

class Car { 
  constructor(brand) {
    this.brand = brand;
  } 

  getBrand() {
    return this.brand;
  }
}

The keyword this allows us to access instance data inside the constructor and methods.

const car = new Car('Tesla');
console.log(car.getBrand()); // -> Tesla

The method invocation car.getBrand() executes the methods inside the Car class and returns the brand property.

Static Methods

We can also assign a method to the class function itself, not to its prototype. Such methods are called static and are prepended with the static keyword:

class Double {
  static double(n) {
    return n * 2;
  }
}

Double.double(2); // -> 4

We don’t have to create an instance of the class but can call the method directly on the class itself. Static methods are often used in utility classes for making computations.

Getters and Setters

JavaScript classes can have getter and setter functions.

class Car { 
  constructor(brand) {
    this._brand = brand;
  }

  get brand() {
    return this._brand;
  }

  set brand(value) {
    this._brand = value;
  }
}

Notice that if you would do this.brand = value in the setter we would be calling the setter again and go into an infinite loop. Using an underscore _ is a common convention.

With this we can create an instance of the class and access the brand property through the setter and getter:

const car = new Car('');
car.brand = 'Tesla;
console.log(car.brand); // -> Tesla

Inheritance

Class inheritance is a way to inherit the functionality of another class and extend it. We create a child class with the extends keyword.

class SportsCar extends Car {
  isFast() {
    return true;
  }
}

Now we can use the functionality of the class we extended:

const car = new SportsCar('Mazda');
console.log(car.brand); // -> Mazda
console.log(car.isFast()); // -> true

You can see here that we didn’t have to create a constructor. If a class extends another class and has no constructor, then the following constructor is generated:

constructor(...args) {
  super(...args); // Copying args with spread operator (...)
}

The super keyword is used to call corresponding methods of the parent class. So the constructor calls the parent constructor passing it all the arguments. If we want to add another in-parameter to our class we can create a constructor:

class SportsCar extends Car {
  constructor(brand, model) {
    super(brand);
    this.model = model;
  }
}

const myCar = new SportsCar('Mazda', 'MX-5');

Note that constructors in inheriting classes must call super(), and do it before using this.

Conclusion

• Use classes when you need to create multiple objects of the same kind.
• Classes are a special kind of functions that run in strict mode and are not hoisted.
• Classes can have fields and methods that we can access from a class instance.
• We can inherit functionality from other classes by extending them.

Variables

A variable is a named container with a unique name for storing data values. The statement below declares a variable with the name “car”:

let car;

console.log(car); // undefined

In JavaScript, variables are initialized with the value of undefined when they are created. You can assign a value to a variable using the assignment operator (=) when you declare it:

let car = 'Volvo';

console.log(car); // Volvo

Always initialize your variables before using them or you will get an error:

console.log(car); // ReferenceError: car is not defined

const car = "Toyota";

ECMAScript 2015 (or ES6) introduced two new ways of declaring variables, let and const. The reason for the new keywords was because the function scoping of var is confusing. It was one of the main sources of bugs in JavaScript.

Scope

By scope, we are talking about the visibility of variables in the different parts of the code during runtime. Or in other words which parts of the code can access and modify a variable.

In JavaScript there are two types of scope:

• Global scope
• Local scope

What changed with Modern JavaScript (ES6+) is the way we use variables in the local scope.

Global Scope

A variable declared outside a function becomes global. This means it can be accessed and modified everywhere in the code.

We can declare constants in the global scope:

const COLS = 10;
const ROWS = 20;</span>

We can then access them from all parts of our code.

Local Scope

Variables declared in a local scope can not be accessed from outside that scope. The same variable name can be used in different scopes because they are bound to their respective scopes.

Local scope differs depending on the variable declaration used.

Function Scope

Variables declared with the var keyword become local to the function. They can be accessed from within the function.

function printCar() {
  if(true) {
    console.log(car); // undefined
    var car = "Porsche";
    console.log(car); // "Porsche" 
  }
  console.log(car); // "Porsche"
}

printCar();
console.log(car); // ReferenceError

We can see that we don’t get an error even though we access car before the declaration. Variables declared with the var keyword are hoisted — moved to the top of the function and initialized with undefined before the code is run. With the hoisting, they are accessible in their enclosing scope even before they are declared.

Can you see how this can get confusing?

Block Scope

The concept of block scope was introduced in ES6 together with the new ways to declare variables — const and let. This means that the variable is accessible between two curly braces {}. For example inside an if or for.

function printCar() {
  if(true) {
    console.log(car); // ReferenceError
    const car = "Fiat";
    console.log(car); // "Fiat" 
  }
  console.log(car) // ReferenceError
}

printCar();
console.log(car); // ReferenceError

The let and const variables are not initialized until their definition is evaluated. They are not hoisted as in the function scoping. Accessing them before the initialization results in a ReferenceError.

I hope you can see how this is easier to reason about.

Const vs Let

So now that we know that we should use let and const, when should we use which?

The difference between the two is that the value of a const can’t be changed through reassignment, and it can’t be re-declared. So if we don’t need to reassign we should use const. This also makes the code clearer since we have one variable to represent one thing.

You could even always declare the variables as const until you see that you need to reassign the variables and then change to let. One example of when you need let is in loops:

for(let i = 0; i < 10; i++) {
  console.log(i); // 1, 2, 3, 4 …
}

Conclusion

• Variables declared on the global scope are accessible everywhere in your code.
• Variables declared in a local scope can not be accessed from outside that scope.
• const and let use block scope which exists between two curly braces.
• Mostly use const for variables whose values will never change.
• For everything else use let.
• Don’t use var to avoid confusion.

• Classes

• Arrow Functions

• Destructuring

• Let and const

• Proxy

I hope you pick up something new that you can bring into your arsenal of JavaScript tricks!

If you are creating the project and get an error from the code snippets, then check the code in the repository on GitHub. Please send me a message if you find something that does not work. Future developments of the game will go into the master branch while the blog branch will stay as is.

The finished game looks like this:

Translations:

• Korean

Tetris

Tetris was created in 1984 by Alexey Pajitnov. The game requires players to rotate and move falling Tetris pieces. Players clear lines by completing horizontal rows of blocks without empty cells. But, if the pieces reach the top, the game is over!

Tetris is a great game to begin our journey in game development. It contains essential elements of games and is relatively easy to program. The tetrominos are a collection of four blocks, which makes graphics a bit easier than most games.

Project structure

It’s good to split the code up some in the project even if it’s not that big. The JavaScript is in four different files:

• constants.js is where we put the configurations and rules of the game.

• board.js is for board logic.

• piece.js is for piece logic.

• main.js has code to initialize the game and the overall game logic.

• index.html the order of the scripts that we add at the end is essential.

• styles.css all the beautifying styles are in here.

• README.md markdown info file that is the first page in the repository.

Size and Style

The playing board consists of 10 columns and 20 rows. We are using these values often to loop through the board so we can add them to constants.js together with the size of the blocks:

const COLS = 10;
const ROWS = 20;
const BLOCK_SIZE = 30;

I prefer using the canvas element for the graphics:

<div class="grid">
  <canvas id="board" class="game-board"></canvas>
  <div class="right-column">
    <div>
      <h1>TETRIS</h1>
      <p>Score: <span id="score">0</span></p>
      <p>Lines: <span id="lines">0</span></p>
      <p>Level: <span id="level">0</span></p>
      <canvas id="next" class="next"></canvas>
    </div>
    <button onclick="play()" class="play-button">Play</button>
  </div>
</div>

We can get the canvas element and its 2d context in main.js and use the constants to set the size:

const canvas = document.getElementById('board');
const ctx = canvas.getContext('2d');

// Calculate size of canvas from constants.
ctx.canvas.width = COLS * BLOCK_SIZE;
ctx.canvas.height = ROWS * BLOCK_SIZE;

// Scale blocks
ctx.scale(BLOCK_SIZE, BLOCK_SIZE);

By using scale, we can always give the size of the blocks as one (1) instead of having to calculate with BLOCK_SIZE everywhere, which simplifies our code.

Styling

It’s nice to have a bit of an 80’s feel to our game. Press Start 2P is a bitmap font based on the font design from the 1980s Namco arcade games. We can link to it in the <head> and add it to our styles:

<link 
  href="https://fonts.googleapis.com/css?family=Press+Start+2P" 
  rel="stylesheet"
/>

The first section in styles.css is for the arcade-style font. Notice the use of CSS Grid and Flexbox for the layout:

* {
  font-family: 'Press Start 2P', cursive;
}

.grid {
  display: grid;
  grid-template-columns: 320px 200px;
}

.right-column {
  display: flex;
  flex-direction: column;
  justify-content: space-between;
}

.game-board {
  border: solid 2px;
}

.play-button {
  background-color: #4caf50;
  font-size: 16px;
  padding: 15px 30px;
  cursor: pointer;
}

With this, we have our game container styled and ready, awaiting code.

The Board

The board in Tetris consists of cells, which are either occupied or not. My first thought was to represent a cell with boolean values. But, we can do better by using numbers. We can represent an empty cell with 0, and the colors with numbers 1–7.

The next concept is representing the rows and columns of the game board. We can use an array of numbers to represent a row. And the board is an array of rows. In other words, a two dimensional (2D) array or what we call a matrix.

The board is a good candidate for a class. We probably wan’t to create a new Board when starting a new game. If you wan’t to learn more about classes I have written a short article about them:

• Getting Started with Modern JavaScript — Classes

Let’s create a function in board.js that returns an empty board with all cells set to zero. The fill() method comes in handy here:

class Board {

  // Reset the board when we start a new game.
  reset() {
    this.grid = this.getEmptyBoard();
  }

  // Get matrix filled with zeros.
  getEmptyBoard() {
    return Array.from(
      {length: ROWS}, () => Array(COLS).fill(0)
    );
  }
}

We can call this function in main.js when we press play:

let board = new Board();

function play() {  
  board.reset();  
  console.table(board.grid);  
}

By using console.table we see the representation of the board in numbers:

The X and Y coordinates represent the cells of the board. Now that we have the board, let’s take a look at the moving parts.

Tetrominos

A piece in Tetris is a shape consisting of four blocks that move as a unit. They are often called tetrominos and come in seven different patterns and colors. The names I, J, L, O, S, T, and Z are from the resemblance in their shape.

We represent the J tetromino as a matrix where the number two represents the colored cells. We add the row of zeros to get a center to rotate around:

[2, 0, 0],
[2, 2, 2],
[0, 0, 0];

The tetrominos spawn horizontally with J, L, and T spawning flat-side first.

We want the Piece class to know its position on the board, what color it has, and its shape. So to be able to draw itself on the board, it needs a reference to the canvas context.

For starters, we can hard-code the values of our piece in the constructor of the Piece class:

class Piece {  
  constructor(ctx) {
    this.ctx = ctx;
    this.color = 'blue';
    this.shape = [
      [2, 0, 0], 
      [2, 2, 2], 
      [0, 0, 0]
    ];

    // Starting position.
    this.x = 3;
    this.y = 0;
  }
}

To draw the tetromino on the board, we loop through all the cells of the shape. If the value in the cell is greater than zero, then we color that block:

draw() {
  this.ctx.fillStyle = this.color;
  this.shape.forEach((row, y) => {
    row.forEach((value, x) => {
      // this.x, this.y gives the left upper position of the shape
      // x, y gives the position of the block in the shape
      // this.x + x is then the position of the block on the board
      if (value > 0) {
        this.ctx.fillRect(this.x + x, this.y + y, 1, 1);
      }
    });
  });
}

The board keeps track of the tetromino on the board so we can create and paint it when we press the play button:

function play() {
  board.reset();
  let piece = new Piece(ctx);
  piece.draw();

  board.piece = piece;
}

The blue J tetromino appears!

Next, let’s make magic happen through the keyboard.

Keyboard input

We need to connect the keyboard events to move the piece on the board. The move function changes the x or y variable of the current piece to change its position on the board.

move(p) {
  this.x = p.x;
  this.y = p.y;
}

Enums

Next, we map the keys to the key codes in constants.js. For this, it would be nice to have an enum.

Enum (enumeration) is a special type used to define collections of constants.

There are no built-in enums in JavaScript so let’s make one by creating an object with the values:

const KEY = {
  LEFT: 37,
  RIGHT: 39,
  DOWN: 40
}
Object.freeze(KEY);

The const can be a bit misleading when working with objects and arrays and does not actually make them immutable. To achieve this, we can use Object.freeze(). A couple of gotchas here are:

• For this to work properly, we need to use strict mode.

• This only works one level down. In other words, if we have an array or object inside our object, then this does not freeze them.

Object literals

To match the key events to actions, we can use object literal lookups.

ES6 allows property keys of object literals to use expressions, making them computed property keys.

We need the brackets to get computed property names so that we can use our constants. This is a simplified example of how it works:

const X = 'x';
const a = { [X]: 5 };
console.log(a.x); *// 5*

We want to send in the current tetromino and return a copy of it together with the change in coordinates. For this, we can use the spread operator to get a shallow copy and then change the coordinates to our desired position.

In JavaScript, we can use shallow copying to copy primitive data types like numbers and strings. In our case, the coordinates are numbers. ES6 offers two shallow copy mechanisms: Object.assign() and the spread operator.

In other words, a lot is going on in this code snippet:

const moves = {
  [KEY.LEFT]:  p => ({ ...p, x: p.x - 1 }),
  [KEY.RIGHT]: p => ({ ...p, x: p.x + 1 }),
  [KEY.DOWN]:    p => ({ ...p, y: p.y + 1 })
};

Which we can use with the code beneath to get the new state without mutating the original piece. It’s important because we don’t always want to move to a new position.

const p = this.moves[event.key](this.piece);

Next, we add an event listener that listens to keydown events:

document.addEventListener('keydown', event => {
  if (moves[event.keyCode]) {  
    // Stop the event from bubbling.
    event.preventDefault();

    // Get new state of piece
    let p = moves[event.keyCode](board.piece);

    if (board.valid(p)) {    
      // If the move is valid, move the piece.
      board.piece.move(p);

      // Clear old position before drawing.
      ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height); 

      board.piece.draw();
    }
  }
});

Now we are listening to the keyboard events, and if we press left, right, or down arrows, then we can see the piece moving.

We have a movement! However, ghost pieces going through walls are not what we want.

Collision detection

Tetris would not be a particularly exciting game if all blocks could pass through each other, or if the walls and floor did not stop them. So instead of moving the tetromino, we’ll check for potential collisions first, and then only move the tetromino if it’s safe. We have a few different collisions to consider.

We have a collision when the tetromino:

• hits the floor

• moves left or right into a wall

• hits a block on the board

• rotates, and the new rotation hits a wall or block

We already defined the potential new position for the shape. Now we can add a check if this position is valid before we move to it. To check for collisions, we loop through all the spaces in the grid that the tetromino would take up in its potential new position.

The array method best suited for this is every(). With it, we can check whether all elements in the array pass the tests we provide. We calculate the coordinates of every block of the piece and check that it’s a valid position:

valid(p) {
  return p.shape.every((row, dy) => {
    return row.every((value, dx) => {
      let x = p.x + dx;
      let y = p.y + dy;
      return (
        this.isEmpty(value) ||
       (this.insideWalls(x) &&
        this.aboveFloor(y)
      );
    });
  });
}

By using this method before we move, we make sure that we don’t move anywhere we shouldn’t:

if (this.valid(p)) {
  this.piece.move(p);
}

Let’s try going outside the grid again.

No more ghosting!

Now that the floor stops the tetromino, we can add another move called the hard drop. Pressing space drops the tetromino until it collides with something. This is called a hard drop. We also need to add the new key mapping and move:

const KEY = {  
  SPACE: 32,
  // ...
}

moves = {  
  [KEY.SPACE]: p => ({ ...p, y: p.y + 1 })
  // ...
};

// In EventListener
if (event.keyCode === KEY.SPACE) {
  // Hard drop
  while (board.valid(p)) {
    board.piece.move(p);   
    p = moves[KEY.DOWN](board.piece);
  }
}

What’s next?

Rotation

Now we can move around, but it would not be any fun if we can’t rotate the piece. We need to rotate the tetrominos around their center.

It has been a while since I studied linear algebra in school. But, to rotate clockwise goes something like this:

Two reflections can accomplish a rotation by 90 degrees at a 45-degree angle so you can take the transpose of the matrix and then multiply it by the permutation matrix that reverses the order of the columns.

And in JavaScript:

// Transpose matrix, p is the Piece.
for (let y = 0; y < p.shape.length; ++y) {
  for (let x = 0; x < y; ++x) {
    [p.shape[x][y], p.shape[y][x]] = 
    [p.shape[y][x], p.shape[x][y]];
  }
}

// Reverse the order of the columns.
p.shape.forEach(row => row.reverse());

We can add a function that rotates the shape. Earlier, we used the spread operator to clone the coordinates. In this case, we are working with a multiple level array, but the spread operator only copies one level deep. The rest is copied by reference.

I’m instead using JSON.parse and JSON.stringify. The **stringify() method converts the matrix to a JSON string. The `parse()`** method parses the JSON string, constructing our matrix back again to a clone:

rotate(p){
  // Clone with JSON for immutability
  let clone = JSON.parse(JSON.stringify(p));

  // Do algorithm

  return clone;
}

Then we add a new state for ArrowUp in board.js.

[KEY.UP]: (p) => this.rotate(p)

Now we rotate!

Randomize Tetromino

To be able to get different kinds of pieces, we need to add a bit of randomization to our code.

Following the Super Rotation System, we can take the first position of the pieces and add them to our constants together with the colors:

const COLORS = [  
  'cyan',
  'blue',
  'orange',
  'yellow',
  'green',
  'purple',
  'red'
];

const SHAPES = [  
  [
    [0, 0, 0, 0], 
    [1, 1, 1, 1],
    [0, 0, 0, 0], 
    [0, 0, 0, 0]
  ], 
  [
    [2, 0, 0],
    [2, 2, 2],
    [0, 0, 0]
  ],
  // And so on
];

We need to randomize the index of one of these to pick one piece. To get a random number, we create a function that uses the length of the array.

randomizeTetrominoType(noOfTypes) {
  return Math.floor(Math.random() * noOfTypes);
}

With this method we can get a random tetromino type when we spawn and then set the color and shape from it:

const typeId = this.randomizeTetrominoType(COLORS.length);
this.shape = SHAPES[typeId];
this.color = COLORS[typeId];

If we press play the page shows pieces with different shapes and colors.

Game Loop

Almost all games have one main function that keeps the game running even when the user isn’t doing anything. This cycle of running the same core function over and over again is called the game loop. In our game, we need a game loop that moves the tetrominos down the screen.

RequestAnimationFrame

To create our game loop, we can use requestAnimationFrame. It tells the browser that we want to animate, and it should call a function to update an animation before the next repaint. In other words, we tell the browser: “Next time you paint on the screen, also run this function because I want to paint something too.”

“Animation is not the art of drawings that move but the art of movements that are drawn.” — Norman McLaren

The way to animate with window.requestAnimationFrame() is to create a function that paints a frame and then re-schedules itself. If we use it inside a class (we don’t in our case), we need to bind the call to this, or it has the window object as its context. Since it doesn't contain the animate function, we get an error.

animate() {
  this.piece.draw();
  requestAnimationFrame(this.animate.bind(this));
}

We can remove all our previous calls to draw() and instead call animate() from the play() function to start the animation. If we try our game, it should still run like before.

Timer

Next, we need a timer. Every time frame, we drop the tetromino. There is an example on the MDN page that we can modify to our needs.

We start by creating an object with the info we need:

time = { start: 0, elapsed: 0, level: 1000 };

In the game loop, we update our game state based on the time interval and then draw the result:

function animate(now = 0) {
  // Update elapsed time.  
  time.elapsed = now - time.start;

  // If elapsed time has passed time for current level  
  if (time.elapsed > time.level) {

    // Restart counting from now
    time.start = now;   

    this.drop();  
  }

  // Clear board before drawing new state.
  ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height); 

  board.draw();  
  requestId = requestAnimationFrame(animate);
}

We have animation!

Next, let’s look at what happens when we reach the bottom.

Freeze

When we can’t move down anymore, we freeze the piece and spawn a new one. Let’s start by defining freeze(). This function merges the tetromino blocks to the board:

freeze() {
  this.piece.shape.forEach((row, y) => {
    row.forEach((value, x) => {
      if (value > 0) {
        this.grid[y + this.piece.y][x + this.piece.x] = value;
      }
    });
  });
}

We can’t see anything yet, but by logging the representation of the board, we can see that the shape is on the board.

Let’s add a function that draws the board:

drawBoard() {
  this.grid.forEach((row, y) => {
    row.forEach((value, x) => {
      if (value > 0) {
        this.ctx.fillStyle = COLORS[value];
        this.ctx.fillRect(x, y, 1, 1);
      }
    });
  });
}

Now the draw function looks like this:

draw() {
  this.piece.draw();
  this.drawBoard();
}

If we run the game, we can see that the pieces are showing up.

Now that we are freezing the pieces, we need to add new collision detection. This time we have to make sure that we don’t collide with frozen tetrominos on the board. We can do this by checking that the cell is zero. Add this to the valid method and send in the board as an argument:

board[p.y + y][p.x + x] === 0;

Now that we are adding pieces to the board, it quickly gets crowded. We should do something about that.

Line clear

To last longer, we need to assemble the tetrominos in rows of blocks that span the entire row, resulting in a line clear. When you do so, the row disappears, causing the ones above it to settle.

Detecting formed lines is as easy as checking if it has any zeros:

this.grid.forEach((row, y) => {

  // If every value is greater than 0.
  if (row.every(value => value > 0)) {

    // Remove the row.
    this.grid.splice(y, 1);

    // Add zero filled row at the top. 
    this.grid.unshift(Array(COLS).fill(0));
  } 
});

We can add a call to this clearLines() function after the freeze() call. We can try playing and hopefully see the rows getting cleared.

Score

To get a bit more excitement, we need to keep score. From the Tetris guideline we get these values:

const POINTS = {
  SINGLE: 100,
  DOUBLE: 300,
  TRIPLE: 500,
  TETRIS: 800,
  SOFT_DROP: 1,
  HARD_DROP: 2
}
Object.freeze(POINTS);

To keep track of the game progress, we add an accountValues object with the score and lines. When any of these values changes, we want to change it on the screen. We add a generic function that gets the element from the HTML and changes its textContext to the value provided.

To act on changes on the account object, we can create a Proxy object and run the code to update the screen in the set method. If you wan’t to learn the basics of Proxy I have a short article on it you can read:

• Getting Started with Modern JavaScript — Proxy

We send in the accountValues object to the proxy because this is the object we want to have custom behaviors on:

let accountValues = {
  score: 0,
  lines: 0
}

function updateAccount(key, value) {
  let element = document.getElementById(key);
  if (element) {
    element.textContent = value;
  }
}

let account = new Proxy(accountValues, {
  set: (target, key, value) => {
    target[key] = value;
    updateAccount(key, value);
    return true;
  }
}

Now every time we call properties on the proxy account, we call updateAccount() and update the DOM. Let’s add the points for soft and hard drops in our event handler:

if (event.keyCode === KEY.SPACE) {
  while (board.valid(p)) {
    account.score += POINTS.HARD_DROP;
    board.piece.move(p);
    p = moves[KEY.DOWN](board.piece);
  }
} else if (board.valid(p)) {
  board.piece.move(p);
  if (event.keyCode === KEY.DOWN) {
    account.score += POINTS.SOFT_DROP;
  }
}****

Now for the line clear points. Depending on the number of lines, we get the defined points:

getLineClearPoints(lines) {  
  return lines === 1 ? Points.SINGLE :
         lines === 2 ? Points.DOUBLE :  
         lines === 3 ? Points.TRIPLE :     
         lines === 4 ? Points.TETRIS : 
         0;
}

For this to work, we need to add a bit of logic to count how many lines we clear:

clearLines() {
  let lines = 0;
  this.board.forEach((row, y) => {    
    if (row.every(value => value !== 0)) {      
      lines++; // Increase for cleared line
      this.board.splice(y, 1); 
      this.board.unshift(Array(COLS).fill(0));
    }  
  });  
  if (lines > 0) {    
    // Add points if we cleared some lines
    account.score += this.getLineClearPoints(lines);  
  }
}

If we try playing now, we can see that we are increasing our score. What we need to keep in mind is that whenever we want something to show up on the screen, we need to go through the proxy instead of directly to the account object.

Levels

When we get better at Tetris, the speed we start on gets too easy. And too easy means boring. So we need to increase the level of difficulty. We do this by decreasing the interval speed in our game loop:

const LINES_PER_LEVEL = 10;

const LEVEL = {
  0: 800,
  1: 720,
  2: 630,
  3: 550,
  // ...
}

Object.freeze(LEVEL);

We can also show the player which level they are currently on. The logic of keeping track and showing levels and lines is the same as for points. We initialize a value for them, and when we start a new game, we have to reset them.

We can add it to the account object:

let accountValues = {
  score: 0,
  lines: 0,
  level: 0
}

The initialization of the game can go in a function that we call from play():

function resetGame() {
  account.score = 0;
  account.lines = 0;
  account.level = 0;
  board = this.getEmptyBoard();
}

With increasing levels comes more points for line clears. We multiply the points with the current level and add one since we start on level zero.

(account.level + 1) * lineClearPoints;

The next level is reached when the lines are cleared as configured. We also need to update the speed of the level:

if (lines > 0) {
  // Calculate points from cleared lines and level.

  account.score += this.getLinesClearedPoints(lines, this.level);
  account.lines += lines;

  // If we have reached the lines for next level
  if (account.lines >= LINES_PER_LEVEL) {

    // Goto next level
    account.level++;

    // Remove lines so we start working for the next level
    account.lines -= LINES_PER_LEVEL;

    // Increase speed of game.
    time.level = Level[account.level];
  }
}

Now if we play and clear ten lines we see the level increase and the points double. And of course the game starts moving a bit faster.

Game Over

If you play for a while, you notice that the tetrominos don’t stop falling. We need to know when to end the game.

After we drop we can check if we are still on row 0 and in that case, we stop the game by exiting the game loop function:

if (this.piece.y === 0) {
  this.gameOver();
  return;
}

Before we exit, we cancel the previously scheduled animation frame request with cancelAnimationFrame. And, we show a message to the user:

function gameOver() {
  cancelAnimationFrame(requestId);
  this.ctx.fillStyle = 'black';
  this.ctx.fillRect(1, 3, 8, 1.2);
  this.ctx.font = '1px Arial';
  this.ctx.fillStyle = 'red';
  this.ctx.fillText('GAME OVER', 1.8, 4);
}

Next tetromino

Let’s add one last thing, the next tetromino. We can add another canvas for this:

<canvas id="next" class="next"></canvas>

Next, we do as we did for our first canvas:

const canvasNext = document.getElementById('next');
const ctxNext = canvasNext.getContext('2d');

// Size canvas for four blocks.
ctxNext.canvas.width = 4 * BLOCK_SIZE;
ctxNext.canvas.height = 4 * BLOCK_SIZE;
ctxNext.scale(BLOCK_SIZE, BLOCK_SIZE);

We have to change the logic a bit in the drop function. Instead of creating a new piece we set it to the next and instead create a new next piece:

this.piece = this.next;
this.next = new Piece(this.ctx);
this.next.drawNext(this.ctxNext);

Now that we see which piece is coming next, we can be a bit more strategic.

Conclusion

Today we learned about the basics in game development and how we can use Canvas for graphics. I also wanted this project to be a fun way of learning modern JavaScript. I hope you enjoyed the article and learned something new for your JavaScript toolbox.

And now that we have taken our first steps into game development, what game do we do next?

Check out how to add high scores:

• How to Add High Scores in Local Storage

Thank you, Tim Deschryver for being the sounding board of my Tetris journey.

Resources

• Here is the code on GitHub for the finished game.

• The Story of Tetris on YouTube

• The history of Tetris randomizers

• Tetris Wiki

• SimpleTetris in only 100 lines of JavaScript

I hope you come back if I let you try out the game: Play the game!

The code for the finished game is on GitHub. Please send me a message if you find something that does not work. Future developments of the game will go into the master branch while the blog branch will stay as is.

Tetris

Tetris was created in 1984, by Alexey Pajitnov. The game requires players to rotate and move falling Tetris pieces. Players clear lines by completing horizontal rows of blocks without empty cells. But, if the pieces reach the top, the game is over!

Tetris is a great game to begin our journey in game development. It contains essential elements of games and can be done without too much effort. The tetrominos are a collection of four blocks, which makes graphics a bit easier than most games.

For more in-detail knowledge about using the canvas, I wrote another article as a primer to this one. It goes through the fundamentals of how to animate an object:

• How to get started with Canvas animations in Angular

Setup

Let’s start by installing the Angular CLI globally:

npm install -g @angular/cli

With the CLI installed, we can create a new project with ng new:

ng new ng-tetris — minimal — defaults

The playing board consists of 10 columns and 20 rows. We are using these values often to loop through the board so we can add them to constants.ts together with the size of the blocks:

export const COLS = 10;
export const ROWS = 20;
export const BLOCK_SIZE = 30;

We need something to draw on. I prefer using a canvas, an HTML element which can be used to draw graphics.

We first need to introduce a <canvas> element, which we can do in the component's template. We'll also attach a reference variable to the element so that can refer to it from the component class. This is our complete template waiting for some logic to make the magic happen:

<div class="grid">
  <canvas #board class="game-board"></canvas>
  <div class="right-column">
    <div>
      <h1>TETRIS</h1>
      <p>Score: {{ points }}</p>
      <p>Lines: {{ lines }}</p>
      <p>Level: {{ level }}</p>
    </div>
    <button (click)="play()" class="play-button">Play</button>
  </div>
</div>

Here is the board.component.ts starter code:

import { Component, ViewChild, ElementRef, OnInit } from '@angular/core';
import { COLS, BLOCK_SIZE, ROWS } from './constants';

@Component({
  selector: 'game-board',
  templateUrl: 'board.component.html'
})
export class BoardComponent implements OnInit {
  // Get reference to the canvas.
  @ViewChild('board', { static: true })
  canvas: ElementRef<HTMLCanvasElement>;

  ctx: CanvasRenderingContext2D;
  points: number;
  lines: number;
  level: number;

  ngOnInit() {
    this.initBoard();
  }

  initBoard() {
    // Get the 2D context that we draw on.
    this.ctx = this.canvas.nativeElement.getContext('2d');

    // Calculate size of canvas from constants.
    this.ctx.canvas.width = COLS * BLOCK_SIZE;
    this.ctx.canvas.height = ROWS * BLOCK_SIZE;
  }

  play() {}
}

Change the template in app.component.ts to be the new board component:

<game-board></game-board>

Styling

It’s nice to have a bit of an 80’s feel to our game. Press Start 2P is a bitmap font based on the font design from 1980s Namco arcade games. We can add it in two steps:

<!-- index.html -->
<link *href*=”https://fonts.googleapis.com/css?family=Press+Start+2P" *rel*=”stylesheet” />

/* styles.css */
* {
  font-family: 'Press Start 2P', cursive;
}

With this, we have our game container styled and ready, waiting for some code.

The Board

The board in Tetris consists of cells, which are either occupied or not. My first thought was to represent a cell with boolean values. But, we can do better by using numbers. We can represent an empty cell with 0, and the colors with numbers 1–7.

The next concept is representing the rows and columns of the game board. We can use an array of numbers to represent a row. And the board is an array of rows. In other words, a two dimensional (2D) array, or matrix.

Let’s create a function that returns an empty board with all cells set to zero. The fill() method comes in handy here:

getEmptyBoard(): number[][] {
  return Array.from({ length: ROWS }, () => Array(COLS).fill(0));
}

We can call this function when we press play:

play() {
  this.board = this.boardService.getEmptyBoard();
  console.table(this.board);
}

By using console.table we see the representation of the board in numbers:

The X and Y coordinates represent the cells of the board. Now that we have the board let’s take a look at the moving parts.

Tetrominos

A piece in Tetris is a shape consisting of four blocks that move as a unit. They are often called tetrominos and come in seven different patterns and colors. The names I, J, L, O, S, T, and Z are from the resemblance in their shape.

We represent the J tetromino as a matrix where the number two represents the colored cells. We add the row of zeros to get a center to rotate around:

[2, 0, 0],
[2, 2, 2],
[0, 0, 0];

The tetrominos spawn horizontally with J, L and T spawning flat-side first.

Let’s specify the Tetris piece in our code with an interface:

export interface IPiece {
  x: number;
  y: number;
  color: string;
  shape: number[][];
}

We want the Piece class to know its position on the board, what color it has, and its shape. So to be able to draw itself on the board, it needs a reference to the canvas context.

For starters, we can hard-code the values of our piece:

export class Piece implements IPiece {
  x: number;
  y: number;
  color: string;
  shape: number[][];

  constructor(private ctx: CanvasRenderingContext2D) {
    this.spawn();
  }

  spawn() {
    this.color = 'blue';
    this.shape = [[2, 0, 0], [2, 2, 2], [0, 0, 0]];

    // Position where the shape spawns.
    this.x = 3;
    this.y = 0;
  }
}

To draw the tetromino on the board, we loop through all the cells of the shape. If the value in the cell is greater than zero, then we color that block:

draw() {
  this.ctx.fillStyle = this.color;
  this.shape.forEach((row, y) => {
    row.forEach((value, x) => {
      if (value > 0) {
        // this.x & this.y = position on the board
        // x & y position are the positions of the shape
        this.ctx.fillRect(this.x + x, this.y + y, 1, 1);
      }
    });
  });
}

You might have noticed that I set the sides of the block to one. That is tiny, so we need to scale it to the block size:

this.ctx.scale(BLOCK_SIZE, BLOCK_SIZE);

The board should keep track of the tetromino on the board so we can create and paint it when we press the play button:

play() {
  this.board = this.boardService.getEmptyBoard();
  this.piece = new Piece(this.ctx);
  this.piece.draw();
}

The blue J tetromino appears!

Next, let’s see about making things happen through our keyboard.

Keyboard input

Now, let’s see how we move pieces on the board. The move function changes the current pieces x or y variable to change its position on the board.

move(p: IPiece) {
  this.x = p.x;
  this.y = p.y;
}

Next, we map the keys to the key codes:

export class KEY {
  static readonly LEFT = 37;
  static readonly RIGHT = 39;
  static readonly DOWN = 40;
}

To match the key events to actions we can use object literal lookups. We need the brackets to get computed property names so that we can use our constants. This is a simplified example of how it works:

const X = 'x';
const a = { [X]: 5 };
console.log(a.x); // 5

We want to send in the current tetromino and return a copy of it together with the change in coordinates. For this, we can use the spread operator to get a shallow copy, and then change the coordinates to our desired position.

In JavaScript, we can use shallow copying to copy primitive data types like numbers and strings. In our case the coordinates are numbers. ES6 offers two shallow copy mechanisms: Object.assign() and the spread operator.

In other words, a lot is going on in this code snippet:

moves = {
  [KEY.LEFT]:  (p: IPiece): IPiece => ({ ...p, x: p.x - 1 }),
  [KEY.RIGHT]: (p: IPiece): IPiece => ({ ...p, x: p.x + 1 }),
  [KEY.UP]:    (p: IPiece): IPiece => ({ ...p, y: p.y + 1 })
};

Which we can use like this to get the new state without mutating the original piece. It’s important because we don’t always want to move to a new position.

const p = *this*.moves[event.key](*this*.piece);

To listen for keyboard events, we can use the @HostListener decorator within our board component:

@HostListener('window:keydown', ['$event'])
keyEvent(event: KeyboardEvent) {
  if (this.moves[event.keyCode]) {
    // If the keyCode exists in our moves stop the event from bubbling.
    event.preventDefault();
    // Get the next state of the piece.
    const p = this.moves[event.key](this.piece);
    // Move the piece
    this.piece.move(p);
    // Clear the old position before drawing
    this.ctx.clearRect(0, 0, this.ctx.canvas.width, this.ctx.canvas.height);
    // Draw the new position.
    this.piece.draw();
  }
}

Now we are listening on the keyboard events, and if we press left, right, or down arrows, then we can see the piece moving.

We have a movement! However, ghost pieces going through walls are not what we want. 👻

Collision detection

Tetris would not be a particularly exciting game if all blocks could pass through each other, or if the walls and floor did not stop them. So instead of moving the tetromino, we’ll check for potential collisions first, and then only move the tetromino if it’s safe. We have a few different collisions to consider.

We have a collision when the tetromino:

• Hits the floor.

• Moves left or right into a wall.

• Hits a block on the board.

• Rotates, and the new rotation hits a wall or block.

We already defined the potential new position for the shape. Now we can add a check if this position is valid before we move to it. To check for collisions, we loop through all the spaces in the grid that the tetromino would take up in its potential new position.

The array method best suited for this is every(). With it, we can check whether all elements in the array pass the tests we provide. We calculate the coordinates of every block of the piece and check that it’s a valid position:

valid(p: IPiece): boolean {
  return p.shape.every((row, dy) => {
    return row.every((value, dx) => {
      let x = p.x + dx;
      let y = p.y + dy;
      return (
        this.isEmpty(value) ||
       (this.insideWalls(x) &&
        this.aboveFloor(y)
      );
    });
  });
}

By using this method before we move, we make sure that we don’t move anywhere we shouldn’t:

if (this.service.valid(p)) {
  this.piece.move(p);
}

Let’s try going outside the grid again.

No more ghosting! We can’t leave the playing area anymore.

Now that the floor stops the tetromino, we can add another move called the hard drop. Pressing space drops the tetromino until it collides with something. And remember we need to add the new key mapping and move:

export class KEY {
  static readonly SPACE = 32;
  // ...
}

moves = {
  [KEY.SPACE]: (p: IPiece): IPiece => ({ ...p, y: p.y + 1 })
  // ...
};

if (event.keyCode === KEY.SPACE) {
  while (this.service.valid(p, this.board)) {
    this.piece.move(p);
    p = this.moves[KEY.DOWN](this.piece);
  }
}

What’s next?

Rotation

Now we can move around, but it would not be any fun if we can’t rotate the piece. We need to rotate the tetrominos around their center.

It has been a while since I studied linear algebra in school. But, to rotate clockwise goes something like this:

A rotation by 90 degrees can be accomplished by two reflections at a 45-degree angle so you can take the transpose of the matrix and then multiply it by the permutation matrix that reverses the order of the columns.

And in JavaScript:

// Transpose matrix
for (let y = 0; y < this.shape.length; ++y) {
  for (let x = 0; x < y; ++x) {
    [this.shape[x][y], this.shape[y][x]] = 
    [this.shape[y][x], this.shape[x][y]];
  }
}

// Reverse the order of the columns.
this.shape.forEach(row => row.reverse());

We can add a function that rotates the shape. Earlier we used the spread operator to clone the coordinates. In this case, we are working with a multiple level array but the spread operator only copies one level deep. The rest is copied by reference.

I’m instead using JSON.parse and JSON.stringify. The **stringify() method converts the matrix to a JSON string. The `parse()`** method parses the JSON string, constructing our matrix back again to a clone.

rotate(p: IPiece): IPiece {
  // Cloning with JSON
  let clone: IPiece = JSON.parse(JSON.stringify(p));

  // Do algorithm

  return clone;
}

Then we add a new state for ArrowUp in board.component.ts.

[KEY.UP]: (p: IPiece): IPiece => this.service.rotate(p)

Now we rotate!

Randomize Tetromino

To be able to get different kinds of pieces, we need to add a bit of randomization to our code.

Following the Super Rotation System, we can take the first position of the pieces and add them to our constants together with the colors:

export const COLORS = [
  'cyan',
  'blue',
  'orange',
  'yellow',
  'green',
  'purple',
  'red'
];
export const SHAPES = [
  [[0, 0, 0, 0], [1, 1, 1, 1], [0, 0, 0, 0], [0, 0, 0, 0]],
  [[2, 0, 0], [2, 2, 2], [0, 0, 0]]
  // And so on
];

We need to randomize the index of one of these to pick one piece. To get a random number, we create a function that uses the length of the array.

randomizeTetrominoType(noOfTypes: number): number {
  return Math.floor(Math.random() * noOfTypes);
}

With this method we can get a random tetromino type when we spawn and then set the color and shape from it:

const typeId = this.randomizeTetrominoType(COLORS.length);
this.shape = SHAPES[typeId];
this.color = COLORS[typeId];

If we press play the page shows pieces with different shapes and colors.

Game Loop

Almost all games have one main function that keeps the game running even when the user isn’t doing anything. This cycle of running the same core function over and over again is called the game loop. In our game, we need a game loop that moves the tetrominos down the screen.

RequestAnimationFrame

To create our game loop, we can use requestAnimationFrame. It tells the browser that we want to animate, and it should call a function to update an animation before the next repaint. In other words, we tell the browser: “Next time you paint on the screen, also run this function because I want to paint something too.”

“Animation is not the art of drawings that move but the art of movements that are drawn.” — Norman McLaren

The way to animate with window.requestAnimationFrame() is to create a function that paints a frame and then re-schedules itself. We need to bind the call to this, or it has the window object as its context. Since it doesn't contain the animate function, we get an error.

animate() {
  this.piece.draw();
  requestAnimationFrame(this.animate.bind(this));
}

We can remove all our previous calls to draw() and instead call animate() from the play() function to start the animation. If we try our game, it should still run like before.

Timer

Next, we need a timer. Every time frame, we drop the tetromino. There is an example on the MDN page that we can modify to our needs.

We start by creating an object with the info we need:

time = { start: 0, elapsed: 0, level: 1000 };

In the game loop, we update our game state based on the time interval and then draw the result:

animate(now = 0) {
  // Update elapsed time.
  this.time.elapsed = now - this.time.start;
  // If elapsed time has passed time for current level
  if (this.time.elapsed > this.time.level) {
    // Reset start time
    this.time.start = now;
    this.drop();
  }
  this.draw();
  requestAnimationFrame(this.animate.bind(this));
}

We have animation!

Next, let’s look at what happens when we reach the bottom.

Freeze

When we can’t move down anymore, we should freeze the piece and spawn a new one. Let’s start by defining freeze(). This function merges the tetromino blocks to the board:

We can’t see anything yet, but by logging the representation of the board, we can see that the shape is on the board.

Let’s add a function that draws the board:

freeze() {
  this.piece.shape.forEach((row, y) => {
    row.forEach((value, x) => {
      if (value > 0) {
        this.board[y + this.piece.y][x + this.piece.x] = value;
      }
    });
  });
}

Now the draw function should look like this:

draw() {
  this.ctx.clearRect(0, 0, this.ctx.canvas.width, this.ctx.canvas.height);
  this.piece.draw();
  this.drawBoard();
}

If we run the game, we can see that the pieces are showing up.

Now that we are freezing the pieces, we need to add new collision detection. This time we have to make sure that we don’t collide with frozen tetrominos on the board. We can do this by checking that the cell is zero. Add this to the valid method and send in the board as an argument:

board[p.y + y][p.x + x] === 0;

Now that we are adding pieces to the board it will quickly get crowded. We should do something about that.

Line clear

To last longer, we need to assemble the tetrominos in rows of blocks that span the entire row, resulting in a line clear. When you do so, the row disappears, causing the ones above it to settle.

Detecting formed lines is as easy as checking if it has any zeros:

this.board.forEach((row, y) => {
  // If every value is greater than 0.
  if (row.every(value => value > 0)) {
    // Remove the row.
    this.board.splice(y, 1);
    // Add a zero filled at the top.
    this.board.unshift(Array(COLS).fill(0));
  }
});

We can add a call to this clearLines() function after the freeze() call. We can try playing and hopefully see the rows getting cleared.

Points

To get a bit more excitement, we need a points system. From the Tetris guideline we get these values:

export class Points {
  static readonly SINGLE = 100;
  static readonly DOUBLE = 300;
  static readonly TRIPLE = 500;
  static readonly TETRIS = 800;
  static readonly SOFT_DROP = 1;
  static readonly HARD_DROP = 2;
}

Let’s add the points for soft and hard drops first in our event handler:

@HostListener('window:keydown', ['$event'])
  keyEvent(event: KeyboardEvent) {
    if (this.moves[event.key]) {
      event.preventDefault();
      let p: ITetromino = this.moves[event.key](this.piece);
      if (event.key === ' ') {
        while (this.service.valid(p, this.board)) {
          this.points += Points.HARD_DROP; // Points for every drop
          this.piece.move(p);
          p = this.moves[' '](this.piece);
        }
      } else if (this.service.valid(p, this.board)) {
        this.piece.move(p);
        if (event.key === 'ArrowDown') {
          this.points += Points.SOFT_DROP; // Points if we move down
        }
      }
    }
  }

Now for the line clear points. Depending on the number of lines, we get the defined points:

getLineClearPoints(lines: number): number {
  return lines === 1 ? Points.SINGLE :
         lines === 2 ? Points.DOUBLE :
         lines === 3 ? Points.TRIPLE :
         lines === 4 ? Points.TETRIS : 0;
}

For this to work, we need to add a bit of logic to count how many lines we clear:

clearLines() {
  let lines = 0; // Set variable
  this.board.forEach((row, y) => {
    if (row.every(value => value !== 0)) {
      lines++; // Increase for cleared line
      this.board.splice(y, 1);
      this.board.unshift(Array(COLS).fill(0));
    }
  });
  if (lines > 0) {
    // Add points if we cleared some lines
    this.points += this.getLineClearPoints(lines);
  }
}

If we try playing now, we can see that we are increasing our score.

Levels

When we get better at Tetris, the speed we start on will get too easy. And too easy means boring. So we need to increase the level of difficulty. We do this by decreasing the interval speed in our game loop.

export const LINES_PER_LEVEL = 10;

export class Level {
  static readonly 0 = 800;
  static readonly 1 = 720;
  static readonly 2 = 630;
  static readonly 3 = 550;
  // ...
}

We can also show the player which level they are currently on. The logic of keeping track and showing levels and lines is the same as for points. We initialize a value for them, and when we start a new game, we have to reset them.

We can move the initialization of the game to a function and call it in ngOnInit and play:

resetGame() {
  this.points = 0; 
  this.lines = 0;
  this.level = 0;
  this.board = this.getEmptyBoard();
}

Depending on the level we get more points for line clears. We multiply the points with the level we are on. And since we start on level 0 add one to it:

(level + 1) * lineClearPoints;

We increase the level every time we reach the lines we have per level. We also need to add the time we have on this level:

if (lines > 0) {
  // Calculate points from cleared lines and level.

  this.points += this.service.getLinesClearedPoints(lines, this.level);
  this.lines += lines;

  // If we have reached the lines per level
  if (this.lines >= LINES_PER_LEVEL) {
    // Goto next level
    this.level++;

    // Remove lines so we start working for the next level
    this.lines -= LINES_PER_LEVEL;

    // Increase speed of game.
    this.time.level = Level[this.level];
  }
}

Now if we play and clear 10 lines we should see the level increase and our points score double. And of course the game starts moving a bit faster.

Game Over

If you play for a while, you notice that the game never ends. The tetrominos keep on falling forever. So we need to know when to end the game.

After we drop we can check if we are still on row 0 and in that case, we can stop the game by exiting the game loop function:

if (this.piece.y === 0) {
  this.gameOver();
  return;
}

Before we exit, we call cancelAnimationFrame to stop it. Also, we print a message to the user.

gameOver() {
  cancelAnimationFrame(this.requestId);
  this.ctx.fillStyle = ‘black’;
  this.ctx.fillRect(1, 3, 8, 1.2);
  this.ctx.font = ‘1px Arial’;
  this.ctx.fillStyle = ‘red’;
  this.ctx.fillText(‘GAME OVER’, 1.8, 4);
}

Next tetromino

Let’s add one last thing. The next tetromino. We can add another canvas for this:

<canvas #next class=”next”></canvas>

Next, we do as we did for our first canvas:

@ViewChild('next', { static: true })
canvasNext: ElementRef<HTMLCanvasElement>;

ctxNext: CanvasRenderingContext2D;

initNext() {
  this.ctxNext = this.canvasNext.nativeElement.getContext('2d');

  // Size it for four blocks.
  this.ctxNext.canvas.width = 4 * BLOCK_SIZE;
  this.ctxNext.canvas.height = 4 * BLOCK_SIZE;

  this.ctxNext.scale(BLOCK_SIZE, BLOCK_SIZE);
}

// Create and draw it in play function
play() {
  // ...
  this.next = new Piece(this.ctx);
  this.next.drawNext(this.ctxNext);
  // ...
}

We have to change the logic a bit in the drop function. Instead of creating a new piece we set it to the next and instead create a new next piece:

this.piece = this.next;
this.next = new Piece(this.ctx);
this.next.drawNext(this.ctxNext);

Now we can be a bit more strategic when we see the next piece coming.

Improvements

There are always improvements that to be made to a game. Some that I can think of:

• Highscore

• Pause

• Music and FX

• AI

So why not fork the repository and implement them!

Conclusion

Today we made a game! We learned how to represent and track the objects we paint on the screen. We learned to move these objects and to respond to the boundaries of the game. I had a lot of fun with this project, and I recommend it as a way of honing your programming skills.

And now that we have taken our first steps into game development, the only question that remains is: What game is next?

Thanks to Tim Deschryver for reviewing the article and code.

Code on GitHub

Here’s what we create in this article:

The application we create has one page for Angular and one for React. The add button and shopping cart are Web Components made with Angular Elements. There is no state between the pages. The main point of the article is to show how we can use the same custom elements in different frameworks.

This isn’t a deep-dive, but I will walk-through the important parts for Web Component support in Angular and React. I’m not going to present all the HTML and CSS that I use but if you want to follow along all the code is here: Example code on GitHub. 📜

Web Components

Web Components is a web standard for defining new HTML elements in a framework-agnostic way. Since Web Components build on web standards, it opens up opportunities for code sharing across JavaScript frameworks.

Web Components are a set of technologies that let you create custom HTML elements compatible with regular HTML:

• Custom Elements to create custom HTML Elements.

• Shadow DOM encapsulates style and markup.

• ES Modules for module handling.

• HTML Template to declare content that can be rendered at run-time.

If you are interested in gaining more knowledge in this technology, then I recommend reading these articles:

• Developments in Web Components I’m excited about in 2019 by Max Koretskyi aka Wizard

• The Ultimate Guide to Web Components by Stefan Nieuwenhuis

• The State of Web Components by me

Angular Elements

Angular Elements provides a way to convert Angular components to native Web Components.

The @angular/elements package exports a [createCustomElement](https://angular.io/api/elements/createCustomElement)() API that provides a bridge from Angular's component interface and change detection functionality to the built-in DOM API.

Transforming a component to a custom element makes all of the required Angular infrastructure available to the browser, mapping Angular functionality to the corresponding native HTML equivalents.

For more in-depth on Angular Elements, check out these articles by Jia Li:

• Angular Elements: how does this magic work under the hood?

• Learn how Angular Elements transmits Component’s @Outputs outside Angular

OK, I wanted to keep the intro brief so we can start coding! 😏

Creating the Workspace

Since we want to be able to use React, the Angular CLI is not enough this time. Fortunately, Nrwl has developed the open-source toolkit Nx that extends the Angular CLI capabilities to React and helps us manage workspaces in a monorepo way.

We are using Nx to build Angular and React applications with a library of shared web components. Let’s start by creating a workspace:

npx create-nx-workspace reactangular

I’m starting with an empty workspace. After the installation, we need to add Angular and React capabilities to the workspace:

cd reactangular
ng add @nrwl/angular
ng add @nrwl/react

Now, we are ready to create the applications.

Angular App

First, we create an Angular application:

ng g @nrwl/angular:app angularapp --defaults

I have added some HTML and styles to spice the page up. It’s not relevant to our story of web components, but if you are interested, you can check the code on GitHub. Let’s make sure that it’s working:

ng serve -o angularapp

The first application is working! Awesome! 😻

Let’s see if we can get React working now that we have the ball rolling.

React App

Next, we create a React application:

ng g @nrwl/react:app reactapp --defaults

Also, I added a bit of fragrance to the code. Now let’s check that it runs:

ng serve reactapp

It’s also working! Beautiful! 😍

Let’s have a look at the scripts next to get a better developer experience.

Running in parallel

Since we have to run more than one application at once, I use a package called Concurrently to run multiple commands in parallel.

npm i concurrently -D

In this case, I want to start my Angular and React applications at the same time, so edit the start script inpackage.json.

"start": "concurrently \"ng serve -o angularapp\" \"ng serve reactapp --port 4201\""

Since we need to use different ports, we send in the port flag to the React app. So, instead of running scripts in two terminals, we can just run:

npm start

We can start both applications with one script! 🎉

Now that we have our applications running let’s start with the elements library.

Angular Elements Library

We can add a new library project for our Angular Elements:

ng g @nrwl/angular:lib elements --defaults

With one CLI command, we add the elements package and make changes in angular.json:

ng add @angular/elements

Add-to-cart Button

Now let’s create add-to-cart.component that has the input property type to know what we are adding to the cart and then outputs the addToCart event with this type.

import { Component, EventEmitter, Output, Input } from '@angular/core';

@Component({
  template: `
    <button mat-raised-button color="primary" (click)="add()">Buy</button>
  `
})
export class AddToCartComponent {
  @Input() type: string;
  @Output() addToCart = new EventEmitter<string>();

  add() {
    this.addToCart.emit(this.type);
  }
}

Now that we have the component, we need to change elements.module.ts to define it as a custom element. Notice, that we do not have a regular bootstrap. Instead, we do a manual bootstrap where we define the custom element and then add it to entryComponents.

A component can also be bootstrapped imperatively in the module’s *ngDoBootstrap() method. The `@NgModule.bootstrap`* property tells the compiler that this is an entry component and it should generate code to bootstrap the application with this component.

import { NgModule, Injector } from '@angular/core';
import { CommonModule } from '@angular/common';
import { BrowserModule } from '@angular/platform-browser';
import { createCustomElement } from '@angular/elements';
import { AddToCartComponent } from './add-to-cart.component';

@NgModule({
  imports: [BrowserModule, CommonModule],
  declarations: [AddToCartComponent],
  entryComponents: [AddToCartComponent]
})
export class ElementsModule {
  constructor(private injector: Injector) {}

  ngDoBootstrap() {
    const el = createCustomElement(AddToCartComponent, {
      injector: this.injector
    });

    customElements.define(`add-to-cart-button`, el);
  }
}

Now, that we have registered the custom element, let’s see how we use it. Wait! I almost forgot one thing. For a pleasant development experience, you can add this code to index.ts.

import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { ElementsModule } from './lib/elements.module';

platformBrowserDynamic()
  .bootstrapModule(ElementsModule)
  .catch(err => console.error(err));

If you want to take the next step and build your Angular Elements then Manfred Steyer is your guy. Check out his tool ngx-build-plus and his articles on this subject:

• Your Options For Building Angular Elements With The CLI

Web component in Angular

It’s time to consume our custom element in Angular. First of all, we need to import it in app.component.ts:

import '@reactangular/elements';

Now, we can use the custom element in app.component.html:

<add-to-cart-button></add-to-cart-button>

Nx does this by default but make sure the target in tsconfig.json is es2015.

If we save and try to run, we get an error message. I wanted to show it since it’s a very nice error that says what we need to do. 😍

So, since we have a Web Component then let’s do as the message suggests and add CUSTOM_ELEMENTS_SCHEMA in app.module.ts.

schemas: [CUSTOM_ELEMENTS_SCHEMA]

It tells the Angular compiler not to error when seeing non-standard element tags in components’ templates. Now we see our custom element!

We can set the type to Angular and catch the addToCart event of the button.

<add-to-cart-button type="Angular" (addToCart)="buy($event)"></add-to-cart-button>

If we add a buy function that console logs the event:

buy(type) {
  console.log(type);
}

We can see that the event created by the EventEmitter is a CustomEvent. The data that we emitted, “Angular,” can be seen in the detail attribute, where we can pick it up if needed.

Let’s see how we do the same thing in React.

Web component in React

First, we need to import the custom elements in app.tsx:

import '@reactangular/elements';

When we add the custom element, VS Code starts complaining:

We need to add a intrincic.d.ts file, which serves a similar purpose as CUSTOM_ELEMENTS_SCHEMA in Angular.

declare namespace JSX {  
  interface IntrinsicElements {    
    [elemName: string]: any;  
  }
}

We also need to add a couple of polyfills:

import 'reflect-metadata';
import 'zone.js';

Angular uses zone.js by default for change detection, so you have to make sure that it’s loaded into the browser when using React. Next level would be to turn off zone.js and do manual change detection.

• Do you still think that NgZone (zone.js) is required for change detection in Angular? by Max Koretskyi aka Wizard

Now we can see the component, and if we click it, we can see the type React in the console. The connection from React to the Custom element is working!

That’s awesome! Let’s create another custom element!

Cart Component

Next, let’s create a shopping cart. It should be an icon with a badge that says how many items we have in the cart.

The best way to create a fully self-contained component is to embed the images into the component using DATA URIs. You would encode the image file into a text format, like Base64, and then use that text data in the src attribute:

<img src="data:image/png;base64,your-base-64-encoded-image-data" />

There are many ways to encode the icon, and one is to run this command in the console (if you are using a good console):

base64 cart.png

After adding the styles, the cart component looks like this:

View Encapsulation

If we add the component to a page and inspect the HTML it looks like this:

Let’s change to ViewEncapsulation.ShadowDom and now we get #shadow-root for our component:

If Custom elements are the way to create a new HTML, Shadow DOM is the way you provide its HTML and CSS. It’s optional, but it provides advantages like CSS scoping and DOM encapsulation.

If we were using ViewEncapsulation.Emulated, we would have to worry about styles bleeding in and out of the component; using ShadowDOM solves this issue by placing the styles inside of the #shadow-root.

You can read more on this here:

• Shadow DOM v1: Self-Contained Web Components

Cart component in Angular

Now we need to get the communication between the button and shopping cart to get working.

The cart has an input property named counter that we can pass to it. Let’s create a local counter that we pass to the shopping cart.

<shopping-cart [counter]="counter"></shopping-cart>

Now to see that it works we can add to the counter every time we click the button.

buy(type: CustomEvent) {
  this.counter++;
}

We have communication between our web components!

Let’s see if we can do the same in React.

Cart component in React

To get the communications flowing in the React component, we need a couple of things. First, we need some local state in the constructor:

this.state = { counter: 0 };

Then we can use the counter in the element.

<shopping-cart counter={this.state.counter} />

Next, we need to update the state when clicking the button. For this, we need to reference the button element.

<add-to-cart-button type="React" ref={this.buttonRef} />

And then listen for the button events. We can map the Web Component events in the componentDidMount() life-cycle hook. Only showing the essential parts, it looks something like this:

import React, { Component } from 'react';
import '@reactangular/elements';

class App extends Component {
  private buttonRef;
  constructor(props) {
    super(props);
    this.state = { counter: 0 };
    this.buttonRef = React.createRef();
  }

  componentDidMount() {
    this.buttonRef.current.addEventListener('addToCart', () =>
      this.setState({ counter: this.state.counter + 1 })
    );
  }

  componentWillUnmount() {
    this.buttonRef.current.removeEventListener('addToCart');
  }

  render() {
    return (
      <>
        <shopping-cart counter={this.statecounter} />
        <add-to-cart-button type="React" ref={this.buttonRef} />
      </>
    );
  }
}
export default App;

Or if you are more into hooks, here’s a Gist for that.

And now we should be able to communicate between the components!

Beautiful! We have achieved what we wanted! 🎉

Conclusion

So, in the end we were able to use the same components created with Angular Elements in both Angular and React. I don’t know about you, but I think this is awesome! 🚀 In Angular, it was straightforward to consume and communicate with the custom element. React was a bit more tricky, but not too hard.

Using Nx helped us to get started fast with creating a monorepo with applications and a library. It really shines when you are using multiple frameworks together.

If you are working in an environment with multiple frameworks, then Web Components could be an option. It’s great to be able to share native components with different frameworks. I’m sure you can think of some use cases for them. I only recently dove into this rabbit hole of technologies and I like what I’m seeing! 🐰

Call to Action

I always enjoy feedback, so please 👏, 📝 and tweet 🐦. Follow me on Twitter and Medium for blog updates.

Resources

• Example code on GitHub. 📜

• Nx

• Angular Elements Docs

• Building Angular and React Applications Together With Nx by Victor Savkin

These are some of the questions I try to answer in this article. However, for those who are wondering what I am talking about, let’s start from the beginning.

Why Web Standards?

Before there were any rules, the browser manufacturers kept introducing new features to better their competition. Browsers were diversified, and developers often had to make multiple versions of websites.

Web standards were finally introduced to protect the web ecosystem. Browser makers started working in a more standardized way unifying the browser stack.

The key groups for web standards are:

• The World Wide Web Consortium (W3C)

• The Web Hypertext Application Technology Working Group (WHATWG).

These are the community of people producing the standards that build up the web platform.

Web Components

In 2010–2011, people at Google started crafting the first drafts of what we now know as Web Components. The specifications are a set of web platform APIs that let you extend the browser’s built-in HTML tags. Components built on the Web Component standards work across modern browsers and with any JavaScript library or framework that works with HTML.

Web Components are framework agnostic components based on web standards.

These are the main specifications in the umbrella term that is Web Components: ☔️

• Custom Elements let developers create their HTML Elements.

• Shadow DOM lets us encapsulate style and markup in web components.

• ES Modules is the ECMAScript standard for working with modules.

• HTML Template defines how to declare fragments of markup that go unused at page load, but can be instantiated later on at runtime.

  Sometimes people use Web components and Custom elements interchangeably.

HTML imports were part of the spec before ES6 modules replaced them. There are now new proposals on HTML Modules and CSS Modules.

How do they work?

Here’s a simplified example of how to create a Web component:

class MagicButton extends HTMLElement {
  // Magic goes here
}

customElements.define('magic-button', MagicButton);

The class for our custom element is a regular JavaScript class which extends the native HTMLElement. When we call customeElements.define(...) we register the custom element in the CustomElementRegistry. Then we can use it with regular HTML:

<magic-button></magic-button>

Note that according to the specifications, your element needs to have at least one dash in its name to avoid conflicts with existing elements.

Why use Web Components?

Why should we write Web Components instead of writing components in our favorite framework? I mean these web standards move slowly while the frameworks move so fast we don’t even remember their version numbers anymore. ⚡️

What problem does providing a native component model solve?

They let you write encapsulated and reusable components. With Web Components, we gain interoperability. By having a standard interface and expressed as real HTML, they work with all the popular frameworks. Web components implemented using different libraries can even mix on the same page. We create them once and can then use them almost anywhere.

There are some excellent use cases for Web Components. For example, it’s popular with companies to unify the look and feel for their sites by writing their own Design Systems. By leveraging Web Components, they can share UI components across frameworks.

Another reason could be when a company or team decides to change tech stacks, because of Hype Driven Development or some important reason. If the library components are Web Components, then we don’t have to rewrite them.

Even people that are not familiar with programming but are familiar with HTML should be able to drop in a Web component on their page. The ease of use makes them perfect for enhancing content sites. Since it’s standard HTML, a maintainer of a Content Management System (CMS) can add it themselves.

So, we have some reasons to use Web Components, but can we use them in the browsers today?

Browser support

When the Chromium-based Edge arrives, Web Components are finally going to be available in all evergreen browsers.

Screenshot from https://webcomponents.org**

I’m sure someone is asking: What about Internet Explorer, a product Microsoft officially discontinued in 2015?

As you can see on this page 7,7% (May 2019) of desktop users are still stuck in on Internet Explorer. That’s more than are using Edge! 😱

Luckily, we have polyfills for them!

With support in evergreen browsers and good polyfills, we can use Web Components in basically any browser, including mobile. ✔️

Framework support

As you can see on the page Custom Elements Everywhere, the support for Custom Elements is excellent and getting even better all the time.

Even the frameworks with the worst Custom elements support are slowly but surely working on improving the situation, and workarounds are available.

Web Components work with any JavaScript library or framework that works with HTML. ✔️

Is anyone using Web Components?

According to Chrome Platform Status, about 8% (mid-2019) of all pages today use Web components. That makes it one of the most successful new web platform features in the last years. 📈

We can find Web components on popular sites like YouTube and GitHub. Moreover, some big companies have decided that Web Components is the best way to implement Design systems going forward. Like Ionic with Stencil and Salesforce with their Lightning Web Components.

Here is a talk about the state of web components from Google I/O 2019:

Frameworks

Wasn’t one of the points of Web components to get rid of frameworks? While it’s fine to write your components without frameworks, let me tell you in one word why you might want one: Boilerplate!

Here are some popular frameworks to check out:

• LitElement

• Stencil

• SkateJS

It can also be possible to create web components with your favorite JavaScript framework. For example, Angular Elements provides a way to wrap Angular components as web components.

UI Libraries 📚

Since Web Components work in all frameworks, creating UI libraries seems like a good idea. There are some great libraries out there. I have not done an extensive search, but here are a few examples:

• Material Web Components

• Vaadin

• Wired Elements

• Ionic

Are there no downsides?

I have been very positive on Web Components in this article. There are, of course, some downsides to them as well. I have touched upon some of them briefly but let’s try to summarize the main points I can think of:

• Web standards can move slowly.

• Polyfills for Internet Explorer.

• Don’t work friction-less with all frameworks.

Look, I love my JavaScript frameworks. I work with React and Angular, and they are fantastic. I’m sure Vue and Svelte and what-not are equally impressive. Web components are not going to replace them. They solve different problems, so there should be no animosity between these technologies.

Conclusion

If you have followed along with this article, you see that Web Components are used today and supported by all modern browsers. Moreover, there are polyfills for when you need to support the Jurassic kind. There are some excellent use cases for Web Components, and these are gaining in popularity.

It took 10 years for browser vendors to unite and standardize ES5. Another six years to get back together for ES2015. It took 15 years for HTML5 to be standardized. We fought cross-browser compatibility for more than a decade.

Enough with the framework wars. Let’s unite. Let’s embrace Web Components. 👐 🚀

Thanks to Lars Gyrup Brink Nielsen for helping me review this article!

Resources

• Developments in Web Components I’m excited about in 2019 by Max Koretskyi aka Wizard

• Why We Use Web Components by Max Lynch

• Understanding the CustomElementRegistry Object by Gil Fink

• 9 Web Components UI Libraries You Should Know in 2019 by Jonathan Saring

With baby steps. 👣

First, we need some 2D graphics. In this case, it’s moving some blocks on the screen. So, in this article, I will show how to draw and animate objects using the HTML5 Canvas and JavaScript. I will also go through some techniques to optimize performance. Who knows, it might come in handy some day.

“Animation is not the art of drawings that move but the art of movements that are drawn.” — Norman McLaren

Photo by JESHOOTS.COM on Unsplash

Introduction

Apple introduced canvas in 2004 to power applications and the Safari browser. A few years later it was standardized by the WHATWG. It comes with finer grained control over rendering but with the cost of having to manage every detail manually. In other words, it can handle many objects, but we need to code everything in detail.

The canvas has a 2D drawing context used for drawing shapes, text, images, and other objects. First, we choose the color and brush, and then we paint. We can change the brush and color before every new drawing, or we can continue with what we have.

Canvas uses immediate rendering: When we draw, it immediately renders on the screen. But, it is a fire-and-forget system. After we paint something, the canvas forgets about the object and only knows it as pixels. So there is no object that we can move. Instead, we have to draw it again.

Doing animations on Canvas is like making a stop-motion movie. In every frame need to move the objects a little bit to animate them.

Using Canvas ✏️

To get started, we need to add a canvas element in our HTML. We'll also attach a reference variable to the element so that we'll be able to refer to it from the component class:

<canvas #canvas width="600" height="300"></canvas>

In the component class, we can then use the **@ViewChild() decorator to inject a reference to the canvas. In Angular 8**, a new static flag has been introduced not to break existing applications. Read more about it here. Since I want access to the canvas in the ngOnInit hook I set it to true.

@ViewChild('canvas', { static: true }) 
canvas: ElementRef<HTMLCanvasElement>;

Once the component has initialized, we’ll have access to the Canvas DOM node, as well as its drawing context:

this.ctx = this.canvas.nativeElement.getContext('2d');

Here is the starting code for the component:

import { Component, ViewChild, ElementRef, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <canvas #canvas width="600" height="300"></canvas>
    <button (click)="animate()">Play</button>   
  `,
  styles: ['canvas { border-style: solid }']
})
export class AppComponent implements OnInit {
  @ViewChild('canvas', { static: true })
  canvas: ElementRef<HTMLCanvasElement>;  

  private ctx: CanvasRenderingContext2D;

  ngOnInit(): void {
    this.ctx = this.canvas.nativeElement.getContext('2d');
  }

  animate(): void {}
}

Now we have a canvas and a button to start the animation.

Let’s paint something on it!

Painting 🔵

Once we have a canvas context in the component class, we can draw on it using the standard canvas context API. We can use fillRect() to draw a square. It draws a filled rectangle colored by the current fill style.

ctx.fillRect(x, y, width, height);

So to draw a small red rectangle with a side of 5 pixels:

this.ctx.fillStyle = 'red';
this.ctx.fillRect(0, 0, 5, 5);

To outline the square, we could use strokeRect():

this.ctx.strokeRect(z * x, z * y, z, z);

Let’s create a Square class with a drawing method that draws squares:

export class Square {
  constructor(private ctx: CanvasRenderingContext2D) {}

  draw(x: number, y: number, z: number) {
    this.ctx.fillRect(z * x, z * y, z, z);
  }
}

I’m using z here for the side lengths of the squares. Let’s try to use it in animate():

animate() {
  this.ctx.fillStyle = 'red';
  const square = new Square(this.ctx);
  square.draw(5, 1, 20);
}

We have painted our first element on the canvas! 🎉

Check out some more advanced examples on MDN.

Like this blog post? Share it on Twitter! 🐦

Animation 🎥

Now, let’s see if we can get our block to move on the canvas. We can create a function for this. With a loop, we can move the x value on the canvas and draw the object over and over again. Here I move the block to the right until it reaches the canvas end. We send in y for vertical position and z for size.

move(y: number, z: number) {
  const max = this.ctx.canvas.width / z;
  for (let x = 0; x < max; x++) {
    this.draw(x, y, z);
  }
}

Let’s change from drawing the square to moving it:

square.move(1, 30);

OK, we were able to draw the square as we wanted. But we have two issues:

1. We are not cleaning up after us.

2. It’s too fast to see the animation.

We need to clear away the old block. What we can do is to erase the pixels in a rectangular area with clearRect(). By using the width and height of the canvas, we can clean it between paints:

move(y: number, z: number) {
  const max = this.ctx.canvas.width / z;
  const canvas = this.ctx.canvas;
  for (let x = 0; x < max; x++) {
    this.ctx.clearRect(0, 0, canvas.width, canvas.height);
    this.draw(x, y, z);
  }
}

Great! We fixed the first problem. Now let’s try to slow down the painting so we can see the animation.

You might be familiar with setInterval(function, delay). It starts repeatedly executing the specified function every delay milliseconds. I set the interval to 200 ms, which means the code will run five times a second.

move(y: number, z: number) {
  const max = this.ctx.canvas.width / z;
  const canvas = this.ctx.canvas;
  let x = 0;
  const i = setInterval(() => {
    this.ctx.clearRect(0, 0, canvas.width, canvas.height);      
    this.draw(x, y, z);
    x++;
    if (x >= max) {
      clearInterval(i);
    }
  }, 200);    
}

To stop a timer created by setInterval, you need to call clearInterval and give it the identifier for the interval you want to cancel. The id to use is the one that is returned by setInterval, and this is why we need to store it.

We can now see that if we press the button, we get a square that moves from left to right.

But, if we press the play button several times, we can see that there is a problem when we try to animate multiple squares at the same time. It’s not working when every block has an interval that clears the board and paints on its own.

It’s all over the place! Let’s see how we can fix this.

Multiple objects

To be able to run the animations for several blocks, we need to rethink the logic. We only need one interval that paints all the objects simultaneously. Every time we press the play button, we add a new Square to a squares-array. The interval then clears the screen and paints all the objects in the array. This way, we avoid the flicker we had before.

setInterval(() => {
  this.ctx.clearRect(0, 0, this.width, this.height);
  this.squares.forEach((square: Square) => {
    square.moveRight();
  });
}, 200);

We can move the coordinates to the square model since we don’t need to know about its internals to move it. Instead of a general move command we could call it with commands to move in different directions.

export class Square {
  private color = 'red';
  private x = 0;
  private y = 0;
  private z = 30;

  constructor(private ctx: CanvasRenderingContext2D) {}

  moveRight() {
    this.x++;
    this.draw();
  }

  private draw() {
    this.ctx.fillStyle = this.color;
    this.ctx.fillRect(this.z * this.x, this.z * this.y, this.z, this.z);
  }
}

And now we get better animations.

What we did here is the first step of making a game loop. This loop is the heart of every game. It’s a controlled infinite loop that keeps your game running — it’s the place where all your little pieces will be updated and drawn on the screen.

🚶Optimize animations 🏃

Another option for animating is to use requestAnimationFrame. It tells the browser that you wish to perform an animation and requests the browser to call a function to update an animation before the next repaint. In other words, we tell the browser: “Next time you paint on the screen, also run this function because I want to paint something too.”

The way to animate with requestAnimationFrame is to create a function that paints a frame and then schedules itself to invoke again. With this, we get an asynchronous loop that will execute when we draw on the canvas. We will be invoking the animate method over and over again until we decide to stop.

animate() {
  // Do stuff
  const id = requestAnimationFrame(this.animate);  
}

There is no recursion here, since the function is not calling itself. It is requestAnimationFrame that is asking for animate to be called.

The requestAnimationFrame method returns an id that we use for canceling the scheduled animation frame. To cancel a scheduled animation frame, you can use the cancelAnimationFrame method. This method should be passed the id for the frame you wish to cancel.

cancelAnimationFrame(id);

So, in conclusion, why should we use requestAnimationFrame instead of setInterval or setTimeout?

• It enables browser optimizations.

• It handles the frame rate.

• Animations only run when visible.

Another gotcha with requestAnimationFrame is that when we re-schedule we need to bind the call to this, or it will have the window object as its context. Since the window object doesn't contain the animate`` function, we get an error like:Cannot read property ‘animate' of undefined.`

animate() {
  // Do stuff
  requestAnimationFrame(this.animate.bind(this));
}

What about Change Detection?

Angular applications execute inside an “Angular Zone”, which makes change detection automatically run without us having to do anything. When events like a mouse click or an HTTP response occur, we enter the zone and run the event handling code. Then, we exit and Angular performs change detection for the application. In most cases, you don’t need to worry about this. But when we fire timers frequently like like setInterval, setTimeoutor requestAnimationFrame, we are also firing off change detection.

By default, every requestAnimationFrame runs inside NgZone and triggers change detection. This could mean that we end up running change detection 60 times a second. Since our application is small and Angular’s change detection is fast, we will most likely not notice it. But it could become a problem, so how do we solve it?

To run animations outside the zone, we use the ngZone.runOutsideAngular function. This function accepts a callback where we can execute the animate function.

constructor(private ngZone: NgZone) {}

...

this.ngZone.runOutsideAngular(() => this.animate());

This code runs the first frame outside the NgZone, and it will also run all the subsequent frames outside the zone. With this small change, we've achieved a potentially significant performance improvement to the animation loop.