Forem: Michael Karén

Angular Error Interceptor

Michael Karén — Mon, 14 Feb 2022 07:24:44 +0000

When applications make HTTP requests and fail, we need to handle them. Ideally, we take care of these errors in one place in our code. In this article, we discover how to handle these exceptions in Angular by using an interceptor. We look into the best steps to take directly in the interceptor before sending errors on their way to the error handler.

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.

Game Development: Breakout in JavaScript

Michael Karén — Mon, 31 Jan 2022 07:55:28 +0000

In this article, we create a complete Breakout-style game. The HTML Canvas provides the game container where we draw graphics via JavaScript. After learning how to use the Canvas for graphics and animations, we go through the algorithms behind collisions using basic shapes like circles and rectangles. With these concepts and a sprinkle of game loops and sound, we will soon have a game ready to be played!

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

How to Combine Add and Edit Forms in Angular

Michael Karén — Mon, 31 Jan 2022 07:48:03 +0000

This article demonstrates how to build a reusable form component that supports add and edit modes. We do this by using the container and presentation components architecture. The goal is not about teaching forms, so we keep it as simple as possible using reactive forms.

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.

How To Get Started With Canvas Animations In JavaScript

Michael Karén — Wed, 26 May 2021 06:06:03 +0000

I love playing games. And I love coding too. So, one day, I got thinking, why not use those coding skills to make a game? But it sounds hard. How would one even get started?

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.

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

We are not cleaning up after ourselves.
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:

7 Useful JavaScript Tricks and Tips

Michael Karén — Mon, 10 May 2021 05:11:30 +0000

You Will Be Surprised By Number 9!

In this article, I gathered some JavaScript tips and tricks that I believe can make you a better JavaScript developer. In no particular order, here are seven (?) JavaScript tricks!

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.

A Promise of Asynchronous JavaScript

Michael Karén — Wed, 28 Apr 2021 19:47:45 +0000

In this article, we discover the problems with synchronous JavaScript and how we can solve them with the asynchronous techniques of callbacks, promises, and async/await.

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.

We log “Start”.
We execute the function which logs “in logFunction”
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.

Maintaining Multi-language Angular Applications with i18n

Michael Karén — Mon, 12 Apr 2021 08:55:04 +0000

Angular i18n and the localizing of applications had an overhaul with version 9, enabled by the new rendering engine Ivy. In this article, we take a closer look at how this built-in package of Angular now works, while pointing out the benefits and drawbacks we find.

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.

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:

Install Nginx
Add config from Angular Docs to conf/nginx.conf
Build our applications
Copy applications to the folder defined in root in nginx.conf.
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.