Tag: Into

02 Sep

A Deep Dive Into The Wonderful World Of SVG Displacement Filtering

by TBSCategories: News

Even today, the magic, wicked realm of SVG Filter Effects is largely uncharted territory. The art of SVG filtering is still surrounded by an aura of alchemy: you have to bravely dive into a dark world of inconsistencies, your dedication will repeatedly be tested by buggy implementations and nerve-wracking side effects, and you must learn complicated incantations. But, once mastered, it gives you unprecedented power — a means to switch the total appearance of elements and websites by the snap of a finger.

In this article, we’ll be diving into one of the most spectacular filter effects: the SVG feDisplacementMap filter primitive. In order to make it all easier to digest, I’ve divided the article into three parts in which we’ll be exploring:

  1. how the feDisplacementMap works, i.e. how to apply it and how to control its output in a predictable manner;
  2. we’ll then explore methods to create fancy displacement maps in SVG (slightly more interesting as we will start playing with JavaScript);
  3. and finally, we’ll take a look at some of the methods to animate the filter and create dramatic visual effects.

As this will be a rather long read, the impatient ones may want to check out the demos we’re going to encounter before continuing. All the demos in this article have been optimized for the latest versions of the three major browser engines.

To get the most out of this article, you should already have a basic understanding of SVG filters. If you are a filter novice, you may want to take a short detour to Sara Soueidan’s introduction or head over on to my humble take on the subject first.

Be warned though: not applied properly, SVG Filters can hurt the performance of your site drastically. Always test extensively if you roll out one of the techniques described here.

A Short Primer On Displacement Filtering

So what’s a displacement filter? A displacement operation can visually distort any graphic it is applied to. You can create warp effects, twirls or ripples like you would do with a Photoshop distortion filter. Displacement filtering is an important tool in VFX, and most likely you already saw some displacement mapping operations on film and TV, created with a VFX tool like After Effects or GiantRed.

To achieve a distortion effect the filter needs two images as input:

  • The actual source graphic should be distorted (from now on just “source”);
  • The “displacement map” (from now on just “map”). This map contains information on how we want the source to be distorted.

Most of the time, a map will be some Bitmap image, but in the next part, I will demonstrate how to use SVG images or fragments as an input.

Let’s see what happens when we use an image of Barcelona’s famous La Sagrada Familia to “distort” the Mona Lisa:

  1. The first filter primitive is feImage which holds a reference to the map (there are other filter primitives that can be used as an input. You will find several fascinating demos out there where feTurbulence is used as displacement map, but in this article, we will mostly focus on feImage).
  2. This feImage is then fed into a feDisplacementMap primitive where the actual distortion happens:
    • A positive or negative scale attribute defines the strength of the distortion.
    • The purpose of xChannelSelector and yChannelSelector is to determine which of the input image’s four-color channels (red, green, blue, alpha) should be applied to which axis for distortion. Both attributes default to the map’s alpha channel (which means if you’re using a map without alpha channels and omit these attributes, you’ll see nothing more than a diagonal shift of the source).

We then apply the filter with CSS:

