DEV Community: Gary Byrne

Introduction to ARIA Live Regions

Gary Byrne — Thu, 25 Feb 2021 14:04:07 +0000

In this article, we will look at ARIA live regions and how they can be used to expose information to assistive technologies.

What are ARIA live regions?

According to the W3C:

Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere.

In applications where content can update dynamically, users of assistive technologies may need to be updated about changes in those live regions. When we think of POUR we want our content to be perceivable. It is important that we ensure our webpage content can be identified even when it changes.

These changes in content can come from various sources. It could be the result of an API call to a third party that returned some data, a chat message appearing on screen, some user interaction, some AJAX update and much more.

The MDN docs state that:

Dynamic content which updates without a page reload is generally either a region or a widget. Simple content changes which are not interactive should be marked as live regions. WAI-ARIA provides us with a list of live region roles and attributes that allows us as authors to mark content as live regions.

Live region attributes

ARIA live region attributes provide a way for us as authors to mark any element as a live region. By doing so, assistive technologies such as screen readers will announce dynamic changes to their content even when we no longer have focus on them.

aria-live

This is an extremely important aria attribute.
By using the aria-live attribute on an element, we are marking it as a live region.

This attribute takes a priority setting as its value which tells the screen reader how it should announce changes to updated content. The value it takes for its priority setting can be one of the following:

off (default)

This is the default value for every element and is the same as if the attribute was omitted entirely. Users will not be notified of changes to any elements content and the element will not be marked as a live region. The only reason you should set this value is if you want to overwrite the aria-live value provided by an ARIA role.

<div aria-live="off">
//not a live region
</div>
// is the same as 
<div></div>

polite

The polite value will mark the element as a live region and will ask the screen reader to announce changes to its content. However, it will not immediately announce it as it will wait until the screen reader is idle and no more announcements are taking place before doing so.

<div aria-live="polite">
//live region content
</div>

assertive

The assertive value will mark the element as a live region and will announce the updated changes immediately as they happen and force the screen reader to stop its current operation. This will disrupt the current announcement of the screen reader and may very annoying for some users.

<div aria-live="assertive">
//live region content
</div>

It is noted on the MDN docs that

the assertive value should only be used for time-sensitive/critical notifications that absolutely require the user's immediate attention.

aria-relevant

We can tell assistive technologies that only certain content is relevant to be announced on updates. We can do this by using the aria-relevant attribute. This attribute can take any number of the following four values:

additions

The addition of nodes within the live region is relevant.

<div aria-live="polite" aria-relevant="additions">
    // live region content.
   // only node additions are relevant
</div>

removals

The removal of nodes within the live region is relevant.

<div aria-live="polite" aria-relevant="removals">
    // live region content.
   // only node removals are relevant
</div>

text

Changes to the text content of existing nodes within the live region are relevant.

<div aria-live="assertive" aria-relevant="text">
    // live region content.
   // only text changes are relevant
</div>

all

This is the same as using additions removals text

<div aria-live="polite" aria-relevant="all">
    // live region content.
    // all changes are relevant
</div>
// is the same as 
<div aria-live="polite" aria-relevant="additions removals text">
    // live region content.
    // all changes are relevant
</div>

Note: When content is irrelevant, then it will not be announced by the screen reader which is the same as if we applied aria-live directly on that element.

The default value for this attribute is additions text.

<div aria-live="polite" aria-relevant="additions text">
    // live region content.
</div>

The W3C have stated:

when the aria-relevant attribute is not provided, the default value, additions text, indicates that text modifications and node additions are relevant, but those node removals are irrelevant. aria-relevant values of removals or all are to be used sparingly. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as a buddy leaving a chat room.

aria-atomic

When we have a live region and we know what content is relevant, the screen reader will announce what content has been updated. In some cases we want it to announce the entire live region even if it only has a small section of content that actually changed. This attribute takes a boolean (true or false). The default value for the aria-atomic attribute is false which means the screen reader only announces the updated content and not the content of the entire live region. In a lot of cases, this is perfectly fine but sometimes we may need aria-atomic to be set to true in order for us to get more context about the updated content.

Example

The following is an example using aria-live, aria-relevant and aria-atomic. See the MDN docs for more examples.

<p aria-live="polite">
    The Quiz leader is Gary Byrne with a score of <span id="score">70</span> points.
</p>

This element has an aria-atomic value of false by default. If we try to update the score from 70 to 80 points then the screen reader only announces the change to a score of 80. The screen reader user may be confused as the announcement will not include the person's name.

<p aria-live="polite" aria-atomic="true">
    The Quiz leader is Gary Byrne with a score of <span id="score">70</span> points.
</p>

Now that aria-atomic is set to true it will announce The Quiz leader is Gary Byrne with a score of 80 points whenever the score updates

aria-busy

The last attribute I want to talk about is aria-busy. If an element has a tonne of updates/modifications, we can use this attribute to tell the screen reader to pause live region announcements until these updates are completed. By default, the value for aria-busy is false which means it will try to announce every single update.

When aria-busy is true for an element, assistive technologies MAY ignore changes to content owned by that element and then process all changes made during the busy period as a single, atomic update when aria-busy becomes false - Digital A11Y

Live region roles

Live region roles are essentially ARIA roles that create live regions and can be changes by the above live region attributes. You can read more about these roles on the W3 docs.

Role	Implicit aria-live	Implicit aria-atomic
alert	assertive	true
status	polite	true
marquee	off
log	polite
timer	off

Wrapping Up

If you enjoyed this blog and would like to see similar content in the future, or would like to get in touch then please follow me on Dev.to, Twitter and Hashnode.

Thank you for reading.

Understanding ARIA Landmarks - General Principles and Roles

Gary Byrne — Mon, 15 Feb 2021 11:48:16 +0000

ARIA landmarks are a set of ARIA roles that are provided to our HTML elements in order for us to identify the structure of a web page. When we visit a webpage, we get a sense of its visual structure from the beginning but this structure should also be present in our markup.

We should use ARIA landmarks for a number of reasons:

We are getting semantic markup that represents our visual structure. Perceivable content should have a semantically meaningful landmark.
Keyboard navigation is supported for screen reader users. Screen reader users can navigate the web page based on its page structure.
We can create skip links that can enhance keyboard navigation for both screen reader users and sighted users.

ARIA General Principles

The World Wide Web Consortium (W3C) has provided us with some ARIA landmarks general principles.

1: Identify the logical structure of a web page

What this means is that we should really think about the structure of our web page. We should break our page into perceivable areas. We can also break our page into further sub-areas if needed.

2: Assign landmark roles to each area

We should assign landmark roles to each area of our web page. Roles such as banner, main, complementary and contentinfo should be top/root level landmarks.

3: Label each area

This principle is very important especially for users who are using assistive technologies.

If a webpage has multiple landmarks in its markup, then the label for each landmark should be unique.

An example of this is when we have multiple navigation landmarks. We could have primary and secondary navigations on our webpage. So we should give each a unique label. The first navigation should have an aria-label attribute with a value of primary. The secondary navigation should have an aria label of secondary or whatever makes sense in that context.

If a landmark area begins with a heading level element then we can provide an aria-labelledby attribute to that area.
Screen readers announce the type of landmark we are currently visiting. Therefore we can omit the landmark from any labels provided to the element.

An example of this can be seen above when we use Primary instead of Primary Navigation in the label. If we kept Primary Navigation then the screen reader would announce Primary Navigation Navigation which may be confusing for the user.

Here is some examples of these types of labels:

<nav role="navigation" aria-label="primary">
   // code here
</nav>
<nav role="navigation" aria-label="secondary">
   // code here
</nav>
<aside role="complementary" aria-labelledby="notice">
 <h2 id="notice">Site Notice</h2>
</side>

A list of ARIA landmarks

Top-level landmarks

Top-level landmarks stand for landmarks that are not contained within any other landmarks. For each of these landmarks, the ARIA landmark design principles are worth reading.

banner - this represents site-oriented content such as a logo or site search. This role should appear at the start of each web page.
contentinfo - this is to represent the footer of a webpage.
main - this is to represent the primary content of a webpage.
complementary - represents the supporting content of a web page.

Other landmarks

navigation
region
form
application
search

You can read about all of these ARIA landmarks on the W3 website.

HTML sectioning elements

Before HTML5 was introduced, we would have had to apply these ARIA landmarks to elements like divs in order for us to convey the structure of the webpage in our markup.

For example, a header section might look like the following:

<div role="banner" id="header">
  // site-oriented content goes here
</div>

HTML5 introduced some new sectioning elements that provide ARIA landmarks by default.

Element	Default Landmark Role	case
main	`main`	always
nav	`navigation`	always
aside	`complementary`	always
header	`banner`	only when top level element *
footer	`contentinfo`	only when top level element *

The footer element no longer has the contentinfo role and the header element no longer has the banner role when they are descendants of section, main, nav, aside or article elements.

The section element has the role of region and the form element has the role of form only when they have an accessible label by using the aria-label, aria-labelledby or title attribute. Some of these labeling methods were mentioned above.

Let's see this in action.

If we visit the homepage of the CSS Tricks website and open up our browser developer tools and navigate to its elements panel. Press Cmd + Option + C (Mac) or Ctrl + Shift + C (Windows, Linux, Chrome OS) to open it up.

This is what you should see:

Now, we can see a few elements in the elements panel. If we inspect the page we can see some sectioning elements such as header, main, section, and footer. If we inspect the header, we can't see anything about its role without viewing its accessibility information.

To do this, we need to visit the accessibility panel for that element. This will be on the bottom menu where we have our styles.

The menu will look something like this:

Click on the Accessibility tab. Do you notice anything about its role?

We can see that by default it is given the role of banner. This is because the header element has a role of banner provided already by this element when it's in the context of the body element.

Wrapping Up

At the time of writing, Internet Explorer (IE) 11, 10, and 9 support all sectioning elements except the main element which only has partial support for sectioning elements. Support on other browsers is relatively good but it's best to refer to the caniuse website for more information.

Landmarks are supported by most major screen readers and Scott O'Hara wrote a really great article about Accessible Landmarks.

For all elements, if you need to support IE version 8 or below then you will need to style each element as a block level element and use some JavaScript to create the element if it is not supported.

Depending on your browser support requirements, it is suggested to manually test the browsers you support and use various screen readers in each test.

If you enjoyed this blog and would like to see similar content in the future, or would like to get in touch then please follow me on Dev.to, Twitter and Hashnode.

Creating a GraphQL Content Hub with Apollo Server

Gary Byrne — Sat, 13 Feb 2021 15:24:13 +0000

Creating a GraphQL Content Hub with Apollo Server and Deploying to Netlify

In this tutorial, I am going to be showing you how to create a very simple version of a GraphQL content hub using Apollo Server. We will be deploying this content hub to Netlify as a serverless function.

Now that we know what we are making, let's jump right in.

What is Apollo Server

Apollo Server is a really cool open-source GraphQL server that works which pretty much any GraphQL client out there. In this article, we will be setting up an Apollo Server which runs a GraphQl playground and we will have it hosted on Netlify.

What is a GraphQL Playground?

This is essentially a browser-based IDE created by Prisma. It makes it easy for us to interact with our data sources and query them all within the browser. Apollo has an entire section on the playground here which is worth checking out.

The GraphQL playground looks like this:

What exactly are we building?

We are building an Apollo GraphQL Server which acts as a content hub serving data from various different sources. These sources can be anything from local data, third party APIs, or even a database. In the case of this tutorial, we will be pulling in data from local JSON, two third-party GraphQL APIs, and a third-party REST API.

The data sources used in this project are:

A books.json file stored in the codebase
The Rick and Morty GraphQL API
OMDB Rest API
Trevorblades Countries GraphQL API