.filtered {   filter: url(#displacement-filter); }

It may be fun to play around distorting images this way but it is unpredictable how the result will look and most of the time it’s not aesthetically pleasing at all. Is there a way to get pixel-perfect control over the output? Here’s what the spec says:

This filter primitive uses the pixels values from the image from in2 to spatially displace the image from in. This is the transformation to be performed:

P'(x,y) ← P( x + scale (XC(x,y) – .5), y + scale (YC(x,y) – .5))

The displacement map, in2, defines the inverse of the mapping performed.

OK, looks complicated at a first glance, but it is actually pretty easy to understand when broken down:

  • P'(x,y) stands for the coordinates of a pixel in the result;
  • X and Y are the coordinates of this pixel in the unfiltered source;
  • XC and YC are the normalized (1/255) RGB color values of the given pixel in the map;
  • Finally, the result of the operation must be inverted (which basically means every + in the formula must be replaced by a -).

We will run some simple experiments to verify our formula by feeding primitive bitmaps into a filter, consisting of only one single color. Let’s say the map is filled with rgb(51, 51, 51), how would we expect the coordinates of a source pixel at x=100 / y=100 to be transformed when fed into a displacement primitive with a scale value of 100?

X: 100 – 100 (51/255 – .5) = 130

Y: 100 – 100 (51/255 – .5) = 130

To scale an image equally in all directions, the color values must gradually decline from a maximum at one edge to a minimum at the opposite edge. We will use red for X and blue for Y from now on, but in the end, it doesn’t matter which color you chose for x- and yChannelSelector.

  1. In your favorite Image editor, open a new document;
  2. Set the background color of the document to black;
  3. Create a new layer and fill it with a left to right gradient from rgb(255, 0, 0) to rgba(255, 0, 0, 0);
  4. Add a second layer and add a top to bottom gradient from rgb (0, 0, 255) to rgba(0, 0, 255, 0);
  5. Set the blending mode for this layer to screen.

Et voilà, you’ve built an absolute map! This map will serve as a solid foundation for all kinds of image distortions:

  • By applying Photoshop-like distortion filters to this map, we are able to use these effects in CSS filters!
  • We can control the scaling of the x- and y-axis independently by altering the transparency of the blue or red gradient.
  • It is possible to “mask” parts of the map with a “neutral” color (rgb(127, 0 ,127) or #7F007F) to prevent the corresponding parts in the image from displacing.

The Problem With Jagged Edges

You may have noticed the pixelated edges that sometimes appear in the output image. Especially source material with high contrast, e.g. typography or vector artwork, is prone to this effect.

This is caused by several reasons:

  • The filter will take the source image as a bitmap:
    If there exist antialiased edges in the source, the filter will not “re-initialize” them after displacing the source. Any pixel will be transformed to its new location, that’s it.
  • Rounding errors:
    Maybe a pixel from 100,100 must be shifted to 83.276, 124.217. The filter must somehow map these coordinates to non-decimal pixel values.
  • Gaps after displacement:
    Maybe two neighboring pixels, say at coordinates x1:100, x2:101 are shifted to different locations, maybe x1:207.4, x2: 211.3. How will the filter fill the space in between? Hint: not at all. The spec clearly states:

“Sometimes filter primitives result in undefined pixels. For example, filter primitive feOffset can shift an image down and to the right, leaving undefined pixels at the top and left. In these cases, the undefined pixels are set to transparent black.”

— Filter Effects Module Level 1, W3C

My weapon of choice to fix this issue is to add a slight blur, then increase the contrast with a feConvolveMatrix. Not perfect, but good enough for most situations. Here’s a demo on CodePen:

  1. Insert a feImage primitive with a reference to the absolutemap;
  2. Create the “magnifying glass”, an SVG containing a circle filled with a radial gradient, starting at rgba(127, 0, 127, 0) and ending at rgba(127, 0, 127, 1);
  3. Insert a second feImage with a reference to the “magnifying glass”;
  4. Merge both images into an feMerge primitive and make the result the feDisplacementMap’s in2. As you may have noticed we’re using a negative scale factor here to make sure the image will be scaled down outside and is displayed at its normal size inside the “magnifying glass”;
  5. Add some JavaScript so that the x and y attributes of the feImage referencing the “magnifying glass” match the mouse position.

Generating Arbitrary Maps With Blurred Paths

A totally different way to build an SVG displacement map is by making use of extremely thick blurred bezier paths instead of gradients. Here’s a little app that lets you change the bezier anchor points in a map created this way.

It’s possible to create some pretty rad maps this way, but you should keep in mind that blurring has an impact on rendering performance. Firefox even has a threshold of 100px on how much blurring is allowed.

Animation

By now we learned everything about the main principles behind displacement filtering and how to create displacement maps in SVG. We are ready for the fun part: how to set everything into motion.

SVG filters can be animated and transitioned. A big problem is the fact that filter values referencing a URL will not be interpolated, but swapped out immediately without any transition in-between, a behavior that is in line with the spec. Can be ok in some situations, but boring most of the time. We want animated twirls, ripples, warps, and morphs!

When thinking of animated maps, the first thing that comes to mind is an animated gif or WebP. Well, animated images will work in every browser somehow. But performance varies greatly from quite bad to extremely bad. And then there are platform-related limitations: e. g. Blink is not able to apply this animated displacement filter to elements that contain other animated elements. And we didn’t talk about file size yet. Instead we will focus on the two most reliable animation techniques IMHO: SMIL (yes, SMIL still is a thing these days) and JavaScript.

A filter will usually be constructed from a variety of different primitives and every attribute that was added to a node, like x, y, width, height or scale can be animated with SMIL.

A Simple Glitch Effect

Here’s a very simple example: making use of an animated feFlood primitive to create a basic glitch effect:

This effect can be leveraged even more by throwing masks, blurs, and some colors into the mix. Here’s a pimped-up version of the effect using the same techniques, but in a more advanced way.

You may have noticed that depending on your browser and CPU, the performance of these demos can vary drastically. It’s a disappointing fact that SVG Filters are still not optimized for performance. Your GPU will accelerate some simple primitives (e. g. color operations), but when you build a compound filter chaining and merging many primitives you will quickly find framerates dropping and fans going up — especially in WebKit and Firefox. Browser vendors have a lot of topics on their to-do lists and SVG Filter Effects don’t have the highest priority there, especially as they still are not found that often out in the wild.

This doesn’t mean that you can’t use animated SVG Filters now, but you should apply them in a responsible way: preferably limit the dimensions of the animated paint area to the smallest possible rectangle, limit the number of iterations to the minimum, be careful with blurs and blending operations and test test test on many browsers and devices.

A good use case for animated filter effects are small, locally constrained animations applied to UI elements. Below is a demonstration of how the animated feImage effect from above can be used to spice up a rather boring progress bar:

A Glitch Transition Between Elements

  • Create 2 different SVGs for each channel in our map. For each color create a grid of rectangles with randomly varying color intensity.
  • Create 2 different feImage primitives. URL-encode each SVG, then put it into the href-attribute of each feImage.
  • Add SMIL animations for width, height, and y attributes.
  • Insert a feBlend and blend both feImages into a single output.
  • Add some colored feDropShadows for a cool split-color effect.
  • Blend everything, then feed it into a feDisplacementmap.
  • Animate the scale attribute with SMIL.
  • Feel free to experiment by changing forms (e. g. use circles instead of rects), applying different timings, adding blur effects, and more.

Animating The Map Itself

So far we have learned that animating filter attributes with SMIL can help us to achieve really cool visual effects. On the other hand, we already saw how SVG fragments can be used as a displacement map. As SVGs are animatable with JavaScript, SMIL and CSS, it would seem obvious that we can apply animations directly to an SVG map right?

Unfortunately, SMIL and CSS animations in SVG images used as input for feImage will not run when the SVG or fragment is URL encoded. We will need to write some JavaScript for a reliable solution and take into account that two different approaches for Webkit and Blink/Quantum browsers are necessary. In a first step, let’s see how the “ideal” way of animating a map will look:

  • Create the SVG fragment containing your map;
  • Reference it from the feImage that controls your feDisplacementMap’s in2;
  • Feel free to animate everything in your fragment with JavaScript as you like. Roll your own script or use your favorite library.

“This sounds too easy. Where’s the catch?” Of course, you are right. The method described above is the ideal path, the way things should work but, here’s a strange matter of fact: It will not work anywhere but Webkit. In order for our animation to run in Blink and Firefox, we must implement a rather hacky solution and you won’t like it:

  • Create the SVG fragment containing your map.
  • In every frame of your animation, change all the values of every animated attribute.
  • In every frame of your animation create a new URL encoded string containing a “snapshot” of the fragment and write it into the feImages href attribute.

You’re probably thinking: “This is ugly! I don’t like it and you are a despicable person!”. I feel your pain. The front end is a hostile habitat and sometimes we must do abhorrent things to survive (fun fact: the “ugly” method performs better in Blink than the “pure” method in Webkit will).

Let’s Rock!

Let’s solve a real-world problem with this approach: here’s what happens to “The Rock” when we apply these two simple displacement maps:

2. Using Animejs’ Grid Animation

Animejs’ staggering and “grid” properties can help you create really cool typographic effects. This effect was created by animating a grid of circles:

3. A “Waving Flag” Menu

An unconventional way of swapping a second-level submenu. The fade-in effect is achieved by moving a striped map horizontally:

Please note that the demos shown above are highly experimental and mainly intended to demonstrate the concept of animated displacement maps. If you want to use any of these techniques in a live project, always take my earlier recommendations to heart. And forgive me for not going into detail on every example — it simply would exceed the scope of this article.

Articles on Smashing Magazine — For Web Designers And Developers

02 Sep

A Deep Dive Into The Wonderful World Of SVG Displacement Filtering

by TBSCategories: News

Even today, the magic, wicked realm of SVG Filter Effects is largely uncharted territory. The art of SVG filtering is still surrounded by an aura of alchemy: you have to bravely dive into a dark world of inconsistencies, your dedication will repeatedly be tested by buggy implementations and nerve-wracking side effects, and you must learn complicated incantations. But, once mastered, it gives you unprecedented power — a means to switch the total appearance of elements and websites by the snap of a finger.

In this article, we’ll be diving into one of the most spectacular filter effects: the SVG feDisplacementMap filter primitive. In order to make it all easier to digest, I’ve divided the article into three parts in which we’ll be exploring:

  1. how the feDisplacementMap works, i.e. how to apply it and how to control its output in a predictable manner;
  2. we’ll then explore methods to create fancy displacement maps in SVG (slightly more interesting as we will start playing with JavaScript);
  3. and finally, we’ll take a look at some of the methods to animate the filter and create dramatic visual effects.

As this will be a rather long read, the impatient ones may want to check out the demos we’re going to encounter before continuing. All the demos in this article have been optimized for the latest versions of the three major browser engines.

To get the most out of this article, you should already have a basic understanding of SVG filters. If you are a filter novice, you may want to take a short detour to Sara Soueidan’s introduction or head over on to my humble take on the subject first.

Be warned though: not applied properly, SVG Filters can hurt the performance of your site drastically. Always test extensively if you roll out one of the techniques described here.

A Short Primer On Displacement Filtering

So what’s a displacement filter? A displacement operation can visually distort any graphic it is applied to. You can create warp effects, twirls or ripples like you would do with a Photoshop distortion filter. Displacement filtering is an important tool in VFX, and most likely you already saw some displacement mapping operations on film and TV, created with a VFX tool like After Effects or GiantRed.

To achieve a distortion effect the filter needs two images as input:

  • The actual source graphic should be distorted (from now on just “source”);
  • The “displacement map” (from now on just “map”). This map contains information on how we want the source to be distorted.

Most of the time, a map will be some Bitmap image, but in the next part, I will demonstrate how to use SVG images or fragments as an input.

Let’s see what happens when we use an image of Barcelona’s famous La Sagrada Familia to “distort” the Mona Lisa:

  1. The first filter primitive is feImage which holds a reference to the map (there are other filter primitives that can be used as an input. You will find several fascinating demos out there where feTurbulence is used as displacement map, but in this article, we will mostly focus on feImage).
  2. This feImage is then fed into a feDisplacementMap primitive where the actual distortion happens:
    • A positive or negative scale attribute defines the strength of the distortion.
    • The purpose of xChannelSelector and yChannelSelector is to determine which of the input image’s four-color channels (red, green, blue, alpha) should be applied to which axis for distortion. Both attributes default to the map’s alpha channel (which means if you’re using a map without alpha channels and omit these attributes, you’ll see nothing more than a diagonal shift of the source).

We then apply the filter with CSS:

.filtered {   filter: url(#displacement-filter); }

It may be fun to play around distorting images this way but it is unpredictable how the result will look and most of the time it’s not aesthetically pleasing at all. Is there a way to get pixel-perfect control over the output? Here’s what the spec says:

This filter primitive uses the pixels values from the image from in2 to spatially displace the image from in. This is the transformation to be performed:

P'(x,y) ← P( x + scale (XC(x,y) – .5), y + scale (YC(x,y) – .5))

The displacement map, in2, defines the inverse of the mapping performed.

OK, looks complicated at a first glance, but it is actually pretty easy to understand when broken down:

  • P'(x,y) stands for the coordinates of a pixel in the result;
  • X and Y are the coordinates of this pixel in the unfiltered source;
  • XC and YC are the normalized (1/255) RGB color values of the given pixel in the map;
  • Finally, the result of the operation must be inverted (which basically means every + in the formula must be replaced by a -).

We will run some simple experiments to verify our formula by feeding primitive bitmaps into a filter, consisting of only one single color. Let’s say the map is filled with rgb(51, 51, 51), how would we expect the coordinates of a source pixel at x=100 / y=100 to be transformed when fed into a displacement primitive with a scale value of 100?

X: 100 – 100 (51/255 – .5) = 130

Y: 100 – 100 (51/255 – .5) = 130

To scale an image equally in all directions, the color values must gradually decline from a maximum at one edge to a minimum at the opposite edge. We will use red for X and blue for Y from now on, but in the end, it doesn’t matter which color you chose for x- and yChannelSelector.

  1. In your favorite Image editor, open a new document;
  2. Set the background color of the document to black;
  3. Create a new layer and fill it with a left to right gradient from rgb(255, 0, 0) to rgba(255, 0, 0, 0);
  4. Add a second layer and add a top to bottom gradient from rgb (0, 0, 255) to rgba(0, 0, 255, 0);
  5. Set the blending mode for this layer to screen.

Et voilà, you’ve built an absolute map! This map will serve as a solid foundation for all kinds of image distortions:

  • By applying Photoshop-like distortion filters to this map, we are able to use these effects in CSS filters!
  • We can control the scaling of the x- and y-axis independently by altering the transparency of the blue or red gradient.
  • It is possible to “mask” parts of the map with a “neutral” color (rgb(127, 0 ,127) or #7F007F) to prevent the corresponding parts in the image from displacing.

The Problem With Jagged Edges

You may have noticed the pixelated edges that sometimes appear in the output image. Especially source material with high contrast, e.g. typography or vector artwork, is prone to this effect.

This is caused by several reasons:

  • The filter will take the source image as a bitmap:
    If there exist antialiased edges in the source, the filter will not “re-initialize” them after displacing the source. Any pixel will be transformed to its new location, that’s it.
  • Rounding errors:
    Maybe a pixel from 100,100 must be shifted to 83.276, 124.217. The filter must somehow map these coordinates to non-decimal pixel values.
  • Gaps after displacement:
    Maybe two neighboring pixels, say at coordinates x1:100, x2:101 are shifted to different locations, maybe x1:207.4, x2: 211.3. How will the filter fill the space in between? Hint: not at all. The spec clearly states:

“Sometimes filter primitives result in undefined pixels. For example, filter primitive feOffset can shift an image down and to the right, leaving undefined pixels at the top and left. In these cases, the undefined pixels are set to transparent black.”

— Filter Effects Module Level 1, W3C

My weapon of choice to fix this issue is to add a slight blur, then increase the contrast with a feConvolveMatrix. Not perfect, but good enough for most situations. Here’s a demo on CodePen:

  1. Insert a feImage primitive with a reference to the absolutemap;
  2. Create the “magnifying glass”, an SVG containing a circle filled with a radial gradient, starting at rgba(127, 0, 127, 0) and ending at rgba(127, 0, 127, 1);
  3. Insert a second feImage with a reference to the “magnifying glass”;
  4. Merge both images into an feMerge primitive and make the result the feDisplacementMap’s in2. As you may have noticed we’re using a negative scale factor here to make sure the image will be scaled down outside and is displayed at its normal size inside the “magnifying glass”;
  5. Add some JavaScript so that the x and y attributes of the feImage referencing the “magnifying glass” match the mouse position.

Generating Arbitrary Maps With Blurred Paths

A totally different way to build an SVG displacement map is by making use of extremely thick blurred bezier paths instead of gradients. Here’s a little app that lets you change the bezier anchor points in a map created this way.

It’s possible to create some pretty rad maps this way, but you should keep in mind that blurring has an impact on rendering performance. Firefox even has a threshold of 100px on how much blurring is allowed.

Animation

By now we learned everything about the main principles behind displacement filtering and how to create displacement maps in SVG. We are ready for the fun part: how to set everything into motion.

SVG filters can be animated and transitioned. A big problem is the fact that filter values referencing a URL will not be interpolated, but swapped out immediately without any transition in-between, a behavior that is in line with the spec. Can be ok in some situations, but boring most of the time. We want animated twirls, ripples, warps, and morphs!

When thinking of animated maps, the first thing that comes to mind is an animated gif or WebP. Well, animated images will work in every browser somehow. But performance varies greatly from quite bad to extremely bad. And then there are platform-related limitations: e. g. Blink is not able to apply this animated displacement filter to elements that contain other animated elements. And we didn’t talk about file size yet. Instead we will focus on the two most reliable animation techniques IMHO: SMIL (yes, SMIL still is a thing these days) and JavaScript.

A filter will usually be constructed from a variety of different primitives and every attribute that was added to a node, like x, y, width, height or scale can be animated with SMIL.

A Simple Glitch Effect

Here’s a very simple example: making use of an animated feFlood primitive to create a basic glitch effect:

This effect can be leveraged even more by throwing masks, blurs, and some colors into the mix. Here’s a pimped-up version of the effect using the same techniques, but in a more advanced way.

You may have noticed that depending on your browser and CPU, the performance of these demos can vary drastically. It’s a disappointing fact that SVG Filters are still not optimized for performance. Your GPU will accelerate some simple primitives (e. g. color operations), but when you build a compound filter chaining and merging many primitives you will quickly find framerates dropping and fans going up — especially in WebKit and Firefox. Browser vendors have a lot of topics on their to-do lists and SVG Filter Effects don’t have the highest priority there, especially as they still are not found that often out in the wild.

This doesn’t mean that you can’t use animated SVG Filters now, but you should apply them in a responsible way: preferably limit the dimensions of the animated paint area to the smallest possible rectangle, limit the number of iterations to the minimum, be careful with blurs and blending operations and test test test on many browsers and devices.

A good use case for animated filter effects are small, locally constrained animations applied to UI elements. Below is a demonstration of how the animated feImage effect from above can be used to spice up a rather boring progress bar:

A Glitch Transition Between Elements

  • Create 2 different SVGs for each channel in our map. For each color create a grid of rectangles with randomly varying color intensity.
  • Create 2 different feImage primitives. URL-encode each SVG, then put it into the href-attribute of each feImage.
  • Add SMIL animations for width, height, and y attributes.
  • Insert a feBlend and blend both feImages into a single output.
  • Add some colored feDropShadows for a cool split-color effect.
  • Blend everything, then feed it into a feDisplacementmap.
  • Animate the scale attribute with SMIL.
  • Feel free to experiment by changing forms (e. g. use circles instead of rects), applying different timings, adding blur effects, and more.

Animating The Map Itself

So far we have learned that animating filter attributes with SMIL can help us to achieve really cool visual effects. On the other hand, we already saw how SVG fragments can be used as a displacement map. As SVGs are animatable with JavaScript, SMIL and CSS, it would seem obvious that we can apply animations directly to an SVG map right?

Unfortunately, SMIL and CSS animations in SVG images used as input for feImage will not run when the SVG or fragment is URL encoded. We will need to write some JavaScript for a reliable solution and take into account that two different approaches for Webkit and Blink/Quantum browsers are necessary. In a first step, let’s see how the “ideal” way of animating a map will look:

  • Create the SVG fragment containing your map;
  • Reference it from the feImage that controls your feDisplacementMap’s in2;
  • Feel free to animate everything in your fragment with JavaScript as you like. Roll your own script or use your favorite library.

“This sounds too easy. Where’s the catch?” Of course, you are right. The method described above is the ideal path, the way things should work but, here’s a strange matter of fact: It will not work anywhere but Webkit. In order for our animation to run in Blink and Firefox, we must implement a rather hacky solution and you won’t like it:

  • Create the SVG fragment containing your map.
  • In every frame of your animation, change all the values of every animated attribute.
  • In every frame of your animation create a new URL encoded string containing a “snapshot” of the fragment and write it into the feImages href attribute.

You’re probably thinking: “This is ugly! I don’t like it and you are a despicable person!”. I feel your pain. The front end is a hostile habitat and sometimes we must do abhorrent things to survive (fun fact: the “ugly” method performs better in Blink than the “pure” method in Webkit will).

Let’s Rock!

Let’s solve a real-world problem with this approach: here’s what happens to “The Rock” when we apply these two simple displacement maps:

2. Using Animejs’ Grid Animation

Animejs’ staggering and “grid” properties can help you create really cool typographic effects. This effect was created by animating a grid of circles:

3. A “Waving Flag” Menu

An unconventional way of swapping a second-level submenu. The fade-in effect is achieved by moving a striped map horizontally:

Please note that the demos shown above are highly experimental and mainly intended to demonstrate the concept of animated displacement maps. If you want to use any of these techniques in a live project, always take my earlier recommendations to heart. And forgive me for not going into detail on every example — it simply would exceed the scope of this article.

Articles on Smashing Magazine — For Web Designers And Developers

01 Sep

A Deep Dive Into The Wonderful World Of SVG Displacement Filtering

by TBSCategories: News

Even today, the magic, wicked realm of SVG Filter Effects is largely uncharted territory. The art of SVG filtering is still surrounded by an aura of alchemy: you have to bravely dive into a dark world of inconsistencies, your dedication will repeatedly be tested by buggy implementations and nerve-wracking side effects, and you must learn complicated incantations. But, once mastered, it gives you unprecedented power — a means to switch the total appearance of elements and websites by the snap of a finger.

In this article, we’ll be diving into one of the most spectacular filter effects: the SVG feDisplacementMap filter primitive. In order to make it all easier to digest, I’ve divided the article into three parts in which we’ll be exploring:

  1. how the feDisplacementMap works, i.e. how to apply it and how to control its output in a predictable manner;
  2. we’ll then explore methods to create fancy displacement maps in SVG (slightly more interesting as we will start playing with JavaScript);
  3. and finally, we’ll take a look at some of the methods to animate the filter and create dramatic visual effects.

As this will be a rather long read, the impatient ones may want to check out the demos we’re going to encounter before continuing. All the demos in this article have been optimized for the latest versions of the three major browser engines.

To get the most out of this article, you should already have a basic understanding of SVG filters. If you are a filter novice, you may want to take a short detour to Sara Soueidan’s introduction or head over on to my humble take on the subject first.

Be warned though: not applied properly, SVG Filters can hurt the performance of your site drastically. Always test extensively if you roll out one of the techniques described here.

A Short Primer On Displacement Filtering

So what’s a displacement filter? A displacement operation can visually distort any graphic it is applied to. You can create warp effects, twirls or ripples like you would do with a Photoshop distortion filter. Displacement filtering is an important tool in VFX, and most likely you already saw some displacement mapping operations on film and TV, created with a VFX tool like After Effects or GiantRed.

To achieve a distortion effect the filter needs two images as input:

  • The actual source graphic should be distorted (from now on just “source”);
  • The “displacement map” (from now on just “map”). This map contains information on how we want the source to be distorted.

Most of the time, a map will be some Bitmap image, but in the next part, I will demonstrate how to use SVG images or fragments as an input.

Let’s see what happens when we use an image of Barcelona’s famous La Sagrada Familia to “distort” the Mona Lisa:

  1. The first filter primitive is feImage which holds a reference to the map (there are other filter primitives that can be used as an input. You will find several fascinating demos out there where feTurbulence is used as displacement map, but in this article, we will mostly focus on feImage).
  2. This feImage is then fed into a feDisplacementMap primitive where the actual distortion happens:
    • A positive or negative scale attribute defines the strength of the distortion.
    • The purpose of xChannelSelector and yChannelSelector is to determine which of the input image’s four-color channels (red, green, blue, alpha) should be applied to which axis for distortion. Both attributes default to the map’s alpha channel (which means if you’re using a map without alpha channels and omit these attributes, you’ll see nothing more than a diagonal shift of the source).

We then apply the filter with CSS:

.filtered {   filter: url(#displacement-filter); }

It may be fun to play around distorting images this way but it is unpredictable how the result will look and most of the time it’s not aesthetically pleasing at all. Is there a way to get pixel-perfect control over the output? Here’s what the spec says:

This filter primitive uses the pixels values from the image from in2 to spatially displace the image from in. This is the transformation to be performed:

P'(x,y) ← P( x + scale (XC(x,y) – .5), y + scale (YC(x,y) – .5))

The displacement map, in2, defines the inverse of the mapping performed.

OK, looks complicated at a first glance, but it is actually pretty easy to understand when broken down:

  • P'(x,y) stands for the coordinates of a pixel in the result;
  • X and Y are the coordinates of this pixel in the unfiltered source;
  • XC and YC are the normalized (1/255) RGB color values of the given pixel in the map;
  • Finally, the result of the operation must be inverted (which basically means every + in the formula must be replaced by a -).

We will run some simple experiments to verify our formula by feeding primitive bitmaps into a filter, consisting of only one single color. Let’s say the map is filled with rgb(51, 51, 51), how would we expect the coordinates of a source pixel at x=100 / y=100 to be transformed when fed into a displacement primitive with a scale value of 100?

X: 100 – 100 (51/255 – .5) = 130

Y: 100 – 100 (51/255 – .5) = 130

To scale an image equally in all directions, the color values must gradually decline from a maximum at one edge to a minimum at the opposite edge. We will use red for X and blue for Y from now on, but in the end, it doesn’t matter which color you chose for x- and yChannelSelector.

  1. In your favorite Image editor, open a new document;
  2. Set the background color of the document to black;
  3. Create a new layer and fill it with a left to right gradient from rgb(255, 0, 0) to rgba(255, 0, 0, 0);
  4. Add a second layer and add a top to bottom gradient from rgb (0, 0, 255) to rgba(0, 0, 255, 0);
  5. Set the blending mode for this layer to screen.

Et voilà, you’ve built an absolute map! This map will serve as a solid foundation for all kinds of image distortions:

  • By applying Photoshop-like distortion filters to this map, we are able to use these effects in CSS filters!
  • We can control the scaling of the x- and y-axis independently by altering the transparency of the blue or red gradient.
  • It is possible to “mask” parts of the map with a “neutral” color (rgb(127, 0 ,127) or #7F007F) to prevent the corresponding parts in the image from displacing.

The Problem With Jagged Edges

You may have noticed the pixelated edges that sometimes appear in the output image. Especially source material with high contrast, e.g. typography or vector artwork, is prone to this effect.

This is caused by several reasons:

  • The filter will take the source image as a bitmap:
    If there exist antialiased edges in the source, the filter will not “re-initialize” them after displacing the source. Any pixel will be transformed to its new location, that’s it.
  • Rounding errors:
    Maybe a pixel from 100,100 must be shifted to 83.276, 124.217. The filter must somehow map these coordinates to non-decimal pixel values.
  • Gaps after displacement:
    Maybe two neighboring pixels, say at coordinates x1:100, x2:101 are shifted to different locations, maybe x1:207.4, x2: 211.3. How will the filter fill the space in between? Hint: not at all. The spec clearly states:

“Sometimes filter primitives result in undefined pixels. For example, filter primitive feOffset can shift an image down and to the right, leaving undefined pixels at the top and left. In these cases, the undefined pixels are set to transparent black.”

— Filter Effects Module Level 1, W3C

My weapon of choice to fix this issue is to add a slight blur, then increase the contrast with a feConvolveMatrix. Not perfect, but good enough for most situations. Here’s a demo on CodePen:

  1. Insert a feImage primitive with a reference to the absolutemap;
  2. Create the “magnifying glass”, an SVG containing a circle filled with a radial gradient, starting at rgba(127, 0, 127, 0) and ending at rgba(127, 0, 127, 1);
  3. Insert a second feImage with a reference to the “magnifying glass”;
  4. Merge both images into an feMerge primitive and make the result the feDisplacementMap’s in2. As you may have noticed we’re using a negative scale factor here to make sure the image will be scaled down outside and is displayed at its normal size inside the “magnifying glass”;
  5. Add some JavaScript so that the x and y attributes of the feImage referencing the “magnifying glass” match the mouse position.

Generating Arbitrary Maps With Blurred Paths

A totally different way to build an SVG displacement map is by making use of extremely thick blurred bezier paths instead of gradients. Here’s a little app that lets you change the bezier anchor points in a map created this way.

It’s possible to create some pretty rad maps this way, but you should keep in mind that blurring has an impact on rendering performance. Firefox even has a threshold of 100px on how much blurring is allowed.

Animation

By now we learned everything about the main principles behind displacement filtering and how to create displacement maps in SVG. We are ready for the fun part: how to set everything into motion.

SVG filters can be animated and transitioned. A big problem is the fact that filter values referencing a URL will not be interpolated, but swapped out immediately without any transition in-between, a behavior that is in line with the spec. Can be ok in some situations, but boring most of the time. We want animated twirls, ripples, warps, and morphs!

When thinking of animated maps, the first thing that comes to mind is an animated gif or WebP. Well, animated images will work in every browser somehow. But performance varies greatly from quite bad to extremely bad. And then there are platform-related limitations: e. g. Blink is not able to apply this animated displacement filter to elements that contain other animated elements. And we didn’t talk about file size yet. Instead we will focus on the two most reliable animation techniques IMHO: SMIL (yes, SMIL still is a thing these days) and JavaScript.

A filter will usually be constructed from a variety of different primitives and every attribute that was added to a node, like x, y, width, height or scale can be animated with SMIL.

A Simple Glitch Effect

Here’s a very simple example: making use of an animated feFlood primitive to create a basic glitch effect:

This effect can be leveraged even more by throwing masks, blurs, and some colors into the mix. Here’s a pimped-up version of the effect using the same techniques, but in a more advanced way.

You may have noticed that depending on your browser and CPU, the performance of these demos can vary drastically. It’s a disappointing fact that SVG Filters are still not optimized for performance. Your GPU will accelerate some simple primitives (e. g. color operations), but when you build a compound filter chaining and merging many primitives you will quickly find framerates dropping and fans going up — especially in WebKit and Firefox. Browser vendors have a lot of topics on their to-do lists and SVG Filter Effects don’t have the highest priority there, especially as they still are not found that often out in the wild.

This doesn’t mean that you can’t use animated SVG Filters now, but you should apply them in a responsible way: preferably limit the dimensions of the animated paint area to the smallest possible rectangle, limit the number of iterations to the minimum, be careful with blurs and blending operations and test test test on many browsers and devices.

A good use case for animated filter effects are small, locally constrained animations applied to UI elements. Below is a demonstration of how the animated feImage effect from above can be used to spice up a rather boring progress bar:

A Glitch Transition Between Elements

  • Create 2 different SVGs for each channel in our map. For each color create a grid of rectangles with randomly varying color intensity.
  • Create 2 different feImage primitives. URL-encode each SVG, then put it into the href-attribute of each feImage.
  • Add SMIL animations for width, height, and y attributes.
  • Insert a feBlend and blend both feImages into a single output.
  • Add some colored feDropShadows for a cool split-color effect.
  • Blend everything, then feed it into a feDisplacementmap.
  • Animate the scale attribute with SMIL.
  • Feel free to experiment by changing forms (e. g. use circles instead of rects), applying different timings, adding blur effects, and more.

Animating The Map Itself

So far we have learned that animating filter attributes with SMIL can help us to achieve really cool visual effects. On the other hand, we already saw how SVG fragments can be used as a displacement map. As SVGs are animatable with JavaScript, SMIL and CSS, it would seem obvious that we can apply animations directly to an SVG map right?

Unfortunately, SMIL and CSS animations in SVG images used as input for feImage will not run when the SVG or fragment is URL encoded. We will need to write some JavaScript for a reliable solution and take into account that two different approaches for Webkit and Blink/Quantum browsers are necessary. In a first step, let’s see how the “ideal” way of animating a map will look:

  • Create the SVG fragment containing your map;
  • Reference it from the feImage that controls your feDisplacementMap’s in2;
  • Feel free to animate everything in your fragment with JavaScript as you like. Roll your own script or use your favorite library.

“This sounds too easy. Where’s the catch?” Of course, you are right. The method described above is the ideal path, the way things should work but, here’s a strange matter of fact: It will not work anywhere but Webkit. In order for our animation to run in Blink and Firefox, we must implement a rather hacky solution and you won’t like it:

  • Create the SVG fragment containing your map.
  • In every frame of your animation, change all the values of every animated attribute.
  • In every frame of your animation create a new URL encoded string containing a “snapshot” of the fragment and write it into the feImages href attribute.

You’re probably thinking: “This is ugly! I don’t like it and you are a despicable person!”. I feel your pain. The front end is a hostile habitat and sometimes we must do abhorrent things to survive (fun fact: the “ugly” method performs better in Blink than the “pure” method in Webkit will).

Let’s Rock!

Let’s solve a real-world problem with this approach: here’s what happens to “The Rock” when we apply these two simple displacement maps:

2. Using Animejs’ Grid Animation

Animejs’ staggering and “grid” properties can help you create really cool typographic effects. This effect was created by animating a grid of circles:

3. A “Waving Flag” Menu

An unconventional way of swapping a second-level submenu. The fade-in effect is achieved by moving a striped map horizontally:

Please note that the demos shown above are highly experimental and mainly intended to demonstrate the concept of animated displacement maps. If you want to use any of these techniques in a live project, always take my earlier recommendations to heart. And forgive me for not going into detail on every example — it simply would exceed the scope of this article.

Articles on Smashing Magazine — For Web Designers And Developers

01 Sep

A Deep Dive Into The Wonderful World Of SVG Displacement Filtering

by TBSCategories: News

Even today, the magic, wicked realm of SVG Filter Effects is largely uncharted territory. The art of SVG filtering is still surrounded by an aura of alchemy: you have to bravely dive into a dark world of inconsistencies, your dedication will repeatedly be tested by buggy implementations and nerve-wracking side effects, and you must learn complicated incantations. But, once mastered, it gives you unprecedented power — a means to switch the total appearance of elements and websites by the snap of a finger.

In this article, we’ll be diving into one of the most spectacular filter effects: the SVG feDisplacementMap filter primitive. In order to make it all easier to digest, I’ve divided the article into three parts in which we’ll be exploring:

  1. how the feDisplacementMap works, i.e. how to apply it and how to control its output in a predictable manner;
  2. we’ll then explore methods to create fancy displacement maps in SVG (slightly more interesting as we will start playing with JavaScript);
  3. and finally, we’ll take a look at some of the methods to animate the filter and create dramatic visual effects.

As this will be a rather long read, the impatient ones may want to check out the demos we’re going to encounter before continuing. All the demos in this article have been optimized for the latest versions of the three major browser engines.

To get the most out of this article, you should already have a basic understanding of SVG filters. If you are a filter novice, you may want to take a short detour to Sara Soueidan’s introduction or head over on to my humble take on the subject first.

Be warned though: not applied properly, SVG Filters can hurt the performance of your site drastically. Always test extensively if you roll out one of the techniques described here.

A Short Primer On Displacement Filtering

So what’s a displacement filter? A displacement operation can visually distort any graphic it is applied to. You can create warp effects, twirls or ripples like you would do with a Photoshop distortion filter. Displacement filtering is an important tool in VFX, and most likely you already saw some displacement mapping operations on film and TV, created with a VFX tool like After Effects or GiantRed.

To achieve a distortion effect the filter needs two images as input:

  • The actual source graphic should be distorted (from now on just “source”);
  • The “displacement map” (from now on just “map”). This map contains information on how we want the source to be distorted.

Most of the time, a map will be some Bitmap image, but in the next part, I will demonstrate how to use SVG images or fragments as an input.

Let’s see what happens when we use an image of Barcelona’s famous La Sagrada Familia to “distort” the Mona Lisa:

  1. The first filter primitive is feImage which holds a reference to the map (there are other filter primitives that can be used as an input. You will find several fascinating demos out there where feTurbulence is used as displacement map, but in this article, we will mostly focus on feImage).
  2. This feImage is then fed into a feDisplacementMap primitive where the actual distortion happens:
    • A positive or negative scale attribute defines the strength of the distortion.
    • The purpose of xChannelSelector and yChannelSelector is to determine which of the input image’s four-color channels (red, green, blue, alpha) should be applied to which axis for distortion. Both attributes default to the map’s alpha channel (which means if you’re using a map without alpha channels and omit these attributes, you’ll see nothing more than a diagonal shift of the source).

We then apply the filter with CSS:

.filtered {   filter: url(#displacement-filter); }

It may be fun to play around distorting images this way but it is unpredictable how the result will look and most of the time it’s not aesthetically pleasing at all. Is there a way to get pixel-perfect control over the output? Here’s what the spec says:

This filter primitive uses the pixels values from the image from in2 to spatially displace the image from in. This is the transformation to be performed:

P'(x,y) ← P( x + scale (XC(x,y) – .5), y + scale (YC(x,y) – .5))

The displacement map, in2, defines the inverse of the mapping performed.

OK, looks complicated at a first glance, but it is actually pretty easy to understand when broken down:

  • P'(x,y) stands for the coordinates of a pixel in the result;
  • X and Y are the coordinates of this pixel in the unfiltered source;
  • XC and YC are the normalized (1/255) RGB color values of the given pixel in the map;
  • Finally, the result of the operation must be inverted (which basically means every + in the formula must be replaced by a -).

We will run some simple experiments to verify our formula by feeding primitive bitmaps into a filter, consisting of only one single color. Let’s say the map is filled with rgb(51, 51, 51), how would we expect the coordinates of a source pixel at x=100 / y=100 to be transformed when fed into a displacement primitive with a scale value of 100?

X: 100 – 100 (51/255 – .5) = 130

Y: 100 – 100 (51/255 – .5) = 130

To scale an image equally in all directions, the color values must gradually decline from a maximum at one edge to a minimum at the opposite edge. We will use red for X and blue for Y from now on, but in the end, it doesn’t matter which color you chose for x- and yChannelSelector.

  1. In your favorite Image editor, open a new document;
  2. Set the background color of the document to black;
  3. Create a new layer and fill it with a left to right gradient from rgb(255, 0, 0) to rgba(255, 0, 0, 0);
  4. Add a second layer and add a top to bottom gradient from rgb (0, 0, 255) to rgba(0, 0, 255, 0);
  5. Set the blending mode for this layer to screen.

Et voilà, you’ve built an absolute map! This map will serve as a solid foundation for all kinds of image distortions:

  • By applying Photoshop-like distortion filters to this map, we are able to use these effects in CSS filters!
  • We can control the scaling of the x- and y-axis independently by altering the transparency of the blue or red gradient.
  • It is possible to “mask” parts of the map with a “neutral” color (rgb(127, 0 ,127) or #7F007F) to prevent the corresponding parts in the image from displacing.

The Problem With Jagged Edges

You may have noticed the pixelated edges that sometimes appear in the output image. Especially source material with high contrast, e.g. typography or vector artwork, is prone to this effect.

This is caused by several reasons:

  • The filter will take the source image as a bitmap:
    If there exist antialiased edges in the source, the filter will not “re-initialize” them after displacing the source. Any pixel will be transformed to its new location, that’s it.
  • Rounding errors:
    Maybe a pixel from 100,100 must be shifted to 83.276, 124.217. The filter must somehow map these coordinates to non-decimal pixel values.
  • Gaps after displacement:
    Maybe two neighboring pixels, say at coordinates x1:100, x2:101 are shifted to different locations, maybe x1:207.4, x2: 211.3. How will the filter fill the space in between? Hint: not at all. The spec clearly states:

“Sometimes filter primitives result in undefined pixels. For example, filter primitive feOffset can shift an image down and to the right, leaving undefined pixels at the top and left. In these cases, the undefined pixels are set to transparent black.”

— Filter Effects Module Level 1, W3C

My weapon of choice to fix this issue is to add a slight blur, then increase the contrast with a feConvolveMatrix. Not perfect, but good enough for most situations. Here’s a demo on CodePen:

  1. Insert a feImage primitive with a reference to the absolutemap;
  2. Create the “magnifying glass”, an SVG containing a circle filled with a radial gradient, starting at rgba(127, 0, 127, 0) and ending at rgba(127, 0, 127, 1);
  3. Insert a second feImage with a reference to the “magnifying glass”;
  4. Merge both images into an feMerge primitive and make the result the feDisplacementMap’s in2. As you may have noticed we’re using a negative scale factor here to make sure the image will be scaled down outside and is displayed at its normal size inside the “magnifying glass”;
  5. Add some JavaScript so that the x and y attributes of the feImage referencing the “magnifying glass” match the mouse position.

Generating Arbitrary Maps With Blurred Paths

A totally different way to build an SVG displacement map is by making use of extremely thick blurred bezier paths instead of gradients. Here’s a little app that lets you change the bezier anchor points in a map created this way.

It’s possible to create some pretty rad maps this way, but you should keep in mind that blurring has an impact on rendering performance. Firefox even has a threshold of 100px on how much blurring is allowed.

Animation

By now we learned everything about the main principles behind displacement filtering and how to create displacement maps in SVG. We are ready for the fun part: how to set everything into motion.

SVG filters can be animated and transitioned. A big problem is the fact that filter values referencing a URL will not be interpolated, but swapped out immediately without any transition in-between, a behavior that is in line with the spec. Can be ok in some situations, but boring most of the time. We want animated twirls, ripples, warps, and morphs!

When thinking of animated maps, the first thing that comes to mind is an animated gif or WebP. Well, animated images will work in every browser somehow. But performance varies greatly from quite bad to extremely bad. And then there are platform-related limitations: e. g. Blink is not able to apply this animated displacement filter to elements that contain other animated elements. And we didn’t talk about file size yet. Instead we will focus on the two most reliable animation techniques IMHO: SMIL (yes, SMIL still is a thing these days) and JavaScript.

A filter will usually be constructed from a variety of different primitives and every attribute that was added to a node, like x, y, width, height or scale can be animated with SMIL.

A Simple Glitch Effect

Here’s a very simple example: making use of an animated feFlood primitive to create a basic glitch effect:

This effect can be leveraged even more by throwing masks, blurs, and some colors into the mix. Here’s a pimped-up version of the effect using the same techniques, but in a more advanced way.

You may have noticed that depending on your browser and CPU, the performance of these demos can vary drastically. It’s a disappointing fact that SVG Filters are still not optimized for performance. Your GPU will accelerate some simple primitives (e. g. color operations), but when you build a compound filter chaining and merging many primitives you will quickly find framerates dropping and fans going up — especially in WebKit and Firefox. Browser vendors have a lot of topics on their to-do lists and SVG Filter Effects don’t have the highest priority there, especially as they still are not found that often out in the wild.

This doesn’t mean that you can’t use animated SVG Filters now, but you should apply them in a responsible way: preferably limit the dimensions of the animated paint area to the smallest possible rectangle, limit the number of iterations to the minimum, be careful with blurs and blending operations and test test test on many browsers and devices.

A good use case for animated filter effects are small, locally constrained animations applied to UI elements. Below is a demonstration of how the animated feImage effect from above can be used to spice up a rather boring progress bar:

A Glitch Transition Between Elements

  • Create 2 different SVGs for each channel in our map. For each color create a grid of rectangles with randomly varying color intensity.
  • Create 2 different feImage primitives. URL-encode each SVG, then put it into the href-attribute of each feImage.
  • Add SMIL animations for width, height, and y attributes.
  • Insert a feBlend and blend both feImages into a single output.
  • Add some colored feDropShadows for a cool split-color effect.
  • Blend everything, then feed it into a feDisplacementmap.
  • Animate the scale attribute with SMIL.
  • Feel free to experiment by changing forms (e. g. use circles instead of rects), applying different timings, adding blur effects, and more.

Animating The Map Itself

So far we have learned that animating filter attributes with SMIL can help us to achieve really cool visual effects. On the other hand, we already saw how SVG fragments can be used as a displacement map. As SVGs are animatable with JavaScript, SMIL and CSS, it would seem obvious that we can apply animations directly to an SVG map right?

Unfortunately, SMIL and CSS animations in SVG images used as input for feImage will not run when the SVG or fragment is URL encoded. We will need to write some JavaScript for a reliable solution and take into account that two different approaches for Webkit and Blink/Quantum browsers are necessary. In a first step, let’s see how the “ideal” way of animating a map will look:

  • Create the SVG fragment containing your map;
  • Reference it from the feImage that controls your feDisplacementMap’s in2;
  • Feel free to animate everything in your fragment with JavaScript as you like. Roll your own script or use your favorite library.

“This sounds too easy. Where’s the catch?” Of course, you are right. The method described above is the ideal path, the way things should work but, here’s a strange matter of fact: It will not work anywhere but Webkit. In order for our animation to run in Blink and Firefox, we must implement a rather hacky solution and you won’t like it:

  • Create the SVG fragment containing your map.
  • In every frame of your animation, change all the values of every animated attribute.
  • In every frame of your animation create a new URL encoded string containing a “snapshot” of the fragment and write it into the feImages href attribute.

You’re probably thinking: “This is ugly! I don’t like it and you are a despicable person!”. I feel your pain. The front end is a hostile habitat and sometimes we must do abhorrent things to survive (fun fact: the “ugly” method performs better in Blink than the “pure” method in Webkit will).

Let’s Rock!

Let’s solve a real-world problem with this approach: here’s what happens to “The Rock” when we apply these two simple displacement maps:

2. Using Animejs’ Grid Animation

Animejs’ staggering and “grid” properties can help you create really cool typographic effects. This effect was created by animating a grid of circles:

3. A “Waving Flag” Menu

An unconventional way of swapping a second-level submenu. The fade-in effect is achieved by moving a striped map horizontally:

Please note that the demos shown above are highly experimental and mainly intended to demonstrate the concept of animated displacement maps. If you want to use any of these techniques in a live project, always take my earlier recommendations to heart. And forgive me for not going into detail on every example — it simply would exceed the scope of this article.

Articles on Smashing Magazine — For Web Designers And Developers

27 Apr

How To Bake Layers Of Accessibility Testing Into Your Process

by TBSCategories: News

When building websites or apps, accessibility testing is critical to ensure that what you build will work for all your users. This includes users with disabilities and also people with temporary and situational limitations (like that coworker who broke their arm skiing or the customer who is outdoors on their phone with glare on the screen).

We’re going to share how to “layer” accessibility testing by using a variety of tools and approaches at different stages in the digital product lifecycle to catch accessibility issues early — when it’s easier and cheaper to fix them. Taking a layered approach to testing your site for accessibility also improves the usability of your site — which in turn increases your customer base and reduces customer service inquiries. It can both make and save you money.

We’ll use a layered cake analogy to talk about the different layers of accessibility testing and when to use them. Food analogies have become quite popular in the accessibility world!

This approach has worked well for both of us. Mike is a seasoned accessibility advocate and senior strategist at a government technology firm (CivicActions), and Kate is the Head of Services at an accessibility testing platform (Fable).

While Mike looks at accessibility testing from a more technical angle early in the development phase and scanning for compliance on live sites, Kate focuses on the user experience. Both of us realized that combining many types of accessibility testing throughout the product development life cycle is a powerful way to improve overall product accessibility. In this article, we’ll share some of the things we’ve learned.

Most organizations approach accessibility in three main ways:

  1. Running tools to check your code and/or user interface.
    This is often referred to as “automated testing” because you use software to automatically test many accessibility issues at once.
  2. Using your computer in a way that is different than you normally do.
    For example, by not using a mouse, zooming your browser to 200%), or switching to Windows high contrast mode.
  3. Using assistive technology and users with disabilities to check for usability issues.
    This is often referred to as “manual testing” because it requires a person to evaluate accessibility issues.

Far too many organizations rely exclusively on a single accessibility solution to validate their site. No one tool or process can give an organization the confidence that they are actually meeting the needs of the greatest possible number of people.

How To Secure Buy-In For Accessibility

In many organizations, in order to do accessibility testing, you’ll need executives to prioritize and support the work. Here are tips on how to make that happen if you don’t already have buy-in for accessibility:

  • Check if there is a legal requirement for your organization to be accessible.
    “Accessibility Act” and “Disability Act” are search terms that should pull up relevant laws in most countries. Sharing the legal risk can be the right incentive for some organizations.
  • Find out what your competitors are doing.
    Check for an accessibility statement on their websites. Most organizations are keen to stay ahead of the competition and knowing that others are prioritizing accessibility could do the trick.
  • Connect with customer service to find out if there are accessibility complaints.
    If possible, reach out to customers directly to hear about their experiences and share those stories with company leaders. Hearing about dissatisfied customers can be a huge motivator. If you can get permission from the customers, record a demo of them facing challenges with your products. A video like that can be very compelling.
  • Explain the financial costs and rewards.
    Many companies think they can’t afford to do accessibility, but it’s much more affordable when it’s integrated into the day-to-day work and not an afterthought. There’s also the potential revenue from people with disabilities — globally they represent more than 3 trillion dollars in disposable income.

  • Find the right champion.
    Chances are there’s already someone at the highest levels of the organization who cares about people and doing the right thing. This may be a Diversity and Inclusion lead, someone fighting for environmental sustainability, or other issues. Perhaps it’s someone with a disabled friend or family member. Making them aware of accessibility may be all that’s needed to add a new focus to their efforts.

Gathering Your Ingredients

Accessibility should be baked into your process as early as possible. One place to start is with the procurement process. You can incorporate accessibility as part of the review process for any technology systems you are buying or building. DisabilityIN has some excellent resources on accessible IT procurement.

Looking for vendor accessibility statements or VPATs for products can help, but so can doing a quick review with some of the tools mentioned in the recipe below. Not all software is created equally, so you want to be sure you’re working with vendors who are actively contributing to tools and processes that help you prioritize accessibility from the start.

Another way to bake in accessibility early, if you’re creating or updating a design system, is to choose a component library that has been built with accessibility in mind. Look for libraries with a clear accessibility statement and an open issue queue that allows you to review problems.

Examples:

  • The Angular Components team has built accessibility into the Material UI library. For example, the radio button component uses a radio group with an aria-label. Each radio button reads as checked or not checked to a screen reader user, the buttons can be selected using the arrow keys like standard HTML radio buttons, and the focused state is clearly visible.
  • Reakit for React describes an accessibility warning feature on their accessibility page that will tell developers when an aria-label is needed.
  • The Lion accessible web components library uses an a11y label to tag accessibility issues in GitHub so you can see what’s being improved and open your own issue if needed.

Another way to embed accessibility into your process is to update one of the personas your team uses to include disabilities. Many people have more than one disability, so creating at least one persona with several disabilities will ensure you keep that audience top-of-mind in all your early design work.

To flesh out that persona, talk to people with real disabilities — including temporary and situational limitations — to help you understand how they use technology, sites, and apps in the real world. One in five people have a permanent disability, but 100% of the population will be faced with vision, hearing, motion, or cognitive disabilities at some point in their lives. Our personas can reflect:

  • people with allergies, insomnia, or broken bones;
  • people using outdated technology or using their computers outside; or even
  • people who change their technology use according to their location (for example, disabling images when they need to save internet bandwidth).

Little changes like these can have a big impact on how your team thinks. One way to pitch this change to leadership and teams is to talk about how it will make your personas more reflective of your actual users — which is the whole point of personas. They must be realistic.

One of the most impactful ways to involve people with disabilities is to have them help co-design services and products. Australia has a free training toolkit on how to do co-design with people with disabilities. There’s also a great case study on how one company ran co-design sessions with people with learning disabilities on behalf of the UK government.

Legacy IT

Whether we like it or not, most of the decisions about organizational IT were made months (if not years) ago. Even when you are in the heat of a procurement process, accessibility is typically just one of many considerations. This is to be expected — even in organizations that are passionate about accessibility.

With legacy technology, the first step is simply to raise awareness with the vendor or team about the importance of accessibility. If you can detail accessibility issues that you want to be fixed using automated tools, it can help adjust how a vendor ranks their issue queue. There isn’t always a community portal to post concerns like this, but there might be a community on Twitter or Reddit where you could bring issues to light.

Additionally, there might be a customizable theme that could be adjusted to address some of the concerns. Some solutions may offer an Application Programming Interface (API) that would allow a developer to build an accessible user interface around it.

If a vendor has competitors, it can be useful to highlight the accessibility features that are included in that product. It can be beneficial to remind vendors that you do have options.

If legacy IT is an internally built product, a good way to quickly evaluate it is using the keyboard only. If you can’t use the product with a keyboard (for example, there’s no visible focus or the UI is only mouse clickable), it’s likely going to be a lot of effort to improve the accessibility of the product.

Consider offering alternative ways to access the service (e.g. phone support, in-person service, or email) so that people who can’t access the product digitally because of accessibility barriers can still get what they need.

Think about the organizational roadmap and when it might be feasible to upgrade or retire the product and weigh the cost and effort of accessibility against that. If you have other, newer products that aren’t accessible, it might be more productive to focus your efforts on those products if a legacy tool is nearing the end of life.

The Recipe

Here is an example of a comprehensive accessibility testing approach, with five layers for a really delicious accessibility testing cake. Figure out what your budget is going to be and then price out all the various testing approaches. Some are free, others will cost money. In the next section, we provide advice on where to start if all these layers of testing won’t fit in your budget.

  1. Research User Needs
    Ensure the questionnaire that you use to screen potential research participants asks about assistive technology use. This will make it easy to integrate people with disabilities into your existing research process at no extra cost. If you don’t have luck finding participants this way, try reaching out to disability organizations.

    You can also modify your existing user personas to include users with disabilities. You can borrow aspects of user profiles from Gov.UK if you need to do this quickly and cheaply. If you have the budget for it, add people with disabilities into prototype and design reviews. This may be easiest to do if you engage a vendor that offers this type of service, hence the need for a budget. Alternatively, you can pay participants directly.

  2. Refine Your Process
    Encourage developers, designers, and content authors to include accessibility checks as part of their process. Here are ways to do that using free automated testing tools:
    • Download free browser extensions/plug-ins to do page specific testing for design reviews (WAVE or Accessibility Insights)
    • If you use continuous integration testing as part of the build pipeline for developers, make sure you are evaluating accessibility (there are free open-source tools for this like Axe Core and Pa11y)
    • Give content authors tools in the WYSIWYG interface to identify barriers that they have added (HTML Code Sniffer)
    • Ensure you are crawling your site regularly to catch accessibility issues. If possible, run crawlers in both staging and production environments (Purple Hats is a free open source option)

  3. Manual QA
    You don’t have to add extra people to do QA, just integrate it into your existing process. If you only do one thing, then stop using the mouse during your regular QA. You’ll catch accessibility bugs along with other functional bugs. If you want to do more, test with screen readers, and magnifiers too.

    Here are various ways you can do manual accessibility QA without purchasing any tools:

    • Can you access your site without your mouse? Use simple keyboard-only manual testing to evaluate new components and content.
    • Browse your site with magnification set to 200% or greater using the built-in magnification tools in your browser (Ctrl + +).
    • Flip your browser or OS to dark mode and see if your site works well for people with light sensitivity.
    • Perform sprint-level testing with developers and designers using assistive technology (VoiceOver, Microsoft Narrator, and NVDA are free options).

  4. User Testing
    In large corporate environments with a dedicated budget for accessibility, you can pay assistive technology users to test functionality on your staging environment before launch.

    Nothing gives you greater certainty that your product will work for people with disabilities than validating with users. Not even a perfect WCAG compliance score can give you that assurance the way a real person using the product can.

    People with disabilities are often asked to do work for free, which is problematic as many with disabilities are already at an economic disadvantage. If you’re working on a personal project and there’s no budget, look at your network and see if there are people who would be interested in helping in exchange for an equivalent favor.

  5. Specialist Review
    If your organization has an accessibility team, have them do User Acceptance Testing pre-release. This is where you can get detailed feedback on WCAG compliance that you may have missed in earlier steps.

    Think of it as a final check; your accessibility team isn’t doing all of the work on accessibility, everyone has a role to play. Accessibility teams are most effective when they set standards, provide training, give guidance and evaluate compliance. They support accessibility efforts but aren’t the only ones doing accessibility work. That way no one person or team becomes a bottleneck.

    If you don’t have a team, you can hire accessibility professionals to do the reviews prior to release.

Where To Start

Start where you are. The goal isn’t perfection, but ongoing improvement. Implementing all layers at once doesn’t have to be the goal. Rather, it’s about starting with one or two layers and then gradually adding more layers as your team gets better at accessibility testing. A small slice of cake is better than no cake.

Individuals

  • If you are new to accessibility, start by adding a free browser extension to find accessibility issues and start by learning how to fix the errors that are displayed. WebAIM’s WAVE Toolbar is great for this.
  • Start sharing accessibility information that you have found useful. This could be just on Twitter or Reddit, but you could also start a newsletter to help raise awareness.
  • Sign up for webinars or events focused on accessibility so that you can learn more.

Teams

  • A team with a strong user-centered design approach might want to start with layer one: interviewing people with disabilities as part of user research.
  • A team with a strong IT compliance process might invest in tighter integration of automated testing in their continuous integration process or a site-wide crawler first.
  • Find ways to incorporate accessibility earlier in the design/development process.

Organizations

  • Make sure you have meaningful accessibility statements which reflect your organization’s commitment to remove barriers to people with disabilities.
  • Build a champions network that allows a community of practice to grow and learn from each other.

Limitations Of Automated Tools

Every baker needs to have an arsenal of tools they can rely on. There are proprietary accessibility tools worth considering, but there are also excellent open-source tools including the ones we mentioned in the “recipe” above that are available for free.

In modern dynamic sites, it is important to use automated tools to catch accessibility errors early before they are published to the live site. It’s also important to crawl the site to see that all the pages still comply after they’ve been published and continuously updated.

The challenge is that designers and developers often assume that if the tests don’t report any errors, a site is good. When you give people a test, people tend to write towards it. Unfortunately, many designers and developers stop when they eliminate the errors that they see with WAVE or Axe.

To be clear, it is a small fraction of teams that even do this, but if we want to make sites that are perceivable, operable, and understandable for more people using different types of technology, we have to do better.

Automated tools are great but limited. Even the best available automated tools only catch about 30 to 40% of WCAG compliance accessibility errors. An automated tool can tell you if an image is missing an alternative description, but what it can’t tell you is if the description is entirely inaccurate or used in the wrong context and therefore useless. That still requires a person to evaluate.

To get past these limits, it’s important to recognize that accessibility doesn’t automatically mean usability for people with disabilities. Think of accessibility as the lowest bar; it works with assistive technology, but to go beyond “it works” to “it’s enjoyable and easy to use” you’ll need to test with real users.

Many organizations already do usability testing, but most don’t include people with disabilities. If you’re having trouble recruiting more diverse participants, consider working with an organization that has a community of assistive technology users and a platform to make testing quick and easy.

Let’s Get Baking!

Use a layered accessibility testing approach when you are working to build an inclusive website. Don’t rely on just one type of testing to find barriers for people with disabilities.

  • Test your ideas with assistive technology users early in the process
  • Integrate regular automated code checks into the process of building the site
  • Do manual testing using assistive technology as part of QA
  • Test with people with disabilities prior to launch
  • Perform comprehensive accessibility reviews on staging

Remember the goal isn’t to score high in a testing tool, or even to meet a WCAG guideline, but rather to make your content more widely available, including to assistive technology users.

Ultimately, accessibility statements are the icing on the cake. Include an accessibility statement with contact information on your site to provide a feedback loop. Your users are the experts and everyone should be part of making a site better over time.

Articles on Smashing Magazine — For Web Designers And Developers

26 Apr

How To Bake Layers Of Accessibility Testing Into Your Process

by TBSCategories: News

When building websites or apps, accessibility testing is critical to ensure that what you build will work for all your users. This includes users with disabilities and also people with temporary and situational limitations (like that coworker who broke their arm skiing or the customer who is outdoors on their phone with glare on the screen).

We’re going to share how to “layer” accessibility testing by using a variety of tools and approaches at different stages in the digital product lifecycle to catch accessibility issues early — when it’s easier and cheaper to fix them. Taking a layered approach to testing your site for accessibility also improves the usability of your site — which in turn increases your customer base and reduces customer service inquiries. It can both make and save you money.

We’ll use a layered cake analogy to talk about the different layers of accessibility testing and when to use them. Food analogies have become quite popular in the accessibility world!

This approach has worked well for both of us. Mike is a seasoned accessibility advocate and senior strategist at a government technology firm (CivicActions), and Kate is the Head of Services at an accessibility testing platform (Fable).

While Mike looks at accessibility testing from a more technical angle early in the development phase and scanning for compliance on live sites, Kate focuses on the user experience. Both of us realized that combining many types of accessibility testing throughout the product development life cycle is a powerful way to improve overall product accessibility. In this article, we’ll share some of the things we’ve learned.

Most organizations approach accessibility in three main ways:

  1. Running tools to check your code and/or user interface.
    This is often referred to as “automated testing” because you use software to automatically test many accessibility issues at once.
  2. Using your computer in a way that is different than you normally do.
    For example, by not using a mouse, zooming your browser to 200%), or switching to Windows high contrast mode.
  3. Using assistive technology and users with disabilities to check for usability issues.
    This is often referred to as “manual testing” because it requires a person to evaluate accessibility issues.

Far too many organizations rely exclusively on a single accessibility solution to validate their site. No one tool or process can give an organization the confidence that they are actually meeting the needs of the greatest possible number of people.

How To Secure Buy-In For Accessibility

In many organizations, in order to do accessibility testing, you’ll need executives to prioritize and support the work. Here are tips on how to make that happen if you don’t already have buy-in for accessibility:

  • Check if there is a legal requirement for your organization to be accessible.
    “Accessibility Act” and “Disability Act” are search terms that should pull up relevant laws in most countries. Sharing the legal risk can be the right incentive for some organizations.
  • Find out what your competitors are doing.
    Check for an accessibility statement on their websites. Most organizations are keen to stay ahead of the competition and knowing that others are prioritizing accessibility could do the trick.
  • Connect with customer service to find out if there are accessibility complaints.
    If possible, reach out to customers directly to hear about their experiences and share those stories with company leaders. Hearing about dissatisfied customers can be a huge motivator. If you can get permission from the customers, record a demo of them facing challenges with your products. A video like that can be very compelling.
  • Explain the financial costs and rewards.
    Many companies think they can’t afford to do accessibility, but it’s much more affordable when it’s integrated into the day-to-day work and not an afterthought. There’s also the potential revenue from people with disabilities — globally they represent more than 3 trillion dollars in disposable income.

  • Find the right champion.
    Chances are there’s already someone at the highest levels of the organization who cares about people and doing the right thing. This may be a Diversity and Inclusion lead, someone fighting for environmental sustainability, or other issues. Perhaps it’s someone with a disabled friend or family member. Making them aware of accessibility may be all that’s needed to add a new focus to their efforts.

Gathering Your Ingredients

Accessibility should be baked into your process as early as possible. One place to start is with the procurement process. You can incorporate accessibility as part of the review process for any technology systems you are buying or building. DisabilityIN has some excellent resources on accessible IT procurement.

Looking for vendor accessibility statements or VPATs for products can help, but so can doing a quick review with some of the tools mentioned in the recipe below. Not all software is created equally, so you want to be sure you’re working with vendors who are actively contributing to tools and processes that help you prioritize accessibility from the start.

Another way to bake in accessibility early, if you’re creating or updating a design system, is to choose a component library that has been built with accessibility in mind. Look for libraries with a clear accessibility statement and an open issue queue that allows you to review problems.

Examples:

  • The Angular Components team has built accessibility into the Material UI library. For example, the radio button component uses a radio group with an aria-label. Each radio button reads as checked or not checked to a screen reader user, the buttons can be selected using the arrow keys like standard HTML radio buttons, and the focused state is clearly visible.
  • Reakit for React describes an accessibility warning feature on their accessibility page that will tell developers when an aria-label is needed.
  • The Lion accessible web components library uses an a11y label to tag accessibility issues in GitHub so you can see what’s being improved and open your own issue if needed.

Another way to embed accessibility into your process is to update one of the personas your team uses to include disabilities. Many people have more than one disability, so creating at least one persona with several disabilities will ensure you keep that audience top-of-mind in all your early design work.

To flesh out that persona, talk to people with real disabilities — including temporary and situational limitations — to help you understand how they use technology, sites, and apps in the real world. One in five people have a permanent disability, but 100% of the population will be faced with vision, hearing, motion, or cognitive disabilities at some point in their lives. Our personas can reflect:

  • people with allergies, insomnia, or broken bones;
  • people using outdated technology or using their computers outside; or even
  • people who change their technology use according to their location (for example, disabling images when they need to save internet bandwidth).

Little changes like these can have a big impact on how your team thinks. One way to pitch this change to leadership and teams is to talk about how it will make your personas more reflective of your actual users — which is the whole point of personas. They must be realistic.

One of the most impactful ways to involve people with disabilities is to have them help co-design services and products. Australia has a free training toolkit on how to do co-design with people with disabilities. There’s also a great case study on how one company ran co-design sessions with people with learning disabilities on behalf of the UK government.

Legacy IT

Whether we like it or not, most of the decisions about organizational IT were made months (if not years) ago. Even when you are in the heat of a procurement process, accessibility is typically just one of many considerations. This is to be expected — even in organizations that are passionate about accessibility.

With legacy technology, the first step is simply to raise awareness with the vendor or team about the importance of accessibility. If you can detail accessibility issues that you want to be fixed using automated tools, it can help adjust how a vendor ranks their issue queue. There isn’t always a community portal to post concerns like this, but there might be a community on Twitter or Reddit where you could bring issues to light.

Additionally, there might be a customizable theme that could be adjusted to address some of the concerns. Some solutions may offer an Application Programming Interface (API) that would allow a developer to build an accessible user interface around it.

If a vendor has competitors, it can be useful to highlight the accessibility features that are included in that product. It can be beneficial to remind vendors that you do have options.

If legacy IT is an internally built product, a good way to quickly evaluate it is using the keyboard only. If you can’t use the product with a keyboard (for example, there’s no visible focus or the UI is only mouse clickable), it’s likely going to be a lot of effort to improve the accessibility of the product.

Consider offering alternative ways to access the service (e.g. phone support, in-person service, or email) so that people who can’t access the product digitally because of accessibility barriers can still get what they need.

Think about the organizational roadmap and when it might be feasible to upgrade or retire the product and weigh the cost and effort of accessibility against that. If you have other, newer products that aren’t accessible, it might be more productive to focus your efforts on those products if a legacy tool is nearing the end of life.

The Recipe

Here is an example of a comprehensive accessibility testing approach, with five layers for a really delicious accessibility testing cake. Figure out what your budget is going to be and then price out all the various testing approaches. Some are free, others will cost money. In the next section, we provide advice on where to start if all these layers of testing won’t fit in your budget.

  1. Research User Needs
    Ensure the questionnaire that you use to screen potential research participants asks about assistive technology use. This will make it easy to integrate people with disabilities into your existing research process at no extra cost. If you don’t have luck finding participants this way, try reaching out to disability organizations.

    You can also modify your existing user personas to include users with disabilities. You can borrow aspects of user profiles from Gov.UK if you need to do this quickly and cheaply. If you have the budget for it, add people with disabilities into prototype and design reviews. This may be easiest to do if you engage a vendor that offers this type of service, hence the need for a budget. Alternatively, you can pay participants directly.

  2. Refine Your Process
    Encourage developers, designers, and content authors to include accessibility checks as part of their process. Here are ways to do that using free automated testing tools:
    • Download free browser extensions/plug-ins to do page specific testing for design reviews (WAVE or Accessibility Insights)
    • If you use continuous integration testing as part of the build pipeline for developers, make sure you are evaluating accessibility (there are free open-source tools for this like Axe Core and Pa11y)
    • Give content authors tools in the WYSIWYG interface to identify barriers that they have added (HTML Code Sniffer)
    • Ensure you are crawling your site regularly to catch accessibility issues. If possible, run crawlers in both staging and production environments (Purple Hats is a free open source option)

  3. Manual QA
    You don’t have to add extra people to do QA, just integrate it into your existing process. If you only do one thing, then stop using the mouse during your regular QA. You’ll catch accessibility bugs along with other functional bugs. If you want to do more, test with screen readers, and magnifiers too.

    Here are various ways you can do manual accessibility QA without purchasing any tools:

    • Can you access your site without your mouse? Use simple keyboard-only manual testing to evaluate new components and content.
    • Browse your site with magnification set to 200% or greater using the built-in magnification tools in your browser (Ctrl + +).
    • Flip your browser or OS to dark mode and see if your site works well for people with light sensitivity.
    • Perform sprint-level testing with developers and designers using assistive technology (VoiceOver, Microsoft Narrator, and NVDA are free options).

  4. User Testing
    In large corporate environments with a dedicated budget for accessibility, you can pay assistive technology users to test functionality on your staging environment before launch.

    Nothing gives you greater certainty that your product will work for people with disabilities than validating with users. Not even a perfect WCAG compliance score can give you that assurance the way a real person using the product can.

    People with disabilities are often asked to do work for free, which is problematic as many with disabilities are already at an economic disadvantage. If you’re working on a personal project and there’s no budget, look at your network and see if there are people who would be interested in helping in exchange for an equivalent favor.

  5. Specialist Review
    If your organization has an accessibility team, have them do User Acceptance Testing pre-release. This is where you can get detailed feedback on WCAG compliance that you may have missed in earlier steps.

    Think of it as a final check; your accessibility team isn’t doing all of the work on accessibility, everyone has a role to play. Accessibility teams are most effective when they set standards, provide training, give guidance and evaluate compliance. They support accessibility efforts but aren’t the only ones doing accessibility work. That way no one person or team becomes a bottleneck.

    If you don’t have a team, you can hire accessibility professionals to do the reviews prior to release.

Where To Start

Start where you are. The goal isn’t perfection, but ongoing improvement. Implementing all layers at once doesn’t have to be the goal. Rather, it’s about starting with one or two layers and then gradually adding more layers as your team gets better at accessibility testing. A small slice of cake is better than no cake.

Individuals

  • If you are new to accessibility, start by adding a free browser extension to find accessibility issues and start by learning how to fix the errors that are displayed. WebAIM’s WAVE Toolbar is great for this.
  • Start sharing accessibility information that you have found useful. This could be just on Twitter or Reddit, but you could also start a newsletter to help raise awareness.
  • Sign up for webinars or events focused on accessibility so that you can learn more.

Teams

  • A team with a strong user-centered design approach might want to start with layer one: interviewing people with disabilities as part of user research.
  • A team with a strong IT compliance process might invest in tighter integration of automated testing in their continuous integration process or a site-wide crawler first.
  • Find ways to incorporate accessibility earlier in the design/development process.

Organizations

  • Make sure you have meaningful accessibility statements which reflect your organization’s commitment to remove barriers to people with disabilities.
  • Build a champions network that allows a community of practice to grow and learn from each other.

Limitations Of Automated Tools

Every baker needs to have an arsenal of tools they can rely on. There are proprietary accessibility tools worth considering, but there are also excellent open-source tools including the ones we mentioned in the “recipe” above that are available for free.

In modern dynamic sites, it is important to use automated tools to catch accessibility errors early before they are published to the live site. It’s also important to crawl the site to see that all the pages still comply after they’ve been published and continuously updated.

The challenge is that designers and developers often assume that if the tests don’t report any errors, a site is good. When you give people a test, people tend to write towards it. Unfortunately, many designers and developers stop when they eliminate the errors that they see with WAVE or Axe.

To be clear, it is a small fraction of teams that even do this, but if we want to make sites that are perceivable, operable, and understandable for more people using different types of technology, we have to do better.

Automated tools are great but limited. Even the best available automated tools only catch about 30 to 40% of WCAG compliance accessibility errors. An automated tool can tell you if an image is missing an alternative description, but what it can’t tell you is if the description is entirely inaccurate or used in the wrong context and therefore useless. That still requires a person to evaluate.

To get past these limits, it’s important to recognize that accessibility doesn’t automatically mean usability for people with disabilities. Think of accessibility as the lowest bar; it works with assistive technology, but to go beyond “it works” to “it’s enjoyable and easy to use” you’ll need to test with real users.

Many organizations already do usability testing, but most don’t include people with disabilities. If you’re having trouble recruiting more diverse participants, consider working with an organization that has a community of assistive technology users and a platform to make testing quick and easy.

Let’s Get Baking!

Use a layered accessibility testing approach when you are working to build an inclusive website. Don’t rely on just one type of testing to find barriers for people with disabilities.

  • Test your ideas with assistive technology users early in the process
  • Integrate regular automated code checks into the process of building the site
  • Do manual testing using assistive technology as part of QA
  • Test with people with disabilities prior to launch
  • Perform comprehensive accessibility reviews on staging

Remember the goal isn’t to score high in a testing tool, or even to meet a WCAG guideline, but rather to make your content more widely available, including to assistive technology users.

Ultimately, accessibility statements are the icing on the cake. Include an accessibility statement with contact information on your site to provide a feedback loop. Your users are the experts and everyone should be part of making a site better over time.

Articles on Smashing Magazine — For Web Designers And Developers

26 Apr

How To Bake Layers Of Accessibility Testing Into Your Process

by TBSCategories: News

When building websites or apps, accessibility testing is critical to ensure that what you build will work for all your users. This includes users with disabilities and also people with temporary and situational limitations (like that coworker who broke their arm skiing or the customer who is outdoors on their phone with glare on the screen).

We’re going to share how to “layer” accessibility testing by using a variety of tools and approaches at different stages in the digital product lifecycle to catch accessibility issues early — when it’s easier and cheaper to fix them. Taking a layered approach to testing your site for accessibility also improves the usability of your site — which in turn increases your customer base and reduces customer service inquiries. It can both make and save you money.

We’ll use a layered cake analogy to talk about the different layers of accessibility testing and when to use them. Food analogies have become quite popular in the accessibility world!

This approach has worked well for both of us. Mike is a seasoned accessibility advocate and senior strategist at a government technology firm (CivicActions), and Kate is the Head of Services at an accessibility testing platform (Fable).

While Mike looks at accessibility testing from a more technical angle early in the development phase and scanning for compliance on live sites, Kate focuses on the user experience. Both of us realized that combining many types of accessibility testing throughout the product development life cycle is a powerful way to improve overall product accessibility. In this article, we’ll share some of the things we’ve learned.

Most organizations approach accessibility in three main ways:

  1. Running tools to check your code and/or user interface.
    This is often referred to as “automated testing” because you use software to automatically test many accessibility issues at once.
  2. Using your computer in a way that is different than you normally do.
    For example, by not using a mouse, zooming your browser to 200%), or switching to Windows high contrast mode.
  3. Using assistive technology and users with disabilities to check for usability issues.
    This is often referred to as “manual testing” because it requires a person to evaluate accessibility issues.

Far too many organizations rely exclusively on a single accessibility solution to validate their site. No one tool or process can give an organization the confidence that they are actually meeting the needs of the greatest possible number of people.

How To Secure Buy-In For Accessibility

In many organizations, in order to do accessibility testing, you’ll need executives to prioritize and support the work. Here are tips on how to make that happen if you don’t already have buy-in for accessibility:

  • Check if there is a legal requirement for your organization to be accessible.
    “Accessibility Act” and “Disability Act” are search terms that should pull up relevant laws in most countries. Sharing the legal risk can be the right incentive for some organizations.
  • Find out what your competitors are doing.
    Check for an accessibility statement on their websites. Most organizations are keen to stay ahead of the competition and knowing that others are prioritizing accessibility could do the trick.
  • Connect with customer service to find out if there are accessibility complaints.
    If possible, reach out to customers directly to hear about their experiences and share those stories with company leaders. Hearing about dissatisfied customers can be a huge motivator. If you can get permission from the customers, record a demo of them facing challenges with your products. A video like that can be very compelling.
  • Explain the financial costs and rewards.
    Many companies think they can’t afford to do accessibility, but it’s much more affordable when it’s integrated into the day-to-day work and not an afterthought. There’s also the potential revenue from people with disabilities — globally they represent more than 3 trillion dollars in disposable income.

  • Find the right champion.
    Chances are there’s already someone at the highest levels of the organization who cares about people and doing the right thing. This may be a Diversity and Inclusion lead, someone fighting for environmental sustainability, or other issues. Perhaps it’s someone with a disabled friend or family member. Making them aware of accessibility may be all that’s needed to add a new focus to their efforts.

Gathering Your Ingredients

Accessibility should be baked into your process as early as possible. One place to start is with the procurement process. You can incorporate accessibility as part of the review process for any technology systems you are buying or building. DisabilityIN has some excellent resources on accessible IT procurement.

Looking for vendor accessibility statements or VPATs for products can help, but so can doing a quick review with some of the tools mentioned in the recipe below. Not all software is created equally, so you want to be sure you’re working with vendors who are actively contributing to tools and processes that help you prioritize accessibility from the start.

Another way to bake in accessibility early, if you’re creating or updating a design system, is to choose a component library that has been built with accessibility in mind. Look for libraries with a clear accessibility statement and an open issue queue that allows you to review problems.

Examples:

  • The Angular Components team has built accessibility into the Material UI library. For example, the radio button component uses a radio group with an aria-label. Each radio button reads as checked or not checked to a screen reader user, the buttons can be selected using the arrow keys like standard HTML radio buttons, and the focused state is clearly visible.
  • Reakit for React describes an accessibility warning feature on their accessibility page that will tell developers when an aria-label is needed.
  • The Lion accessible web components library uses an a11y label to tag accessibility issues in GitHub so you can see what’s being improved and open your own issue if needed.

Another way to embed accessibility into your process is to update one of the personas your team uses to include disabilities. Many people have more than one disability, so creating at least one persona with several disabilities will ensure you keep that audience top-of-mind in all your early design work.

To flesh out that persona, talk to people with real disabilities — including temporary and situational limitations — to help you understand how they use technology, sites, and apps in the real world. One in five people have a permanent disability, but 100% of the population will be faced with vision, hearing, motion, or cognitive disabilities at some point in their lives. Our personas can reflect:

  • people with allergies, insomnia, or broken bones;
  • people using outdated technology or using their computers outside; or even
  • people who change their technology use according to their location (for example, disabling images when they need to save internet bandwidth).

Little changes like these can have a big impact on how your team thinks. One way to pitch this change to leadership and teams is to talk about how it will make your personas more reflective of your actual users — which is the whole point of personas. They must be realistic.

One of the most impactful ways to involve people with disabilities is to have them help co-design services and products. Australia has a free training toolkit on how to do co-design with people with disabilities. There’s also a great case study on how one company ran co-design sessions with people with learning disabilities on behalf of the UK government.

Legacy IT

Whether we like it or not, most of the decisions about organizational IT were made months (if not years) ago. Even when you are in the heat of a procurement process, accessibility is typically just one of many considerations. This is to be expected — even in organizations that are passionate about accessibility.

With legacy technology, the first step is simply to raise awareness with the vendor or team about the importance of accessibility. If you can detail accessibility issues that you want to be fixed using automated tools, it can help adjust how a vendor ranks their issue queue. There isn’t always a community portal to post concerns like this, but there might be a community on Twitter or Reddit where you could bring issues to light.

Additionally, there might be a customizable theme that could be adjusted to address some of the concerns. Some solutions may offer an Application Programming Interface (API) that would allow a developer to build an accessible user interface around it.

If a vendor has competitors, it can be useful to highlight the accessibility features that are included in that product. It can be beneficial to remind vendors that you do have options.

If legacy IT is an internally built product, a good way to quickly evaluate it is using the keyboard only. If you can’t use the product with a keyboard (for example, there’s no visible focus or the UI is only mouse clickable), it’s likely going to be a lot of effort to improve the accessibility of the product.

Consider offering alternative ways to access the service (e.g. phone support, in-person service, or email) so that people who can’t access the product digitally because of accessibility barriers can still get what they need.

Think about the organizational roadmap and when it might be feasible to upgrade or retire the product and weigh the cost and effort of accessibility against that. If you have other, newer products that aren’t accessible, it might be more productive to focus your efforts on those products if a legacy tool is nearing the end of life.

The Recipe

Here is an example of a comprehensive accessibility testing approach, with five layers for a really delicious accessibility testing cake. Figure out what your budget is going to be and then price out all the various testing approaches. Some are free, others will cost money. In the next section, we provide advice on where to start if all these layers of testing won’t fit in your budget.

  1. Research User Needs
    Ensure the questionnaire that you use to screen potential research participants asks about assistive technology use. This will make it easy to integrate people with disabilities into your existing research process at no extra cost. If you don’t have luck finding participants this way, try reaching out to disability organizations.

    You can also modify your existing user personas to include users with disabilities. You can borrow aspects of user profiles from Gov.UK if you need to do this quickly and cheaply. If you have the budget for it, add people with disabilities into prototype and design reviews. This may be easiest to do if you engage a vendor that offers this type of service, hence the need for a budget. Alternatively, you can pay participants directly.

  2. Refine Your Process
    Encourage developers, designers, and content authors to include accessibility checks as part of their process. Here are ways to do that using free automated testing tools:
    • Download free browser extensions/plug-ins to do page specific testing for design reviews (WAVE or Accessibility Insights)
    • If you use continuous integration testing as part of the build pipeline for developers, make sure you are evaluating accessibility (there are free open-source tools for this like Axe Core and Pa11y)
    • Give content authors tools in the WYSIWYG interface to identify barriers that they have added (HTML Code Sniffer)
    • Ensure you are crawling your site regularly to catch accessibility issues. If possible, run crawlers in both staging and production environments (Purple Hats is a free open source option)

  3. Manual QA
    You don’t have to add extra people to do QA, just integrate it into your existing process. If you only do one thing, then stop using the mouse during your regular QA. You’ll catch accessibility bugs along with other functional bugs. If you want to do more, test with screen readers, and magnifiers too.

    Here are various ways you can do manual accessibility QA without purchasing any tools:

    • Can you access your site without your mouse? Use simple keyboard-only manual testing to evaluate new components and content.
    • Browse your site with magnification set to 200% or greater using the built-in magnification tools in your browser (Ctrl + +).
    • Flip your browser or OS to dark mode and see if your site works well for people with light sensitivity.
    • Perform sprint-level testing with developers and designers using assistive technology (VoiceOver, Microsoft Narrator, and NVDA are free options).

  4. User Testing
    In large corporate environments with a dedicated budget for accessibility, you can pay assistive technology users to test functionality on your staging environment before launch.

    Nothing gives you greater certainty that your product will work for people with disabilities than validating with users. Not even a perfect WCAG compliance score can give you that assurance the way a real person using the product can.

    People with disabilities are often asked to do work for free, which is problematic as many with disabilities are already at an economic disadvantage. If you’re working on a personal project and there’s no budget, look at your network and see if there are people who would be interested in helping in exchange for an equivalent favor.

  5. Specialist Review
    If your organization has an accessibility team, have them do User Acceptance Testing pre-release. This is where you can get detailed feedback on WCAG compliance that you may have missed in earlier steps.

    Think of it as a final check; your accessibility team isn’t doing all of the work on accessibility, everyone has a role to play. Accessibility teams are most effective when they set standards, provide training, give guidance and evaluate compliance. They support accessibility efforts but aren’t the only ones doing accessibility work. That way no one person or team becomes a bottleneck.

    If you don’t have a team, you can hire accessibility professionals to do the reviews prior to release.

Where To Start

Start where you are. The goal isn’t perfection, but ongoing improvement. Implementing all layers at once doesn’t have to be the goal. Rather, it’s about starting with one or two layers and then gradually adding more layers as your team gets better at accessibility testing. A small slice of cake is better than no cake.

Individuals

  • If you are new to accessibility, start by adding a free browser extension to find accessibility issues and start by learning how to fix the errors that are displayed. WebAIM’s WAVE Toolbar is great for this.
  • Start sharing accessibility information that you have found useful. This could be just on Twitter or Reddit, but you could also start a newsletter to help raise awareness.
  • Sign up for webinars or events focused on accessibility so that you can learn more.

Teams

  • A team with a strong user-centered design approach might want to start with layer one: interviewing people with disabilities as part of user research.
  • A team with a strong IT compliance process might invest in tighter integration of automated testing in their continuous integration process or a site-wide crawler first.
  • Find ways to incorporate accessibility earlier in the design/development process.

Organizations

  • Make sure you have meaningful accessibility statements which reflect your organization’s commitment to remove barriers to people with disabilities.
  • Build a champions network that allows a community of practice to grow and learn from each other.

Limitations Of Automated Tools

Every baker needs to have an arsenal of tools they can rely on. There are proprietary accessibility tools worth considering, but there are also excellent open-source tools including the ones we mentioned in the “recipe” above that are available for free.

In modern dynamic sites, it is important to use automated tools to catch accessibility errors early before they are published to the live site. It’s also important to crawl the site to see that all the pages still comply after they’ve been published and continuously updated.

The challenge is that designers and developers often assume that if the tests don’t report any errors, a site is good. When you give people a test, people tend to write towards it. Unfortunately, many designers and developers stop when they eliminate the errors that they see with WAVE or Axe.

To be clear, it is a small fraction of teams that even do this, but if we want to make sites that are perceivable, operable, and understandable for more people using different types of technology, we have to do better.

Automated tools are great but limited. Even the best available automated tools only catch about 30 to 40% of WCAG compliance accessibility errors. An automated tool can tell you if an image is missing an alternative description, but what it can’t tell you is if the description is entirely inaccurate or used in the wrong context and therefore useless. That still requires a person to evaluate.

To get past these limits, it’s important to recognize that accessibility doesn’t automatically mean usability for people with disabilities. Think of accessibility as the lowest bar; it works with assistive technology, but to go beyond “it works” to “it’s enjoyable and easy to use” you’ll need to test with real users.

Many organizations already do usability testing, but most don’t include people with disabilities. If you’re having trouble recruiting more diverse participants, consider working with an organization that has a community of assistive technology users and a platform to make testing quick and easy.

Let’s Get Baking!

Use a layered accessibility testing approach when you are working to build an inclusive website. Don’t rely on just one type of testing to find barriers for people with disabilities.

  • Test your ideas with assistive technology users early in the process
  • Integrate regular automated code checks into the process of building the site
  • Do manual testing using assistive technology as part of QA
  • Test with people with disabilities prior to launch
  • Perform comprehensive accessibility reviews on staging

Remember the goal isn’t to score high in a testing tool, or even to meet a WCAG guideline, but rather to make your content more widely available, including to assistive technology users.

Ultimately, accessibility statements are the icing on the cake. Include an accessibility statement with contact information on your site to provide a feedback loop. Your users are the experts and everyone should be part of making a site better over time.

Articles on Smashing Magazine — For Web Designers And Developers


Deprecated: Function create_function() is deprecated in /home2/thebrand/public_html/wp-content/plugins/wp-spamshield/wp-spamshield.php on line 1884
25 Mar

A Deep Dive Into Eleventy Static Site Generator

by TBSCategories: News

But first — let’s quickly review what is meant by a “static site” and then what a generator provides. A static site is composed of static content — as in, the HTML, CSS, assets, and all content are already compiled together before pushing to a website host. This is different from a dynamic site that compiles those things from querying a database at run time (like WordPress) or that pulls content from APIs client-side (like JavaScript frameworks without server-side rendering).

A static site generator is an environment and build processor to compile your content into static HTML. They usually offer helpers to provide flexibility in writing your content (like supporting Markdown) and include methods for templating. So instead of writing HTML pages one by one and having to copy and paste the repeated parts, a generator will support breaking those things into components via a certain templating language. Then the generator’s build process will bring everything together and output the final HTML that can be uploaded to a web host to be served as your website. Depending on the web host you use, this build process can even be done by the host.

There are many static site generators available. You may have heard of or even used ones like Jekyll, Hugo, Gatsby, Next and Nuxt. A comprehensive list is provided by Jamstack.org.

What Makes Eleventy Different From Other Static Site Generators?

Eleventy is exceptionally fast both during builds and in the browser. This is largely thanks to not requiring the loading of a client-side JavaScript bundle in order to serve content (compared to something like Gatsby). Server-side rendering isn’t even a concern here, since the filesystem page creation defaults to static HTML.

What really makes Eleventy unique is the ability to select from and intermix up to ten different templating languages:

Intermixing languages can happen in the same file, or between layouts. For example, I often write my main content with Markdown that feeds into a Nunjucks layout. In some projects, I’ve found it useful to be able to loop over some data using Nunjucks while in the Markdown file. This ability to combine languages is very powerful, and allows you to design a write-and-build workflow that works best for you and your project.

Eleventy includes a --serve flag that uses BrowserSync to enable serving the site locally and with hot-reload upon file changes. This is a great convenience, and is good to keep in mind if you’re not looking for a static site generator but perhaps an upgrade from build tools like Gulp.

As part of being zero-config, all your site files could live in the root of your project. To alter the input and output directories, you can create an Eleventy config, which is expected to be a root file called .eleventy.js. Here’s a quick snippet showing how to make this modification:

module.exports = function (eleventyConfig) {   return {     dir: {       // default: [site root]       input: "src",       // default: _site       output: "public",     },   }; };

As noted earlier, the default behavior is filesystem page creation which is generally of great benefit especially for rapidly getting started. This is easily overrideable by assigning a custom permalink and that can be done per file, for an entire directory, or dynamically for a set of data. Permalinks also offer another superpower which we’ll explore in a bit!

Uniquely, during the build, you can prepare content, data, and transforms on that content and data by using JavaScript and leveraging filters and shortcodes (we’ll talk about those later). Again, this all happens without adding a JavaScript bundle client-side, while still enabling the use of JavaScript as a templating language.

Important Note: You can successfully use Eleventy with no or low JavaScript knowledge.

Unlike other SSGs like Gatsby, or environments like WordPress, most Eleventy sites do not require any plugins. There are some plugins available, but they are not necessary for essential functionality.

When building with Eleventy, you can add on features as you need them. In fact, you could just use HTML and never work with any of the other templating languages. Eleventy is only as complex as your project requires!

Understanding Essential Eleventy Concepts

Let’s go over a few bits of terminology and concepts that will help you be successful in creating your Eleventy projects.

Layouts And Templates

You may think of these terms as interchangeable, but in Eleventy’s context, they do have contextual meanings:

  • Template is the generic term for all content files.
  • Layouts are special templates that wrap other content.

For example, template refers to all your Markdown files, whereas a layout might be a Nunjucks file that contains the HTML5 boilerplate and a slot for the template content. We’ll learn how to make this work in the section on getting started.

Filters And Shortcodes

These are additional ways to modify content output, and create reusable template parts. They are available for use with Nunjucks, Liquid, Handlebars, and JavaScript templating. Filters and shortcodes are defined within .eleventy.js.

Beyond variables and operators available in your templating language of choice, Eleventy has unified the concept of filters across the previously listed languages. Filters transform content in some way specific to the content type. For example, you may create a filter intended for strings to uppercase them. Or you might have a filter intended to be used on arrays to alter what is returned, like picking a random item. Some filters are provided by Eleventy, a few of which we’ll use in the getting started tutorial.

Shortcodes allow creating reusable template parts and are able to accept arguments. They can be either standalone or paired, meaning they wrap content with a start and end tag.

One of my favorite shortcodes is to render the current year — meaning no more out of date copyright years in your footer! Here’s how to create a year shortcode:

eleventyConfig.addShortcode("year", () => $  {new Date().getFullYear()});

To use it in a Nunjucks or Liquid template looks like this: {% year %}.

You can review the Eleventy docs for examples of paired shortcodes.

Collections

Collections are groups of related content, and are typically created within frontmatter by defining tags. Tag syntax options include single strings, single-line arrays — ["tagA", "tagB"] — for multiples, or YAML-style lists to assign multiple tags. For example, I can create a “pages” collection by adding the following frontmatter to all content I want to be included in that collection:

--- tags: pages ---

Once you have defined a collection, you can access it via your templating language of choice within the global collections object. To access our “pages” collection would look like collections.pages. This returns an array of that collection’s data, and so you can perform array operations like looping over it such as to produce a list of links or article teaser cards. You can even suppress normal file output and use only collections to manage data display, which is useful for managing single-page site content.

Custom Data

So far we’ve talked about creating content as files, but Eleventy also makes it very easy to maintain different data sources. This is called “custom data” and lives as JavaScript module exports or JSON files in the _data directory.

Custom data can be used to:

  • Define a basic JSON array.
  • Return the results of a fetch operation.
  • Retrieve and re-format content from a headless CMS.

Eleventy makes all data from within _data available under a variable matching the filename. For example, if I create posts.json then I can access that in my templates as posts. Using Nunjucks, here’s an example of looping over the posts data:

{% for post in posts %}   {{ post.title }} {% endfor %}

Pagination And Creating Pages From Data

In Eleventy terms, pagination refers to iterating over a data set and defining a template for the output of that data “chunk”. This is done with a dedicated file that defines the pagination within frontmatter. The file also includes setting up your intended output for the data, meaning it becomes its own template as well. We can define a layout to send the content to and also add tags to create a collection for ease of reference and flexibility for the output.

Note: If you use custom data to retrieve content from a CMS, then pagination is the Eleventy method you’re looking for to turn that data into pages dynamically.

Here’s an example of referencing our posts custom data which we’ll assume we’re retrieving via a fetch from a headless CMS. Importantly, the size is set to 1, which means each “pagination chunk” should produce one single page of output. We then use the alias to create a reference to the current item in the pagination loop, and then use that reference in the permalink definition and the template body.

The file that defines the pagination can live wherever you’d like within your input directory. My organizational preference is to create a generate directory, and then name it the same as the collection it will be creating. Consider the following to be src/generate/posts.njk:

--- pagination:   data: posts   size: 1   alias: post   addAllPagesToCollections: true permalink: "/{{ post.title | slug }}/" tags: posts layout: post templateEngineOverride: njk, md --- {{ post.body | safe }}

In this case, the permalink is assigning the page to be output directly off of the site root. You could change this to add a prefix such as /posts/{{ post.title | slug }}, for example.

Additionally, if you want all of the generated pages to be available in the collection created by the tags, you must set addAllPagesToCollections to true to include more than the first item.

Lastly, if your content is coming in as Markdown instead of pre-compiled HTML, you’ll need to use the templateEngineOverride. In the example snippet, I’ve set it to njk, md which means the template content will need to be processed both as Nunjucks in order to convert the variable, and then Markdown to compile the contents returned in the variable.

If you’re wondering what safe means, we’re going to learn that next!

How To Get Started With Eleventy

Alright, so you’re ready to get going with your first Eleventy project! This brief tutorial will help you get a starting structure in place to continue building from. We’ll use the concepts we’ve already learned about and add a few new ideas, too.

The first important note here is that Eleventy is a scoped package, so here’s the install command:

npm install @11ty/eleventy

Next, a handy convenience I like to do is add the following scripts into my package.json:

"scripts": {   "start": "eleventy --serve",   "build": "eleventy" }

As mentioned previously, the --serve flag will enable a local server via BrowserSync.

My preference is to update the input/output directories as we already looked at, so now it’s time to create some content within src or the input directory of your choosing.

In order to prepare our project to be more flexible and scalable from the start, I would suggest creating at least one layout that contains the HTML5 boilerplate. Layouts need to be defined within a directly called _includes, which is one of a handful of expected directories.

A convention that you’ll often find among starters is to call this layout base. I have a preference for making it a Nunjucks file.

Here’s a sample base.njk:

<!DOCTYPE html> <html lang="en"> <head>   <meta charset="UTF-8">   <meta name="viewport" content="width=device-width, initial-scale=1.0">   <title>{{ title }}</title> </head> <body>   <header>     <h1>{{ title }}</h1>   </header>   <main>     {{ content | safe }}   </main> </body> </html>

The double curly braces are Nunjucks syntax for variables. Here, we’ve prepared for an incoming title variable that will shortly be supplied via front matter. The content variable is provided by Eleventy and marks the slot where all incoming non-front matter content should go. Importantly, this is used in conjunction with the provided safe filter which prevents compiled HTML from being escaped versus rendered.

Now it’s time to create our site index, which we’ll add as index.md:

--- title: Hello Smashing Readers! layout: base.njk ---  Thanks for reading — hope you’re excited to try Eleventy!

Notice that in the front matter we added our title, and also defined the layout.

At this point, we can run our project with the script we added: npm start. This will trigger BrowserSync to setup localhost:8080 (if it’s available) but you will need to manually open it in the browser. Check out this quick tip if you’d like it to open the browser automatically.

The last critical step is to add a stylesheet. Currently, CSS isn’t recognized as an automatically included filetype so we’ll have one extra config step after we create our stylesheet.

You can add a CSS file wherever you’d like in your input directory, such as css/style.css. Then, open .eleventy.js (or create it in the project root if you didn’t do the input/output customization) and add the following :

module.exports = function (eleventyConfig) {   eleventyConfig.addPassthroughCopy("./src/css/");   eleventyConfig.addWatchTarget("./src/css/");    // - input/output customization if using - };

First, we add the css directory as a “passthrough copy” which means Eleventy should include it in the push to the output directory. Then we also add it as a “watch target” so that as we make changes to our styles while running our start command, Eleventy will trigger a rebuild to update our local site.

Lastly, we need to remember to add the link to our stylesheet within our base layout:

<link rel="stylesheet" href="{{ '/css/style.css' | url }}" />

When we define the stylesheet’s location, we pass it through Eleventy’s url filter which will adjust the relative file path as needed upon build.

Next, let’s create a “pages” post type to explore using collections and layouts a bit more. To do this, add the directory of pages and create one or two Markdown files, including a title front-matter key but not a layout.

We’re going to use a slightly different method to define the layout this time — a data directory file. This file is generally formatted as JSON and enables us to add data that should be applied to all files within a directory, which prevents having to duplicate it across files. The file needs to be named the same as the directory it will be used for, so create the file pages.json and add the following content:

{   "layout": "page.njk",   "tags": "pages" }

We’ve also gone ahead and defined tags in order to create the “pages” collection. But the layout we defined doesn’t actually exist yet, so create _includes/page.njk and add the following:

--- layout: base.njk ---  <article>   {{ content | safe }} </article>

Here we’re using the Eleventy concept of layout chaining to be able to re-use our base template but also add a unique element for our page layout, which is the <article>. This means that all of the content of our pages will use both the page layout and base layouts.

Layout chaining reduces duplication by allowing re-use of boilerplates and base site layout structures.

Now that we’ve created content for the pages content type and defined it as the “pages” collection via the tags, let’s see how we can access that collection. Here, we’ll use Nunjucks to loop over the collection and output a list of links to each page. This loop will be added within our index.md file.

{% for post in collections.post -%} - [{{ post.data.title }}]({{ post.url }}) {% endfor %}

We’ve done something unique though which is that the inside of the loop actually switches back to Markdown to render the links. This is not a required way to handle this scenario, but it can be very handy! Sometimes, depending on complexity, this may not work. The real reason is that the Markdown renderer defaults to Liquid templating language, so if you’re using Nunjucks features beyond basic loops, you will have to let Eleventy know how to process the file.

In the earlier section on pagination, we actually already looked at the solution for this. And that is to make use of the templateEngineOverride to indicate that the file should be processed as both Nunjucks and Markdown. The following full solution should be placed in the template’s front matter: templateEngineOverride: njk, md.

At this point, you’ve created a basic multi-page site! If you have need of using external data, jump back up to the section on pagination.

Other Ways To Start An Eleventy Project

Whereas some other static site generators and environments like WordPress have the concept of “themes”, Eleventy uses the term “starter”. There is a growing collection to choose from, and many can be found in the listing within the Eleventy docs.

My preference is to use Sass with my Eleventy projects, and I have a Sass starter available if you’d like to see how to add that into your build process. Others may choose to add in Gulp if they are used to that build pipeline for assets and processing.

I’ve also created a minimal starter that includes the features discussed in this article and shares similarities with the tutorial result. It also has a small example of fetching external data, and shows how to add in a partial to display site navigation based on a collection.

Expanding On The Basics

Once you’ve experimented with creating your first site with some basic content and maybe some custom data, it’s helpful to know additional ways to work with that content. Here is a brief overview of some other concepts to be aware of.

Altering File Output Type With Permalinks

I mentioned earlier that permalinks have a superpower. And that is that you can use them to output non-HTML file types.

Two useful examples are creating an RSS feed and a sitemap, both of which happen to typically be XML files. What’s really powerful is that you can continue to use the templating language of your choice to help generate those files, so you can loop over page data with Nunjucks to keep your RSS feed fresh, for example.

Customizing Collections

Sometimes using tags to create collections may not be sufficient. Or, you may want to create filtered variations of an existing collection. We can alter or create collections by using a series of provided functions. These will live in the .eleventy.js config file.

In this example, we’re using the addCollection function to filter items in an existing collection. The new collection will be based on the existence of customKey within front matter. This key is returned off of the data object which is attached to all generated Eleventy content.

eleventyConfig.addCollection("specialCollection", function (collection) {   return collection.getAll().filter((post) => post.data.customKey); });

You can review other ways to create, modify, and use collections in the Eleventy docs.

Working With The Data Cascade

Eleventy has a more full concept of how data is compiled for a template called the data cascade which we only just began exploring in this guide. You will get the most out of Eleventy if you review how that works, starting in the docs. Ben Myers also has an excellent guide to understanding the data cascade.

Recommended Eleventy Plugins

In the intro, I briefly mentioned there were plugins available, but that they aren’t always needed. However, there are a few I tend to use on most projects, which include:

  • @11ty/eleventy-plugin-rss If you would like to have an RSS feed, this official plugin provides some filters to help you to generate the feed. The linked repo includes a sample feed, which you may also find in use within some starters.
  • @11ty/eleventy-plugin-syntaxhighlight Instead of loading Prism as a script for code highlighting, this plugin allows that processing to be applied as part of the Eleventy build process. This means code blocks are transformed to include the classes for applying a Prism theme ahead of time, so you will only need to add a Prism CSS theme of your choice.
  • @11tyrocks/eleventy-plugin-social-images A feature I sought out early in my Eleventy exploration was the ability to generate social media share images. This led me to create a plugin that uses Puppeteer behind the scenes to take the snapshot. The plugin comes with prebuilt templates as well as config options to define your own template file.

I would also recommend becoming familiar with the rest of the official Eleventy plugins as they address other common needs including navigation and image handling.

Deciding If Eleventy Is Right For Your Project

Eleventy, like most static sites, is best for content that doesn’t typically need to be served dynamically or on-demand. This is not to say all of the site has to be static, or that there are not ways to make content dynamic. You may still load JavaScript to enable dynamic content like fetching from APIs or creating interactive widgets. You can also use services like IFTTT or Zapier to facilitate rebuilding your site if your host supports build webhooks and you have parts that you want to refresh on a schedule.

Thanks to custom data and pagination, we saw it was easy to include external data as from a headless CMS or any other API. So although it will be served statically, you still have a lot of flexibility in where you pull content and how you manage it.

My favorite thing about Eleventy is that it doesn’t impose many opinions on how I should structure my site, beyond the few expected directories we talked about for _includes and _data (and you can update the naming convention of those, too). This can also be helpful if you are looking to migrate a site and being able to potentially move some existing file structure as well. However, if you prefer a more opinionated architecture, you might seek a different option.

I also enjoy how I can mold Eleventy to fit my mental model for a given project by leveraging multiple templating languages as well as filters, shortcodes, and layouts. Starters also help give a boost so that you can focus on what’s really important: your content. And the high performance of purely static output is also a great benefit.

If you do need a bit more in your build process, you can add other familiar tools like Webpack, Gulp, or Parcel. You may be able to find a starter that already includes those things. Keep in mind you can also leverage Node scripts which are already inherent to the Eleventy build process.

Eleventy is very capable of handling large amounts of page generation. It has been used for some large and complex sites such as Google’s web.dev and Netlify’s marketing site. I’ve also used Eleventy for some unconventional purposes, like email and web component generators, along with some others which are described in this overview.

Additional Resources

I hope this guide has both peaked your interest and prepared you to begin using Eleventy! It included a lot of points that I found a bit tricky to uncover when I was creating my first project with it. Since I first found Eleventy in April 2020, I’ve built over 20 Eleventy projects counting starters, plugins, side projects, and course materials. Many of those can be found on my site 11ty.Rocks which also has tutorials and tips. Eleventy is something I really enjoy discussing, so feel free to reach out on Twitter!

The following are more resources for helping you on your journey to learn and get the most out of Eleventy:

Finally, I want to note that the Eleventy community is small but active! If you ever have difficulty finding some information, you can tweet your question to the official @eleven_ty account. Eleventy’s creator, Zach Leatherman, is quick to answer or RT questions to help get you back on your way!

Articles on Smashing Magazine — For Web Designers And Developers


Deprecated: Function create_function() is deprecated in /home2/thebrand/public_html/wp-content/plugins/wp-spamshield/wp-spamshield.php on line 1884
25 Mar

A Deep Dive Into Eleventy Static Site Generator

by TBSCategories: News

But first — let’s quickly review what is meant by a “static site” and then what a generator provides. A static site is composed of static content — as in, the HTML, CSS, assets, and all content are already compiled together before pushing to a website host. This is different from a dynamic site that compiles those things from querying a database at run time (like WordPress) or that pulls content from APIs client-side (like JavaScript frameworks without server-side rendering).

A static site generator is an environment and build processor to compile your content into static HTML. They usually offer helpers to provide flexibility in writing your content (like supporting Markdown) and include methods for templating. So instead of writing HTML pages one by one and having to copy and paste the repeated parts, a generator will support breaking those things into components via a certain templating language. Then the generator’s build process will bring everything together and output the final HTML that can be uploaded to a web host to be served as your website. Depending on the web host you use, this build process can even be done by the host.

There are many static site generators available. You may have heard of or even used ones like Jekyll, Hugo, Gatsby, Next and Nuxt. A comprehensive list is provided by Jamstack.org.

What Makes Eleventy Different From Other Static Site Generators?

Eleventy is exceptionally fast both during builds and in the browser. This is largely thanks to not requiring the loading of a client-side JavaScript bundle in order to serve content (compared to something like Gatsby). Server-side rendering isn’t even a concern here, since the filesystem page creation defaults to static HTML.

What really makes Eleventy unique is the ability to select from and intermix up to ten different templating languages:

Intermixing languages can happen in the same file, or between layouts. For example, I often write my main content with Markdown that feeds into a Nunjucks layout. In some projects, I’ve found it useful to be able to loop over some data using Nunjucks while in the Markdown file. This ability to combine languages is very powerful, and allows you to design a write-and-build workflow that works best for you and your project.

Eleventy includes a --serve flag that uses BrowserSync to enable serving the site locally and with hot-reload upon file changes. This is a great convenience, and is good to keep in mind if you’re not looking for a static site generator but perhaps an upgrade from build tools like Gulp.

As part of being zero-config, all your site files could live in the root of your project. To alter the input and output directories, you can create an Eleventy config, which is expected to be a root file called .eleventy.js. Here’s a quick snippet showing how to make this modification:

module.exports = function (eleventyConfig) {   return {     dir: {       // default: [site root]       input: "src",       // default: _site       output: "public",     },   }; };

As noted earlier, the default behavior is filesystem page creation which is generally of great benefit especially for rapidly getting started. This is easily overrideable by assigning a custom permalink and that can be done per file, for an entire directory, or dynamically for a set of data. Permalinks also offer another superpower which we’ll explore in a bit!

Uniquely, during the build, you can prepare content, data, and transforms on that content and data by using JavaScript and leveraging filters and shortcodes (we’ll talk about those later). Again, this all happens without adding a JavaScript bundle client-side, while still enabling the use of JavaScript as a templating language.

Important Note: You can successfully use Eleventy with no or low JavaScript knowledge.

Unlike other SSGs like Gatsby, or environments like WordPress, most Eleventy sites do not require any plugins. There are some plugins available, but they are not necessary for essential functionality.

When building with Eleventy, you can add on features as you need them. In fact, you could just use HTML and never work with any of the other templating languages. Eleventy is only as complex as your project requires!

Understanding Essential Eleventy Concepts

Let’s go over a few bits of terminology and concepts that will help you be successful in creating your Eleventy projects.

Layouts And Templates

You may think of these terms as interchangeable, but in Eleventy’s context, they do have contextual meanings:

  • Template is the generic term for all content files.
  • Layouts are special templates that wrap other content.

For example, template refers to all your Markdown files, whereas a layout might be a Nunjucks file that contains the HTML5 boilerplate and a slot for the template content. We’ll learn how to make this work in the section on getting started.

Filters And Shortcodes

These are additional ways to modify content output, and create reusable template parts. They are available for use with Nunjucks, Liquid, Handlebars, and JavaScript templating. Filters and shortcodes are defined within .eleventy.js.

Beyond variables and operators available in your templating language of choice, Eleventy has unified the concept of filters across the previously listed languages. Filters transform content in some way specific to the content type. For example, you may create a filter intended for strings to uppercase them. Or you might have a filter intended to be used on arrays to alter what is returned, like picking a random item. Some filters are provided by Eleventy, a few of which we’ll use in the getting started tutorial.

Shortcodes allow creating reusable template parts and are able to accept arguments. They can be either standalone or paired, meaning they wrap content with a start and end tag.

One of my favorite shortcodes is to render the current year — meaning no more out of date copyright years in your footer! Here’s how to create a year shortcode:

eleventyConfig.addShortcode("year", () => $  {new Date().getFullYear()});

To use it in a Nunjucks or Liquid template looks like this: {% year %}.

You can review the Eleventy docs for examples of paired shortcodes.

Collections

Collections are groups of related content, and are typically created within frontmatter by defining tags. Tag syntax options include single strings, single-line arrays — ["tagA", "tagB"] — for multiples, or YAML-style lists to assign multiple tags. For example, I can create a “pages” collection by adding the following frontmatter to all content I want to be included in that collection:

--- tags: pages ---

Once you have defined a collection, you can access it via your templating language of choice within the global collections object. To access our “pages” collection would look like collections.pages. This returns an array of that collection’s data, and so you can perform array operations like looping over it such as to produce a list of links or article teaser cards. You can even suppress normal file output and use only collections to manage data display, which is useful for managing single-page site content.

Custom Data

So far we’ve talked about creating content as files, but Eleventy also makes it very easy to maintain different data sources. This is called “custom data” and lives as JavaScript module exports or JSON files in the _data directory.

Custom data can be used to:

  • Define a basic JSON array.
  • Return the results of a fetch operation.
  • Retrieve and re-format content from a headless CMS.

Eleventy makes all data from within _data available under a variable matching the filename. For example, if I create posts.json then I can access that in my templates as posts. Using Nunjucks, here’s an example of looping over the posts data:

{% for post in posts %}   {{ post.title }} {% endfor %}

Pagination And Creating Pages From Data

In Eleventy terms, pagination refers to iterating over a data set and defining a template for the output of that data “chunk”. This is done with a dedicated file that defines the pagination within frontmatter. The file also includes setting up your intended output for the data, meaning it becomes its own template as well. We can define a layout to send the content to and also add tags to create a collection for ease of reference and flexibility for the output.

Note: If you use custom data to retrieve content from a CMS, then pagination is the Eleventy method you’re looking for to turn that data into pages dynamically.

Here’s an example of referencing our posts custom data which we’ll assume we’re retrieving via a fetch from a headless CMS. Importantly, the size is set to 1, which means each “pagination chunk” should produce one single page of output. We then use the alias to create a reference to the current item in the pagination loop, and then use that reference in the permalink definition and the template body.

The file that defines the pagination can live wherever you’d like within your input directory. My organizational preference is to create a generate directory, and then name it the same as the collection it will be creating. Consider the following to be src/generate/posts.njk:

--- pagination:   data: posts   size: 1   alias: post   addAllPagesToCollections: true permalink: "/{{ post.title | slug }}/" tags: posts layout: post templateEngineOverride: njk, md --- {{ post.body | safe }}

In this case, the permalink is assigning the page to be output directly off of the site root. You could change this to add a prefix such as /posts/{{ post.title | slug }}, for example.

Additionally, if you want all of the generated pages to be available in the collection created by the tags, you must set addAllPagesToCollections to true to include more than the first item.

Lastly, if your content is coming in as Markdown instead of pre-compiled HTML, you’ll need to use the templateEngineOverride. In the example snippet, I’ve set it to njk, md which means the template content will need to be processed both as Nunjucks in order to convert the variable, and then Markdown to compile the contents returned in the variable.

If you’re wondering what safe means, we’re going to learn that next!

How To Get Started With Eleventy

Alright, so you’re ready to get going with your first Eleventy project! This brief tutorial will help you get a starting structure in place to continue building from. We’ll use the concepts we’ve already learned about and add a few new ideas, too.

The first important note here is that Eleventy is a scoped package, so here’s the install command:

npm install @11ty/eleventy

Next, a handy convenience I like to do is add the following scripts into my package.json:

"scripts": {   "start": "eleventy --serve",   "build": "eleventy" }

As mentioned previously, the --serve flag will enable a local server via BrowserSync.

My preference is to update the input/output directories as we already looked at, so now it’s time to create some content within src or the input directory of your choosing.

In order to prepare our project to be more flexible and scalable from the start, I would suggest creating at least one layout that contains the HTML5 boilerplate. Layouts need to be defined within a directly called _includes, which is one of a handful of expected directories.

A convention that you’ll often find among starters is to call this layout base. I have a preference for making it a Nunjucks file.

Here’s a sample base.njk:

<!DOCTYPE html> <html lang="en"> <head>   <meta charset="UTF-8">   <meta name="viewport" content="width=device-width, initial-scale=1.0">   <title>{{ title }}</title> </head> <body>   <header>     <h1>{{ title }}</h1>   </header>   <main>     {{ content | safe }}   </main> </body> </html>

The double curly braces are Nunjucks syntax for variables. Here, we’ve prepared for an incoming title variable that will shortly be supplied via front matter. The content variable is provided by Eleventy and marks the slot where all incoming non-front matter content should go. Importantly, this is used in conjunction with the provided safe filter which prevents compiled HTML from being escaped versus rendered.

Now it’s time to create our site index, which we’ll add as index.md:

--- title: Hello Smashing Readers! layout: base.njk ---  Thanks for reading — hope you’re excited to try Eleventy!

Notice that in the front matter we added our title, and also defined the layout.

At this point, we can run our project with the script we added: npm start. This will trigger BrowserSync to setup localhost:8080 (if it’s available) but you will need to manually open it in the browser. Check out this quick tip if you’d like it to open the browser automatically.

The last critical step is to add a stylesheet. Currently, CSS isn’t recognized as an automatically included filetype so we’ll have one extra config step after we create our stylesheet.

You can add a CSS file wherever you’d like in your input directory, such as css/style.css. Then, open .eleventy.js (or create it in the project root if you didn’t do the input/output customization) and add the following :

module.exports = function (eleventyConfig) {   eleventyConfig.addPassthroughCopy("./src/css/");   eleventyConfig.addWatchTarget("./src/css/");    // - input/output customization if using - };

First, we add the css directory as a “passthrough copy” which means Eleventy should include it in the push to the output directory. Then we also add it as a “watch target” so that as we make changes to our styles while running our start command, Eleventy will trigger a rebuild to update our local site.

Lastly, we need to remember to add the link to our stylesheet within our base layout:

<link rel="stylesheet" href="{{ '/css/style.css' | url }}" />

When we define the stylesheet’s location, we pass it through Eleventy’s url filter which will adjust the relative file path as needed upon build.

Next, let’s create a “pages” post type to explore using collections and layouts a bit more. To do this, add the directory of pages and create one or two Markdown files, including a title front-matter key but not a layout.

We’re going to use a slightly different method to define the layout this time — a data directory file. This file is generally formatted as JSON and enables us to add data that should be applied to all files within a directory, which prevents having to duplicate it across files. The file needs to be named the same as the directory it will be used for, so create the file pages.json and add the following content:

{   "layout": "page.njk",   "tags": "pages" }

We’ve also gone ahead and defined tags in order to create the “pages” collection. But the layout we defined doesn’t actually exist yet, so create _includes/page.njk and add the following:

--- layout: base.njk ---  <article>   {{ content | safe }} </article>

Here we’re using the Eleventy concept of layout chaining to be able to re-use our base template but also add a unique element for our page layout, which is the <article>. This means that all of the content of our pages will use both the page layout and base layouts.

Layout chaining reduces duplication by allowing re-use of boilerplates and base site layout structures.

Now that we’ve created content for the pages content type and defined it as the “pages” collection via the tags, let’s see how we can access that collection. Here, we’ll use Nunjucks to loop over the collection and output a list of links to each page. This loop will be added within our index.md file.

{% for post in collections.post -%} - [{{ post.data.title }}]({{ post.url }}) {% endfor %}

We’ve done something unique though which is that the inside of the loop actually switches back to Markdown to render the links. This is not a required way to handle this scenario, but it can be very handy! Sometimes, depending on complexity, this may not work. The real reason is that the Markdown renderer defaults to Liquid templating language, so if you’re using Nunjucks features beyond basic loops, you will have to let Eleventy know how to process the file.

In the earlier section on pagination, we actually already looked at the solution for this. And that is to make use of the templateEngineOverride to indicate that the file should be processed as both Nunjucks and Markdown. The following full solution should be placed in the template’s front matter: templateEngineOverride: njk, md.

At this point, you’ve created a basic multi-page site! If you have need of using external data, jump back up to the section on pagination.

Other Ways To Start An Eleventy Project

Whereas some other static site generators and environments like WordPress have the concept of “themes”, Eleventy uses the term “starter”. There is a growing collection to choose from, and many can be found in the listing within the Eleventy docs.

My preference is to use Sass with my Eleventy projects, and I have a Sass starter available if you’d like to see how to add that into your build process. Others may choose to add in Gulp if they are used to that build pipeline for assets and processing.

I’ve also created a minimal starter that includes the features discussed in this article and shares similarities with the tutorial result. It also has a small example of fetching external data, and shows how to add in a partial to display site navigation based on a collection.

Expanding On The Basics

Once you’ve experimented with creating your first site with some basic content and maybe some custom data, it’s helpful to know additional ways to work with that content. Here is a brief overview of some other concepts to be aware of.

Altering File Output Type With Permalinks

I mentioned earlier that permalinks have a superpower. And that is that you can use them to output non-HTML file types.

Two useful examples are creating an RSS feed and a sitemap, both of which happen to typically be XML files. What’s really powerful is that you can continue to use the templating language of your choice to help generate those files, so you can loop over page data with Nunjucks to keep your RSS feed fresh, for example.

Customizing Collections

Sometimes using tags to create collections may not be sufficient. Or, you may want to create filtered variations of an existing collection. We can alter or create collections by using a series of provided functions. These will live in the .eleventy.js config file.

In this example, we’re using the addCollection function to filter items in an existing collection. The new collection will be based on the existence of customKey within front matter. This key is returned off of the data object which is attached to all generated Eleventy content.

eleventyConfig.addCollection("specialCollection", function (collection) {   return collection.getAll().filter((post) => post.data.customKey); });

You can review other ways to create, modify, and use collections in the Eleventy docs.

Working With The Data Cascade

Eleventy has a more full concept of how data is compiled for a template called the data cascade which we only just began exploring in this guide. You will get the most out of Eleventy if you review how that works, starting in the docs. Ben Myers also has an excellent guide to understanding the data cascade.

Recommended Eleventy Plugins

In the intro, I briefly mentioned there were plugins available, but that they aren’t always needed. However, there are a few I tend to use on most projects, which include:

  • @11ty/eleventy-plugin-rss If you would like to have an RSS feed, this official plugin provides some filters to help you to generate the feed. The linked repo includes a sample feed, which you may also find in use within some starters.
  • @11ty/eleventy-plugin-syntaxhighlight Instead of loading Prism as a script for code highlighting, this plugin allows that processing to be applied as part of the Eleventy build process. This means code blocks are transformed to include the classes for applying a Prism theme ahead of time, so you will only need to add a Prism CSS theme of your choice.
  • @11tyrocks/eleventy-plugin-social-images A feature I sought out early in my Eleventy exploration was the ability to generate social media share images. This led me to create a plugin that uses Puppeteer behind the scenes to take the snapshot. The plugin comes with prebuilt templates as well as config options to define your own template file.

I would also recommend becoming familiar with the rest of the official Eleventy plugins as they address other common needs including navigation and image handling.

Deciding If Eleventy Is Right For Your Project

Eleventy, like most static sites, is best for content that doesn’t typically need to be served dynamically or on-demand. This is not to say all of the site has to be static, or that there are not ways to make content dynamic. You may still load JavaScript to enable dynamic content like fetching from APIs or creating interactive widgets. You can also use services like IFTTT or Zapier to facilitate rebuilding your site if your host supports build webhooks and you have parts that you want to refresh on a schedule.

Thanks to custom data and pagination, we saw it was easy to include external data as from a headless CMS or any other API. So although it will be served statically, you still have a lot of flexibility in where you pull content and how you manage it.

My favorite thing about Eleventy is that it doesn’t impose many opinions on how I should structure my site, beyond the few expected directories we talked about for _includes and _data (and you can update the naming convention of those, too). This can also be helpful if you are looking to migrate a site and being able to potentially move some existing file structure as well. However, if you prefer a more opinionated architecture, you might seek a different option.

I also enjoy how I can mold Eleventy to fit my mental model for a given project by leveraging multiple templating languages as well as filters, shortcodes, and layouts. Starters also help give a boost so that you can focus on what’s really important: your content. And the high performance of purely static output is also a great benefit.

If you do need a bit more in your build process, you can add other familiar tools like Webpack, Gulp, or Parcel. You may be able to find a starter that already includes those things. Keep in mind you can also leverage Node scripts which are already inherent to the Eleventy build process.

Eleventy is very capable of handling large amounts of page generation. It has been used for some large and complex sites such as Google’s web.dev and Netlify’s marketing site. I’ve also used Eleventy for some unconventional purposes, like email and web component generators, along with some others which are described in this overview.

Additional Resources

I hope this guide has both peaked your interest and prepared you to begin using Eleventy! It included a lot of points that I found a bit tricky to uncover when I was creating my first project with it. Since I first found Eleventy in April 2020, I’ve built over 20 Eleventy projects counting starters, plugins, side projects, and course materials. Many of those can be found on my site 11ty.Rocks which also has tutorials and tips. Eleventy is something I really enjoy discussing, so feel free to reach out on Twitter!

The following are more resources for helping you on your journey to learn and get the most out of Eleventy:

Finally, I want to note that the Eleventy community is small but active! If you ever have difficulty finding some information, you can tweet your question to the official @eleven_ty account. Eleventy’s creator, Zach Leatherman, is quick to answer or RT questions to help get you back on your way!

Articles on Smashing Magazine — For Web Designers And Developers


Deprecated: Function create_function() is deprecated in /home2/thebrand/public_html/wp-content/plugins/wp-spamshield/wp-spamshield.php on line 1884
24 Mar

A Deep Dive Into Eleventy Static Site Generator

by TBSCategories: News

But first — let’s quickly review what is meant by a “static site” and then what a generator provides. A static site is composed of static content — as in, the HTML, CSS, assets, and all content are already compiled together before pushing to a website host. This is different from a dynamic site that compiles those things from querying a database at run time (like WordPress) or that pulls content from APIs client-side (like JavaScript frameworks without server-side rendering).

A static site generator is an environment and build processor to compile your content into static HTML. They usually offer helpers to provide flexibility in writing your content (like supporting Markdown) and include methods for templating. So instead of writing HTML pages one by one and having to copy and paste the repeated parts, a generator will support breaking those things into components via a certain templating language. Then the generator’s build process will bring everything together and output the final HTML that can be uploaded to a web host to be served as your website. Depending on the web host you use, this build process can even be done by the host.

There are many static site generators available. You may have heard of or even used ones like Jekyll, Hugo, Gatsby, Next and Nuxt. A comprehensive list is provided by Jamstack.org.

What Makes Eleventy Different From Other Static Site Generators?

Eleventy is exceptionally fast both during builds and in the browser. This is largely thanks to not requiring the loading of a client-side JavaScript bundle in order to serve content (compared to something like Gatsby). Server-side rendering isn’t even a concern here, since the filesystem page creation defaults to static HTML.

What really makes Eleventy unique is the ability to select from and intermix up to ten different templating languages:

Intermixing languages can happen in the same file, or between layouts. For example, I often write my main content with Markdown that feeds into a Nunjucks layout. In some projects, I’ve found it useful to be able to loop over some data using Nunjucks while in the Markdown file. This ability to combine languages is very powerful, and allows you to design a write-and-build workflow that works best for you and your project.

Eleventy includes a --serve flag that uses BrowserSync to enable serving the site locally and with hot-reload upon file changes. This is a great convenience, and is good to keep in mind if you’re not looking for a static site generator but perhaps an upgrade from build tools like Gulp.

As part of being zero-config, all your site files could live in the root of your project. To alter the input and output directories, you can create an Eleventy config, which is expected to be a root file called .eleventy.js. Here’s a quick snippet showing how to make this modification:

module.exports = function (eleventyConfig) {   return {     dir: {       // default: [site root]       input: "src",       // default: _site       output: "public",     },   }; };

As noted earlier, the default behavior is filesystem page creation which is generally of great benefit especially for rapidly getting started. This is easily overrideable by assigning a custom permalink and that can be done per file, for an entire directory, or dynamically for a set of data. Permalinks also offer another superpower which we’ll explore in a bit!

Uniquely, during the build, you can prepare content, data, and transforms on that content and data by using JavaScript and leveraging filters and shortcodes (we’ll talk about those later). Again, this all happens without adding a JavaScript bundle client-side, while still enabling the use of JavaScript as a templating language.

Important Note: You can successfully use Eleventy with no or low JavaScript knowledge.

Unlike other SSGs like Gatsby, or environments like WordPress, most Eleventy sites do not require any plugins. There are some plugins available, but they are not necessary for essential functionality.

When building with Eleventy, you can add on features as you need them. In fact, you could just use HTML and never work with any of the other templating languages. Eleventy is only as complex as your project requires!

Understanding Essential Eleventy Concepts

Let’s go over a few bits of terminology and concepts that will help you be successful in creating your Eleventy projects.

Layouts And Templates

You may think of these terms as interchangeable, but in Eleventy’s context, they do have contextual meanings:

  • Template is the generic term for all content files.
  • Layouts are special templates that wrap other content.

For example, template refers to all your Markdown files, whereas a layout might be a Nunjucks file that contains the HTML5 boilerplate and a slot for the template content. We’ll learn how to make this work in the section on getting started.

Filters And Shortcodes

These are additional ways to modify content output, and create reusable template parts. They are available for use with Nunjucks, Liquid, Handlebars, and JavaScript templating. Filters and shortcodes are defined within .eleventy.js.

Beyond variables and operators available in your templating language of choice, Eleventy has unified the concept of filters across the previously listed languages. Filters transform content in some way specific to the content type. For example, you may create a filter intended for strings to uppercase them. Or you might have a filter intended to be used on arrays to alter what is returned, like picking a random item. Some filters are provided by Eleventy, a few of which we’ll use in the getting started tutorial.

Shortcodes allow creating reusable template parts and are able to accept arguments. They can be either standalone or paired, meaning they wrap content with a start and end tag.

One of my favorite shortcodes is to render the current year — meaning no more out of date copyright years in your footer! Here’s how to create a year shortcode:

eleventyConfig.addShortcode("year", () => $  {new Date().getFullYear()});

To use it in a Nunjucks or Liquid template looks like this: {% year %}.

You can review the Eleventy docs for examples of paired shortcodes.

Collections

Collections are groups of related content, and are typically created within frontmatter by defining tags. Tag syntax options include single strings, single-line arrays — ["tagA", "tagB"] — for multiples, or YAML-style lists to assign multiple tags. For example, I can create a “pages” collection by adding the following frontmatter to all content I want to be included in that collection:

--- tags: pages ---

Once you have defined a collection, you can access it via your templating language of choice within the global collections object. To access our “pages” collection would look like collections.pages. This returns an array of that collection’s data, and so you can perform array operations like looping over it such as to produce a list of links or article teaser cards. You can even suppress normal file output and use only collections to manage data display, which is useful for managing single-page site content.

Custom Data

So far we’ve talked about creating content as files, but Eleventy also makes it very easy to maintain different data sources. This is called “custom data” and lives as JavaScript module exports or JSON files in the _data directory.

Custom data can be used to:

  • Define a basic JSON array.
  • Return the results of a fetch operation.
  • Retrieve and re-format content from a headless CMS.

Eleventy makes all data from within _data available under a variable matching the filename. For example, if I create posts.json then I can access that in my templates as posts. Using Nunjucks, here’s an example of looping over the posts data:

{% for post in posts %}   {{ post.title }} {% endfor %}

Pagination And Creating Pages From Data

In Eleventy terms, pagination refers to iterating over a data set and defining a template for the output of that data “chunk”. This is done with a dedicated file that defines the pagination within frontmatter. The file also includes setting up your intended output for the data, meaning it becomes its own template as well. We can define a layout to send the content to and also add tags to create a collection for ease of reference and flexibility for the output.

Note: If you use custom data to retrieve content from a CMS, then pagination is the Eleventy method you’re looking for to turn that data into pages dynamically.

Here’s an example of referencing our posts custom data which we’ll assume we’re retrieving via a fetch from a headless CMS. Importantly, the size is set to 1, which means each “pagination chunk” should produce one single page of output. We then use the alias to create a reference to the current item in the pagination loop, and then use that reference in the permalink definition and the template body.

The file that defines the pagination can live wherever you’d like within your input directory. My organizational preference is to create a generate directory, and then name it the same as the collection it will be creating. Consider the following to be src/generate/posts.njk:

--- pagination:   data: posts   size: 1   alias: post   addAllPagesToCollections: true permalink: "/{{ post.title | slug }}/" tags: posts layout: post templateEngineOverride: njk, md --- {{ post.body | safe }}

In this case, the permalink is assigning the page to be output directly off of the site root. You could change this to add a prefix such as /posts/{{ post.title | slug }}, for example.

Additionally, if you want all of the generated pages to be available in the collection created by the tags, you must set addAllPagesToCollections to true to include more than the first item.

Lastly, if your content is coming in as Markdown instead of pre-compiled HTML, you’ll need to use the templateEngineOverride. In the example snippet, I’ve set it to njk, md which means the template content will need to be processed both as Nunjucks in order to convert the variable, and then Markdown to compile the contents returned in the variable.

If you’re wondering what safe means, we’re going to learn that next!

How To Get Started With Eleventy

Alright, so you’re ready to get going with your first Eleventy project! This brief tutorial will help you get a starting structure in place to continue building from. We’ll use the concepts we’ve already learned about and add a few new ideas, too.

The first important note here is that Eleventy is a scoped package, so here’s the install command:

npm install @11ty/eleventy

Next, a handy convenience I like to do is add the following scripts into my package.json:

"scripts": {   "start": "eleventy --serve",   "build": "eleventy" }

As mentioned previously, the --serve flag will enable a local server via BrowserSync.

My preference is to update the input/output directories as we already looked at, so now it’s time to create some content within src or the input directory of your choosing.

In order to prepare our project to be more flexible and scalable from the start, I would suggest creating at least one layout that contains the HTML5 boilerplate. Layouts need to be defined within a directly called _includes, which is one of a handful of expected directories.

A convention that you’ll often find among starters is to call this layout base. I have a preference for making it a Nunjucks file.

Here’s a sample base.njk:

<!DOCTYPE html> <html lang="en"> <head>   <meta charset="UTF-8">   <meta name="viewport" content="width=device-width, initial-scale=1.0">   <title>{{ title }}</title> </head> <body>   <header>     <h1>{{ title }}</h1>   </header>   <main>     {{ content | safe }}   </main> </body> </html>

The double curly braces are Nunjucks syntax for variables. Here, we’ve prepared for an incoming title variable that will shortly be supplied via front matter. The content variable is provided by Eleventy and marks the slot where all incoming non-front matter content should go. Importantly, this is used in conjunction with the provided safe filter which prevents compiled HTML from being escaped versus rendered.

Now it’s time to create our site index, which we’ll add as index.md:

--- title: Hello Smashing Readers! layout: base.njk ---  Thanks for reading — hope you’re excited to try Eleventy!

Notice that in the front matter we added our title, and also defined the layout.

At this point, we can run our project with the script we added: npm start. This will trigger BrowserSync to setup localhost:8080 (if it’s available) but you will need to manually open it in the browser. Check out this quick tip if you’d like it to open the browser automatically.

The last critical step is to add a stylesheet. Currently, CSS isn’t recognized as an automatically included filetype so we’ll have one extra config step after we create our stylesheet.

You can add a CSS file wherever you’d like in your input directory, such as css/style.css. Then, open .eleventy.js (or create it in the project root if you didn’t do the input/output customization) and add the following :

module.exports = function (eleventyConfig) {   eleventyConfig.addPassthroughCopy("./src/css/");   eleventyConfig.addWatchTarget("./src/css/");    // - input/output customization if using - };

First, we add the css directory as a “passthrough copy” which means Eleventy should include it in the push to the output directory. Then we also add it as a “watch target” so that as we make changes to our styles while running our start command, Eleventy will trigger a rebuild to update our local site.

Lastly, we need to remember to add the link to our stylesheet within our base layout:

<link rel="stylesheet" href="{{ '/css/style.css' | url }}" />

When we define the stylesheet’s location, we pass it through Eleventy’s url filter which will adjust the relative file path as needed upon build.

Next, let’s create a “pages” post type to explore using collections and layouts a bit more. To do this, add the directory of pages and create one or two Markdown files, including a title front-matter key but not a layout.

We’re going to use a slightly different method to define the layout this time — a data directory file. This file is generally formatted as JSON and enables us to add data that should be applied to all files within a directory, which prevents having to duplicate it across files. The file needs to be named the same as the directory it will be used for, so create the file pages.json and add the following content:

{   "layout": "page.njk",   "tags": "pages" }

We’ve also gone ahead and defined tags in order to create the “pages” collection. But the layout we defined doesn’t actually exist yet, so create _includes/page.njk and add the following:

--- layout: base.njk ---  <article>   {{ content | safe }} </article>

Here we’re using the Eleventy concept of layout chaining to be able to re-use our base template but also add a unique element for our page layout, which is the <article>. This means that all of the content of our pages will use both the page layout and base layouts.

Layout chaining reduces duplication by allowing re-use of boilerplates and base site layout structures.

Now that we’ve created content for the pages content type and defined it as the “pages” collection via the tags, let’s see how we can access that collection. Here, we’ll use Nunjucks to loop over the collection and output a list of links to each page. This loop will be added within our index.md file.

{% for post in collections.post -%} - [{{ post.data.title }}]({{ post.url }}) {% endfor %}

We’ve done something unique though which is that the inside of the loop actually switches back to Markdown to render the links. This is not a required way to handle this scenario, but it can be very handy! Sometimes, depending on complexity, this may not work. The real reason is that the Markdown renderer defaults to Liquid templating language, so if you’re using Nunjucks features beyond basic loops, you will have to let Eleventy know how to process the file.

In the earlier section on pagination, we actually already looked at the solution for this. And that is to make use of the templateEngineOverride to indicate that the file should be processed as both Nunjucks and Markdown. The following full solution should be placed in the template’s front matter: templateEngineOverride: njk, md.

At this point, you’ve created a basic multi-page site! If you have need of using external data, jump back up to the section on pagination.

Other Ways To Start An Eleventy Project

Whereas some other static site generators and environments like WordPress have the concept of “themes”, Eleventy uses the term “starter”. There is a growing collection to choose from, and many can be found in the listing within the Eleventy docs.

My preference is to use Sass with my Eleventy projects, and I have a Sass starter available if you’d like to see how to add that into your build process. Others may choose to add in Gulp if they are used to that build pipeline for assets and processing.

I’ve also created a minimal starter that includes the features discussed in this article and shares similarities with the tutorial result. It also has a small example of fetching external data, and shows how to add in a partial to display site navigation based on a collection.

Expanding On The Basics

Once you’ve experimented with creating your first site with some basic content and maybe some custom data, it’s helpful to know additional ways to work with that content. Here is a brief overview of some other concepts to be aware of.

Altering File Output Type With Permalinks

I mentioned earlier that permalinks have a superpower. And that is that you can use them to output non-HTML file types.

Two useful examples are creating an RSS feed and a sitemap, both of which happen to typically be XML files. What’s really powerful is that you can continue to use the templating language of your choice to help generate those files, so you can loop over page data with Nunjucks to keep your RSS feed fresh, for example.

Customizing Collections

Sometimes using tags to create collections may not be sufficient. Or, you may want to create filtered variations of an existing collection. We can alter or create collections by using a series of provided functions. These will live in the .eleventy.js config file.

In this example, we’re using the addCollection function to filter items in an existing collection. The new collection will be based on the existence of customKey within front matter. This key is returned off of the data object which is attached to all generated Eleventy content.

eleventyConfig.addCollection("specialCollection", function (collection) {   return collection.getAll().filter((post) => post.data.customKey); });

You can review other ways to create, modify, and use collections in the Eleventy docs.

Working With The Data Cascade

Eleventy has a more full concept of how data is compiled for a template called the data cascade which we only just began exploring in this guide. You will get the most out of Eleventy if you review how that works, starting in the docs. Ben Myers also has an excellent guide to understanding the data cascade.

Recommended Eleventy Plugins

In the intro, I briefly mentioned there were plugins available, but that they aren’t always needed. However, there are a few I tend to use on most projects, which include:

  • @11ty/eleventy-plugin-rss If you would like to have an RSS feed, this official plugin provides some filters to help you to generate the feed. The linked repo includes a sample feed, which you may also find in use within some starters.
  • @11ty/eleventy-plugin-syntaxhighlight Instead of loading Prism as a script for code highlighting, this plugin allows that processing to be applied as part of the Eleventy build process. This means code blocks are transformed to include the classes for applying a Prism theme ahead of time, so you will only need to add a Prism CSS theme of your choice.
  • @11tyrocks/eleventy-plugin-social-images A feature I sought out early in my Eleventy exploration was the ability to generate social media share images. This led me to create a plugin that uses Puppeteer behind the scenes to take the snapshot. The plugin comes with prebuilt templates as well as config options to define your own template file.

I would also recommend becoming familiar with the rest of the official Eleventy plugins as they address other common needs including navigation and image handling.

Deciding If Eleventy Is Right For Your Project

Eleventy, like most static sites, is best for content that doesn’t typically need to be served dynamically or on-demand. This is not to say all of the site has to be static, or that there are not ways to make content dynamic. You may still load JavaScript to enable dynamic content like fetching from APIs or creating interactive widgets. You can also use services like IFTTT or Zapier to facilitate rebuilding your site if your host supports build webhooks and you have parts that you want to refresh on a schedule.

Thanks to custom data and pagination, we saw it was easy to include external data as from a headless CMS or any other API. So although it will be served statically, you still have a lot of flexibility in where you pull content and how you manage it.

My favorite thing about Eleventy is that it doesn’t impose many opinions on how I should structure my site, beyond the few expected directories we talked about for _includes and _data (and you can update the naming convention of those, too). This can also be helpful if you are looking to migrate a site and being able to potentially move some existing file structure as well. However, if you prefer a more opinionated architecture, you might seek a different option.

I also enjoy how I can mold Eleventy to fit my mental model for a given project by leveraging multiple templating languages as well as filters, shortcodes, and layouts. Starters also help give a boost so that you can focus on what’s really important: your content. And the high performance of purely static output is also a great benefit.

If you do need a bit more in your build process, you can add other familiar tools like Webpack, Gulp, or Parcel. You may be able to find a starter that already includes those things. Keep in mind you can also leverage Node scripts which are already inherent to the Eleventy build process.

Eleventy is very capable of handling large amounts of page generation. It has been used for some large and complex sites such as Google’s web.dev and Netlify’s marketing site. I’ve also used Eleventy for some unconventional purposes, like email and web component generators, along with some others which are described in this overview.

Additional Resources

I hope this guide has both peaked your interest and prepared you to begin using Eleventy! It included a lot of points that I found a bit tricky to uncover when I was creating my first project with it. Since I first found Eleventy in April 2020, I’ve built over 20 Eleventy projects counting starters, plugins, side projects, and course materials. Many of those can be found on my site 11ty.Rocks which also has tutorials and tips. Eleventy is something I really enjoy discussing, so feel free to reach out on Twitter!

The following are more resources for helping you on your journey to learn and get the most out of Eleventy:

Finally, I want to note that the Eleventy community is small but active! If you ever have difficulty finding some information, you can tweet your question to the official @eleven_ty account. Eleventy’s creator, Zach Leatherman, is quick to answer or RT questions to help get you back on your way!

Articles on Smashing Magazine — For Web Designers And Developers

Newer postsOlder posts
×

Powered by WhatsApp Chat

WhatsApp Chat is free, download and try it now here!

× Chat with Us