Getting started

Project setup

Setting up a GraphQL API might sound more daunting than it actually is. Let's create our API step by step.

Dependencies needed

apollo-server-lambda
graphql
netlify-lambda (dev dependency)

Project structure

Clone this repo to get started quickly.

git clone https://github.com/garyb1/netlify-apollo-server-starter
cd netlify-apollo-server-starter

Then install project dependencies.

npm install

Things to note:

Inside src we have a lambda directory. This is our folder for our serverless functions. We have a serverless function called graphql that will run our Apollo Server.

We have a netlify.toml file with the following:

[build]
  command = "npm run build"
  functions = "built-lambda"

When we are building our application run the command npm run build. netlify-lambda builds to the built lambda folder at the root of our project and Netlify reads functions from here. So when we run a build our graphql.js serverless function will be placed in /built-lambda.

Setting up our schema and resolvers

In our project template, you will see two files inside src. These are schema.js and resolvers.js. In some real-world examples, you will see the schema and resolvers in the same file as your server. For this example, I decided to extract them to make them easier to read.

src/schema.js

The first type in our schema will be Book which will represent a single book.

A schema is a collection of type definitions (hence "typeDefs") that together define the "shape" of queries that are executed against your data.

Our Book type looks like this:

  # This "Book" type defines the queryable fields for every book in our data source.
  type Book {
    title: String
    author: String
  }

This created a queryable field called Book which has a title and an author which are both strings. Now we add this Book type to the Query type. This type is used to identify all of the available queries that GraphQL clients can execute.

In typeDefs you will see the following:

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "books" query returns an array of zero or more Books (defined above).
  type Query {
    books: [Book]
    book(title: String!): Book,
  }

We added a books query which returns an array of zero or more Books. We also added a single book query that takes a title and returns a single Book.

FYI:
The ! in our type means the type is non-nullable.

We have data for our books in src/data/books.js but Apollo Server doesn't know anything about that data. We need to tell Apollo Server whenever it's executing a query for books to use that data. This is the role of resolvers. Let's look at our resolver for books. We can also add a resolver for a single book by searching for its title.

Our resolver looks like the following:

export const resolvers = {
  Query: {
    books: () => books,
    book: (parent, { title }) => books.find((book) => title === book.title)
  },
};

Running the server

In our src/lambda/graphql.js you will see the following:

// The ApolloServer constructor requires two parameters: your schema
// definition and your set of resolvers.
const server = new ApolloServer({ typeDefs, resolvers });

exports.handler = server.createHandler();

We are creating an instance of an apollo server and passing it our schema definition and our set of resolvers. Finally, pay close attention to the last line. This creates an export named handler with a Lambda function handler. This is used for executing as our serverless function. Netlify functions are built with AWS Lambda under the hood.

In your terminal, we can now run our GraphQL server.

npm start

npm start will run NODE_ENV=development npm run start:lambda from our package.json scripts.

As per apollo-server docs:

The GraphQL Playground will only run if your NODE_ENV is set to development. If you don't pass this, or your NODE_ENV is set to production, you will not see the GraphQL Playground.

You should see Lambda server is listening on 9000.

Open localhost:9000/graphql to see our GraphQL playground.

Type the following query into the playground to get back some books.

# Write your query or mutation here
query {
  books {
    title
    author
  }
}

This should give you back

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      }
    ]
  }
}

See the screenshot below of the playground to compare with yours.

We can also query for a specific book. Let's search for a book by its title.

# Write your query or mutation here
query {
  book(title: "City of Glass") {
    title
    author
  }
}

This will return the following data:

{
  "data": {
    "book": {
      "title": "City of Glass",
      "author": "Paul Auster"
    }
  }
}

Getting countries data

We will be getting the country's data from this GraphQL API.

Create a file called countries.js and place it in the data directory.

touch src/data/countries.js

Next, we need to install the isomorphic-fetch package so we can use fetch API to query the countries API.

npm install isomorphic-fetch

Next, let's create a function that will query the countries API for every country including their name, country code, and capital. The query will look something like this:

    query {
      countries {
        name
        code
        capital
      }
    }

Paste the following code into src/data/countries.js

import fetch from 'isomorphic-fetch;

export const getCountries = async () => {
  const url = 'https://countries.trevorblades.com/';

  const query = `
    query {
      countries {
        name
        code
        capital
      }
    }
  `;

  const opts = {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query }),
  };

  const response = await fetch(url, opts);
  return response.json();
};

This will create a POST request to the countries API for the information we need. We take the response which returns a promise.

Why do we return response.json()?

We need to parse the response as JSON. You can read more about it on MDN.

One thing you may have noticed is that this query will only work to get all countries.

What if we want a single country? Let's refactor this function to filter by a country code if it is supplied.

Change the query

export const getCountries = async (code) => {
  const url = 'https://countries.trevorblades.com/';
  let query;
  if (code) {
    query = `
      query {
        countries(filter: { code: { eq: "${code}" } }) {
          name
          code
          capital
        }
      }
    `
  } else { 
    query = `query {
      countries {
        name
        code
        capital
      }
    }`; 
  }

// rest of the code here

Creating country types and resolvers

In src/schema.js let us add our Country type:

# This "Country" type defines the queryable fields for every country from the countries.trevorblades.com/ api
  type Country {
    code: String
    name: String
    capital: String
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "books" query returns an array of zero or more Books (defined above).
  type Query {
    books: [Book],
    book(title: String!): Book,
    countries(code: String): [Country]
  }

In src/resolvers.js let's add our resolver for countries.

    countries: async (parent, { code }) => {
      const { data: { countries } } = await getCountries(code);
      return [...countries.slice(0, 10)];
    },

We have created an asynchronous function that takes the country code. We await the response of the getCountries function from src/data/countries.js which is used to query the countries API. If the country code does not exist, it will query all of the countries. For this example, we return just the first 10 results.

Querying our data

Let's restart our node server by running npm start and go back to our playground on port 9000.

Copy in the following query to search for all of the countries available:

query {
  countries {
    code
    name
    capital
  }
}

This should return 10 countries from our resolver.

Let's search for United Arab Emirates:

query {
  countries(code: "AE") {
    code
    name
    capital
  }
}

You should see the following country returned:

{
  "data": {
    "countries": [
      {
        "code": "AE",
        "name": "United Arab Emirates",
        "capital": "Abu Dhabi"
      }
    ]
  }
}

Querying the Rick and Morty GraphQL API

We could use the same approach with isomorphic-fetch. However, I am going to show you another way to query this API. This example shows how to query a third-party GraphQL API with the request function from Prisma's graphql-request library.


import { request } from 'graphql-request';

export const getCharacters = async () => {
  const url = 'https://rickandmortyapi.com/graphql';
  const query = `
    query {
        characters {
            results {
                name
                id
            }
        }
    }
  `;

  const response = await request(url, query);
  return response;
};

Adding our character type and resolver

In src/schema.js:


  # This "Character" type defines the queryable fields for every character from the Rick and Morty API
  type Character {
    name: String
    id: String
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "books" query returns an array of zero or more Books (defined above).

  type Query {
    books: [Book],
    book(title: String!): Book,
    countries(code: String): [Country],
    characters: [Character]
  }

QUIZ

Test your skills now by querying for an individual character following similar steps from the countries example.

In src/resolvers.js, let's add our resolver for characters.

   characters: async () => {
      const { characters: { results } } = await getCharacters();
      return results;
    }

Querying for a Rick and Morty character

Open up your GraphQL playground on localhost:9000/graphql.

Paste in the following query:

query {
  characters {
    name
    id
  }
}

This will return an array of characters from the Rick and Morty GraphQL API.

Getting our OMDB movies

This OMBD API is a REST API. We could use isomorphic-fetch or another library like axios.
Instead, we are going to use the apollo-datasource-rest library. This was recommended by Eve Porcello on moonhighway.com.

To help developers make use of data from REST APIs, Apollo created REST Data Sources as a way to encapsulate data fetching. You might choose this utility over fetch because the package will help you with caching, deduplication, and error handling.

To get started with this, create the following file:

touch src/data/omdb.js

Paste in the following code:

/*
  This example shows how to query the OMDB API using the apollo data source package
*/

import { RESTDataSource } from 'apollo-datasource-rest';

export class MoviesAPI extends RESTDataSource {
  constructor() {
    super();
    this.baseURL = 'http://www.omdbapi.com';
  }

  async getMovie(name) {
    const response = await this.get(`/?${name ? (`t=${name}`) : 'i=tt3896198'}&apikey=${process.env.OMDB_API_KEY}`);
    return response;
  }
}

This essentially just created a MoviesAPI class that has an async method getMovie that will query the API and will change the query parameters if it's searching for a specific movie. If we don't supply a name we will get a random movie.

Note that I have my OMDB API store to my .env file. You will need to sign up to get a free API key. Read this post to understand more about using environment variables. These will serve useful as we deploy to Netlify and keep our API keys safe.

Adding our type and resolver for movie

Our src/schema.js should now look like the following:

/* eslint-disable import/prefer-default-export */
import { gql } from 'apollo-server-lambda';

// # A schema is a collection of type definitions (hence "typeDefs")
// # that together define the "shape" of queries that are executed against
// # your data.

export const typeDefs = gql`
  # Comments in GraphQL strings (such as this one) start with the hash (#) symbol.

  # This "Book" type defines the queryable fields for every book in our data source.
  type Book {
    title: String
    author: String
  }

  # This "Country" type defines the queryable fields for every country from the countries.trevorblades.com/ API
  type Country {
    code: String
    name: String
    capital: String
  }

  # This "Character" type defines the queryable fields for every character from the rick and morty api
  type Character {
    name: String
    id: String
  }

  # This "Movie" type defines the queryable fields for a given movie from the OMDB API
  type Movie {
    Title: String
    Year: String
    Rated: String
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "books" query returns an array of zero or more Books (defined above).
  type Query {
    books: [Book],
    book(title: String!): Book,
    countries(code: String): [Country],
    characters: [Character],
    movie(name: String): Movie,
  }
`;

Our src/resolvers.js should now look like the following:

// Resolvers define the technique for fetching the types defined in the
// schema. This resolver retrieves books from the "books" array above.

import { getCountries } from './data/countries.js';
import { getCharacters } from './data/rickandmorty.js';
import books from './data/books.js';

export const resolvers = {
  Query: {
    books: () => books,
    book: (parent, { title }) => books.find((book) => title === book.title),
    countries: async (parent, { code }) => {
      const { data: { countries } } = await getCountries(code);
      return [...countries.slice(0, 10)];
    },
    characters: async () => {
      const { characters: { results } } = await getCharacters();
      return results;
    },
    movie: (parent, { name }, { dataSources }) => (name
      ? dataSources.movieAPI.getMovie(name)
      : dataSources.movieAPI.getMovie()
    ),
  },
};

How did we grab the movie name and our data sources from our resolver?
Eve really made this clearer for us in her article here.
I really suggest giving it a read.

Every resolver function takes in positional arguments. If there's anything that the resolver needs to execute appropriately (database details, authentication information, etc.), it will be passed via the third argument: context. An important thing to note is that Apollo Server puts dataSources on the context object so it can be used by the resolver functions.

We need to supply this to our Apollo Server instance.
In src/lambda/graphql.js add in the following.

import { MoviesAPI } from '../data/omdb.js';

const server = new ApolloServer({
  typeDefs,
  resolvers,
  dataSources: () => ({
    movieAPI: new MoviesAPI(),
  })
});

Querying for a movie

Open the playground on localhost:9000/graphql.
Add the following query to search for a Batman movie.

query {
movie(name: "Batman") {
  Title
  Year
  Rated
}
}

This will return the following data:

{
  "data": {
    "movie": {
      "Title": "Batman",
      "Year": "1989",
      "Rated": "PG-13"
    }
  }
}

Lastly, before we push to Github, we need to enable the GraphQL playground and introspection in production to see and play with it. Both of these are disabled as a production best-practice.

Deploying to Netlify

Now that we are ready to deploy our server. We can go ahead and commit our project to Github.
If you need to figure out how to create a repository on Github you can follow these docs.

git add -A
git commit -m "created graphql content hub"
git push -u origin main

You can grab all of the code for this project on my Github repo.

The next thing we need to do is tell Netlify to deploy our project. Head on over to Netlify and create a free account to get started.

You will see something like this when you are logged in:

Next, click new site from git and follow the steps.

Our netlify.toml file will be used here during the build phase. This will run the npm run build command.

You will need to go to Build and Deploy and in environments set your OMDB_API_KEY variable.

If if the build fails as a result of your missing environment variable, you just need to manually trigger a deployment in the deploys section.

If you run into issues with encoding when running the build, trying installing encoding with
npm install encoding. You can read about the issue here.

If all goes smoothly, you should see the following message:

My site has now deployed to gql-content-hub.netlify.app/.netlify/functions/graphql.
Feel free to visit the playground.

If you don't like the endpoint being "/.netlify/functions"
you can change it by adding a redirect in netlify.toml.

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

Tutorial complete

As always I hope you enjoyed this tutorial. If you have any feedback please do let me know and I will take it on board. If you liked it and would like to see more posts from me then please do follow me. You can also reach me on Twitter. You can grab all of the code for this project on my Github repo.

References

Fizzbuzz with CSS and Pug

Gary Byrne — Wed, 03 Feb 2021 14:52:27 +0000

Back in 2017, I entered a frontend interview and I was asked to write some code on a whiteboard. I was given the Fizzbuzz problem. Without thinking I immediately went for JavaScript. Recently I learned about CSS counters and that got me thinking. What if we can do it with CSS?

In this article, I am going to show you two easy ways to solve the Fizzbuzz problem with CSS.

What is the Fizzbuzz question?

Write a program that prints the numbers from 1 to 100.
For multiples of 3 print Fizz instead of the number,
for the multiples of 5 print Buzz and for
multiples of both 5 and 3 print FizzBuzz

Solution 1: Using CSS Counters

We can loop in Pug

Loop for 1 to 100 and create an HTML element. In this example, we are creating a div. We will use each div to hold the counter.

- const range = 100;
- for(let i = 1; i <= range; i++)
    .fizz

We are using a for loop here. We could also write an each
iteration such as each _ in Array(100) instead.

Using CSS counters

To get started, we must first create a counter-reset. This will initialize our CSS counter, giving it a name and setting its value. By default, the value is 0.

body {
    counter-reset: fizz;
    // counter initialized with value of 0, same as saying "counter-reset: fizz 0;"
}

Once a counter has been created, we can use counter-increment to increment its value.
For every fizz div, let's update the counter.

.fizz {
    counter-increment: fizz;
}

Next, we will set the content for our divs. We can utilize CSS before and after pseudo-elements to set the content of the div.

If the div is a multiple of 3, set its ::before content to 'Fizz '. If the div is a multiple of 5, set is ::after content to 'Buzz'. If a div is a multiple of both 3 and 5, the before and after pseudo-elements will combine to form Fizz Buzz.

.fizz:nth-child(3n)::before {
  content: 'fizz ';
}

.fizz:nth-child(5n)::after {
  content: 'buzz';  
}

Now we want to set the counter value for those other divs that are not a multiple of 3 or 5. To set the ::before content of the div to use the counter value, we use counter.


.fizz::before {
    content: counter(fizz);
}

.fizz:nth-child(3n)::before {
  content: 'fizz ';
}

.fizz:nth-child(5n)::after {
  content: 'buzz';  
}

This gives us the following:

Note how the divs with a multiple of 5 and not a multiple of 3 still get the number applied. To fix this we can use the not pseudo-class. When the div is not a multiple of 5, then set the before content to the counter number.

.fizz:not(:nth-child(5n))::before {
    content: counter(fizz);
}
.fizz:nth-child(3n)::before {
  content: 'fizz ';
}

.fizz:nth-child(5n)::after {
  content: 'buzz';  
}

Here is a working example in codepen:

Refactoring our Pug

In some cases, an interviewer might ask to change your code to work for a different range instead of 1 to 100. We can write a Pug mixin to take a min and max value.

mixin fizzbuzz(min, max)
    - for(let i = min; i <= max; i++)
        .fizz

+fizzbuzz(1, 100)

Here is a working codepen example:

Browser Support

At the time of writing, CSS Counters are supported in most major browsers. See Can I Use for more information.

Solution 2: Using an Ordered List

Let's copy the same pug from the last example.

mixin fizzbuzz(min, max)
    ol
        - for(let i = min; i <= max; i++)
            li

+fizzbuzz(1, 100)

So we have an ordered list here which returns a list of numbered elements. So if we render 100 list items in that ordered list, we have the numbers already available to view. Although it makes no sense semantically, it is just to show how we might do this.

In this ordered list, we can set the list-style-position of each list item to inside. This will set the position of everything inside, relative to the list which created the nice alignment. We then just set the list style to none to remove the numbering on those items that need the text.

//scss

li {
    list-style-position: inside;

    &:nth-child(3n), &:nth-child(5n){
         list-style-type: none;
    }

    &:nth-child(3n)::before {
          content: 'Fizz';  
    }

    &:nth-child(5n)::after {
          content: ' Buzz';  
    } 
}

Here is a working example:

Creating a Xylophone using CSS and Pug

Gary Byrne — Tue, 02 Feb 2021 16:38:25 +0000

Let's create a simple xylophone with some CSS and Pug. The xylophone sounds I will be using in this blog can be found here. The resulting codepen can be found here.

What will it look like?

We will use an unordered list of buttons to represent the xylophone. The finished product will look like the image below:

Creating the Xylophone

To get up and running quickly with Pug you can open up a codepen. In your HTML settings, click Pug as your HTML preprocessor.

Writing our Pug

Let's create an unordered list of buttons using an array of xylophone notes.

- const notes = ['c', 'd', 'e', 'f', 'g', 'a', 'b', 'c2'];

main
  ul.xylophone(role="list")
    each note, index in notes
      li
        button #{note}

This produces the following HTML:

<main>
  <ul class="xylophone" role="list">
    <li>
      <button>c</button>
    </li>
    <li>
      <button>d</button>
    </li>
    <li>
      <button>e</button>
    </li>
    // ..... the rest
  </ul>
</main>

I added role="list" to the ul to overcome a semantics issue in voiceover and safari.

Let's style our xylophone with CSS.

First, let's reset box-sizing and position the content to the center of the page.

Alternatively, you can just import a CSS reset. I recommend the modern CSS reset by Andy Bell but it's not necessary for this project.

*,
*:before,
*:after {
  box-sizing: border-box;
}

body {
  min-height: 100vh;
  margin: 0;
  display: grid;
  place-items: center;
}

We can style our ul to be a flex container. Using the attribute selector here just to open our CSS to other types of lists.

[role="list"] {
  list-style: none;
  display: flex;
  justify-content: space-between;
  padding: 0;
}

This gives us:

Now we can add some responsive sizing to our xylophone.
We will apply the vmin relative length unit using CSS custom properties.

:root {
  --desired-size: 60;
  --coefficient: 1vmin;
  --size: calc(var(--desired-size) * var(--coefficient));
}

Let's update our list with the new sizing.

[role="list"] {
  list-style: none;
  display: flex;
  justify-content: space-between;
  padding: 0;
  height: calc(1.5 * var(--size));
  width: calc(2.5 * var(--size));
}

li {
  width: 10%;
}

button {
  width: 100%;
  height: 100%;
}

Let's apply the backboards of the xylophone. We will be absolutely positioning these against our xylophone. To do this, we must first set position: relative; in our [role="list"] CSS.

.xylophone:before,
.xylophone:after {
  content: "";
  position: absolute;
  z-index: -1; // hide these to the back, allow our buttons to appear in front
  background: black;
  height: 15%; // 15% of the overall xylophone height
  width: 100%;
}

.xylophone:before {
  top: 10%;
  transform: rotate(3deg);
}

.xylophone:after {
  bottom: 10%;
  transform: rotate(-3deg);
}

This gives us the following:

Hooking up our audio

Before we continue to style our xylophone, let's add some audio to it.

main
  ul.xylophone(role="list")
    each note, index in notes
      li
        button(onclick=`playNote('${note}')`)
          audio(
            data-key=`${note}`,
            src=`https://s3-us-west-2.amazonaws.com/s.cdpn.io/1312918/${note}.wav`
          )

We have added a hidden audio element to be a child of the button. We can hook into this to play each note sound. I have added a src attribute to point to the different wav files. The data-key attribute will be used within our querySelector to help us find an audio element for each individual note. In this example, I have stored them on my codepen s3 bucket. Next, I will need to add some JavaScript to handle the on click logic.

At the bottom of your pug file, add the following script.

script.
  function playNote(note) {
    const audioElement = document.querySelector(`audio[data-key="${note}"]`);
    audioElement.currentTime = 0;
    audioElement.play();
  }

Cleaning up our xylophone

Let's add some color to our buttons:

li:nth-child(1) button {
  background-color: pink;
}
li:nth-child(2) button  {
  background-color: orange;
}
li:nth-child(3) button {
  background-color: yellow;
}
li:nth-child(4) button {
  background-color: lightgreen;
}
li:nth-child(5) button {
  background-color: green;
}
li:nth-child(6) button{
  background-color: skyblue;
}
li:nth-child(7) button{
  background-color: blue;
}
li:nth-child(8) button{
  background-color: rebeccapurple;
}

Next, let's add the knobs for each button:

button {
  width: 100%;
  height: 100%;
  position: relative;
  border-radius: 5px;
}

button::before,
button::after {
  content: '';
  position: absolute;
  left: 50%;
  transform: translateX(-50%);
  height: 5%;
  width: 35%;
  border-radius: 50%;
  background-color: white;
  box-shadow: 0 10px 20px rgba(0,0,0,0.19), 0 6px 6px rgba(0,0,0,0.23);
}

button::before {
  top: 5%;
}

button::after {
  bottom: 5%;
}

Now we have a working xylophone. Here is a working version:

Cleaning up our Xylophone

There is a number of things we can do to tidy up our component.

When we click a button, we can apply a class to show the sound is playing.
For the same button, we can also add an event listener to remove the class
when the transitionend event is fired.
For this, we will remove the class when the box-shadow transition has ended.

Let's add a transition to our button and a nice box-shadow when the button is playing.

button {
  //..other styles
  transition: all 1s ease; //we can listen for the box shadow end
}

button.playing {
  border-color: #ffc600;
  box-shadow: 0px -10px 1rem #FFC600;
}

Add the data-key attribute with the value of the note to our button.

   button(onclick=`playNote('${note}')`, data-key=`${note}`)

Then apply the .playing class when we click the button.

script.
  function playNote(note) {
    const audioElement = document.querySelector(`audio[data-key="${note}"]`);
    const buttonElement = document.querySelector(`button[data-key="${note}"]`);
    buttonElement.classList.add('playing');   
    audioElement.currentTime = 0;
    audioElement.play();
  }

Add our transitionend event listener:

script.
  function removeStyles(e) {
    if (e.propertyName !== 'box-shadow') return;
    e.target.classList.remove('playing');
  }

  function playNote(note) {
    const audioElement = document.querySelector(`audio[data-key="${note}"]`);
    const buttonElement = document.querySelector(`button[data-key="${note}"]`);
    buttonElement.classList.add('playing');
    buttonElement.addEventListener('transitionend', removeStyles);
    audioElement.currentTime = 0;
    audioElement.play();
  }

Now we have a nice transition on our xylophone:

We can do a lot more with Pug. I created another example to show how we can pass values from pug into our CSS to use as custom properties.

I randomly generate the hue for our background color each time, and I can pass the index which I use to make each button smaller in height and create a nice horizontal rhythm. In the pen below, you can also see how I used the kbd element instead of the button element to listen for keyboard events.

References

Font Loading with FontFace Observer - Getting Started

Gary Byrne — Tue, 02 Feb 2021 09:51:53 +0000

Font Loading with Font Face Observer

What is Font Face Observer

Font Face Observer is a really great web font loader created by Bram Stein that provides us with a promised based way to control our font loading. It will know when web fonts have been loaded which gives us complete control to customize the font loading experience as we want.

With web fonts, we decide if we want to self-host or load from external services, so it can be difficult to control our browser's font loading behavior. We need to be careful with problems in our loading like FOIT or FOUT.

Font-Display Swap

@font-face {
  font-family: "Font Family";
  src: url('....url.to.font') format('format');
  font-display: swap;
}

According to the MDN Docs:

If the font face is not loaded, any element attempting to use it must render a fallback font face. If the font face successfully loads during this period, it is used normally. This introduces FOUT which may cause a significant layout shift.

We want to have greater flexibility with our fallback font. With FOUT, it gives us that fallback font but doesn't give us a way to tweak the harsh viewing when layout shift occurs. By using Font Face Observer, it can provide us with a way of controlling this.

Installation of Font Face Observer

Using npm

   npm install fontfaceobserver -S

Using yarn

   yarn add fontfaceobserver

If you are not using node, you can add it by linking the script file into the head of the document.

// locally
<script src="js/vendor/fontfaceobserver.js"></script>
//or from CDN
<script src="https://cdnjs.cloudflare.com/ajax/libs/fontfaceobserver/2.1.0/fontfaceobserver.js"></script>

Roboto Example

Let's grab the Roboto 'Regular', 'Medium' and 'Bold' from Google Fonts.

Next, let's load our fonts in our CSS and point to their directory:

@font-face {
  font-family: "Roboto";
  font-weight: 400;
  src: url("../fonts/Roboto-Regular.ttf") format("truetype");
  font-display: swap;
}

@font-face {
  font-family: "Roboto";
  font-weight: 500;
  src: url("../fonts/Roboto-Medium.ttf") format("truetype");
  font-display: swap;
}

@font-face {
  font-family: "Roboto";
  font-weight: 700;
  src: url("../fonts/Roboto-Bold.ttf") format("truetype");
  font-display: swap;
}

Now we can start using FontFace Observer.
Create a script tag in the head of our document below where we brought in FontFace Observer.

document.documentElement.className += " roboto-inactive";
const RobotoFont = new FontFaceObserver("Roboto", {});

RobotoFont.load().then(function () {
    document.documentElement.classList.remove("roboto-inactive");
    document.documentElement.classList.add("roboto-active");
    sessionStorage.foutFontsLoaded = true;
});

What we are doing here is appending some classes to the root of our document whenever our RobotoFont promise resolves. The promise will resolve when the font has loaded. We can use the roboto-inactive class in our CSS to style our fallback font however we want. This class will only be present when the font fails to load.

If we wanted to load multiple fonts we use Promise.all which will make sure we wait for both promises to resolve before executing our important code.

document.documentElement.className += " wf-inactive";
const robotoFont = new FontFaceObserver("Roboto", {});
const poppinsFont = new FontFaceObserver("PoppinsFont", {
       weight: 700, // we can be more precise
       style: italic
});

Promise.all([robotoFont.load(), poppinsFont.load()]).then(function () {
   // Important code here.... add a class or remove, etc.
});

// We can also provide a second function to 
// run when the font is not available

Promise.all([robotoFont.load(), poppinsFont.load()]).then(
function () {
   console.log('font is available');
   // Important code here.... add a class or remove, etc.
},
function () {
  console.log('font is not available');
 // do something here ...
});

In our CSS, we can now add some styles to clean up our fallback font or add existing styles to our loaded font.


body {
    font-family: 'Roboto', Arial, Helvetica, sans-serif;
}

.wf-inactive body {
    font-family: Arial, Helvetica, sans-serif;
}


.wf-inactive h1,
.wf-inactive h2,
.wf-inactive h3 {
   // you could also apply the font-family to specific
  // elements if we had a heading font for example.
}

.wf-inactive p { 
    // apply these styles to a pargraph using our fallback font 
    line-height: 1.2;
    letter-spacing: -0.5px;
}

// ... more styles here

Support

Promise Support

In the FontFace Observer README it says:

FontFace Observer uses Promises in its API, so for browsers that do not support promises, you'll need to include a polyfill. If you use your own Promise polyfill you just need to include fontfaceobserver.standalone.js in your project. If you do not have an existing Promise polyfill you should use fontfaceobserver.js which includes a small Promise polyfill. Using the Promise polyfill adds roughly 1.4KB (500 bytes gzipped) to the file size.

Browser Support

You can see the browser support within the package README.

References

Variable Fonts in Your Web Projects - Getting Started

Gary Byrne — Tue, 02 Feb 2021 09:47:38 +0000

Before we check out some code, let us briefly discuss what variable fonts are.

OpenType Font Variations

OpenType font variations allow us to create a single font file that contains a variety of fonts from a single typeface.
Variable fonts are fonts that use OpenType font variations. By using variable fonts, we now have access to every variation of a given typeface in a single file, reducing the number of font files considerably. We no longer need a font file for every single style, weight, or even width.

Font Variation Settings and the Variation Axis

With variable fonts, one of the main concepts is an axis of variation. The axis of variation is a range of values to describe a specific aspect of a typeface.
For example, a 'slant' axis * describes how much slant should exist in letterforms, or a *'wght' axis describes how much weight exists in letterforms.

Typeface designers have the ability to use five registered axes of variations.

These are:

Weight
Width
Slant
Italic
Optical size.

These five axes were added to the specification.
Designers also have the ability to add custom axes for their variable font.

Loading a Variable Font.

I wrote about loading a variable font that uses FontFaceObserver. This can be used to optimize your font loading.

Specify a font using @ font-face CSS rule

@font-face {
    font-family: "Vollkorn"; // typeface we are using
    src: url('https://s3-us-west-2.amazonaws.com/s.cdpn.io/1312918/Vollkorn-VariableFont_wght.ttf') 
    format('truetype-variations'); // we have a .ttf font file, support Safari, Android, iOS
    font-display: swap; //browser use fallback font to display content until custom font has downloaded
}

Depending on the type of variable font you are using, you can set the format as woff2-variations, woff-variations, opentype-variations or truetype-variations. This blog from Ollie Williams on CSS-Tricks explains it in more detail. As Ollie says, we should try our best to use woff2 where possible.

Use font-family and set font-variation-settings

Let us change the the font-weight by using font-variation setttings. If we set the weight to 400,
it will look like the following:

h1 {
    font-family: 'Vollkorn', serif;
    font-variation-settings: 'wght' 400; // see wakamaifondue to get min and max values
}

Now if we decide to change it to the max weight, which is 900, we will see:

h1 {
    font-family: 'Vollkorn', serif;
    font-variation-settings: 'wght' 900; // see wakamaifondue to get min and max values
}

We can perform animation by changing the font-variation-settings:

@keyframes scale {
    0% {
        font-variation-settings: 'wght' 400;
    }
    50% {
        font-variation-settings: 'wght' 900;
    }
    100% {
        font-variation-settings: 'wght' 400;
    }
}

The result is a fun animating variable font:

Support for Older Browsers

Check Can I Use for variable font support.

You can check if the browser supports font variation settings:

@supports (font-variation-settings: normal) {
  html {
    font-family: 'SourceSansVariable', sans-serif;
    font-variation-settings: "wght" 900;
  }
}

You can also check if the browser does not support font variation settings:

@supports not (font-variation-settings: normal) {
  html {
    font-family: sans-serif
  }
}

Finding Variation Axes - Wakamaifondue

A service that I use is wakamaifondue, which provides us with tonnes of information about an uploaded font file. When I uploaded a DecovarAlpha variable font to wakamaifondue, I could see it provides me with a short summary about that font. It also provides an interactive area where you can change the variations of axes and see the available characters for that font.

This is a TrueType variable font with 114 characters. It has 15 axes and 0 named instances. It has no layout features.

I wrote a tweet showing how useful this can be. You can see it below:

// Detect dark theme var iframe = document.getElementById('tweet-1278632855699103745-960'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1278632855699103745&theme=dark" }

Benefits of Variable Fonts

1. Single File

As we are only loading one single variable font file which includes all variations of a typeface, it reduces the number of HTTP requests considerably.

Let us pretend we are dealing with static fonts and we decided to use the Poppins typeface. If we needed every font variation of Poppins, we need to make a request for every file. If we need 'Poppins Regular', 'Poppins Bold', and 'Poppins Bold Italic', then we have three font files to deal with.

2. Full Variation Access

With variable fonts, we have access to the full variation settings for that typeface, meaning we can do more with our type and really make the most out of our designs.

*3. Fluid Type Animations *

We have the ability to animate between the different variations in our file, which means we have endless possibilities for animation.

Codepen Examples

A codepen example by Gary Byrne showing how to animate a variable font.

A codepen example by Mandy Michael showing how to animate a variable font.

References

A list of useful links that really helped me understand variable fonts.

OpenType Specification

Frontend Masters Course By Jason Pamental

Mandy Michael Codepen

MDN Variable Fonts Guide

Variable Fonts List

DEV Community: Gary Byrne

Introduction to ARIA Live Regions

What are ARIA live regions?

Live region attributes

aria-live

off (default)

polite

assertive

aria-relevant

aria-atomic

Example

aria-busy

Live region roles

Wrapping Up

Understanding ARIA Landmarks - General Principles and Roles

ARIA General Principles

1: Identify the logical structure of a web page

2: Assign landmark roles to each area

3: Label each area

A list of ARIA landmarks

Top-level landmarks

Other landmarks

HTML sectioning elements

Wrapping Up

Creating a GraphQL Content Hub with Apollo Server

Creating a GraphQL Content Hub with Apollo Server and Deploying to Netlify

What is Apollo Server

What is a GraphQL Playground?

What exactly are we building?

Getting started

Project setup

Dependencies needed

Project structure

Setting up our schema and resolvers

Running the server

Getting countries data

Creating country types and resolvers

Querying our data

Querying the Rick and Morty GraphQL API

Adding our character type and resolver

Querying for a Rick and Morty character

Getting our OMDB movies

Adding our type and resolver for movie

Querying for a movie

Deploying to Netlify

Tutorial complete

References

Fizzbuzz with CSS and Pug

What is the Fizzbuzz question?

Solution 1: Using CSS Counters

We can loop in Pug

Using CSS counters

Refactoring our Pug

Browser Support

Solution 2: Using an Ordered List

Creating a Xylophone using CSS and Pug

What will it look like?

Creating the Xylophone

Writing our Pug

Let's style our xylophone with CSS.

Hooking up our audio

Cleaning up our xylophone

Cleaning up our Xylophone

References

Font Loading with FontFace Observer - Getting Started

Font Loading with Font Face Ob­server

What is Font Face Observer

Font-Display Swap

Installation of Font Face Observer

Roboto Example

Support

Promise Support

Browser Support

References

Variable Fonts in Your Web Projects - Getting Started

OpenType Font Variations

Font Variation Settings and the Variation Axis

Loading a Variable Font.

Specify a font using @ font-face CSS rule

Use font-family and set font-variation-settings

Font Loading with Font Face Observer