DEV Community: Manuel Sommerhalder

Display your PWA / website fullscreen

Manuel Sommerhalder — Thu, 07 Jan 2021 09:43:11 +0000

In this short article I will show you how to expand your installed PWA to the full edge of the screen of a mobile device and how to take care of design issues that might occur.

Standalone mode

As soon as the user has added your PWA to the home screen and opened it, it runs in a standalone mode, where e.g. the navigation bar of the browser will disappear and we can produce more app-like designs.

We can detect if the PWA is running in standalone mode inside our application like this:



// on iOS Safari
window.navigator.standalone

// on Android Chrome
window.matchMedia(
  '(display-mode: standalone)'
).matches

Because of the platform difference, a more popular approach is to define a start_url inside your manifest.json file, where we can add a parameter that will be added, when the app is started in standalone mode. Then we can check for the parameter inside our application to make changes to our UI.

To display it fullscreen and remove native control elements, we also have to add the display property with the value standalone (fullscreen won't work). Here's our current manifest:



// manifest.json
{
  "name": "Example App",
  "display": "standalone",
  "start_url": "/?standalone=true"
}

Meta Tags

To display your app fullscreen, we will also have to add a few meta tags.

You might already have a viewport meta tag, but make sure viewport-fit=cover is inside it (separated by ;):



<meta name="viewport"
    content="width=device-width; initial-scale=1; viewport-fit=cover">

Then we have to add the mobile-web-app-capable and status-bar-style meta tags:



<meta name="mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-capable" content="yes">

<!-- possible content values: default, black or black-translucent -->
<meta name="apple-mobile-web-app-status-bar-style"
    content="black-translucent">

Note that we can decide, whether the status bar should have a white (default), black or transparent (with white color) background. Take into account that this meta tag is only used when the app starts, so it's app-wide and we can't modify the meta tag later to change the color dynamically.

Because we also want to be able to display content underneath the status bar, we'll use the transparent background (black-translucent). This will also shift our app up to the top of the screen.

Now we can produce fancy headers that look like this:

Safe Area

Since we can display content underneath the status bar now, we'll have to make sure that the white text will always be readable (e.g. with a decorative shadow or ensuring dark background colors) and that there will be no interactive elements underneath. Also we might have to take the notch into account, which some newer iOS versions have:

To solve those problems we can utilize the safe-area CSS env variables (supported since iOS >= 11.1 and Chrome >= 69):



.element {
    height: env(safe-area-inset-top);
    width: env(safe-area-inset-left);
    margin: env(safe-area-inset-right);
    // you can also use fallback values
    padding: env(safe-area-inset-bottom, 20px);
}

As an example, I implemented a sticky navigation bar vue component for my app, which has an element with the top safe-area applied as height. It will be transparent as long as the transparent property is true and the user has not scrolled down. Here's the crucial part of the component:



<!-- NavigationBar.vue -->
<div class="sticky top-0">
    <div
        class="h-safe-area-inset-top"
        :class="{
            'bg-black': !transparent
                        || (transparent && scrollTop > 0)
        }"
    ></div>
    ...
</div>

<style>
.h-safe-area-inset-top { height: env(safe-area-inset-top); }
.bg-black { background-color: #444; }
</style>

<script>
export default {
  data() {
    return {
      scrollTop: 0
    }
  },
  props: {
    transparent: {
      type: Boolean,
      default: false
    }
  },
  methods: {
    scrollListener(e) {
      this.scrollTop = e.target.scrollTop;
    }
  },
  mounted() {
    window.addEventListener('scroll', this.scrollListener);
  }
}
</script>

If you have a question, don't hesitate to leave a comment. Happy coding and designing! 👨🏼‍💻

How to embed a PWA into a (existing) native iOS / Android App

Manuel Sommerhalder — Tue, 05 Jan 2021 19:40:57 +0000

In this article I will show you, how to embed a progressive web app (PWA) or any website into a (existing) native app from a frontend perspective. How they can communicate with each other and navigation handling.

The PWA was built with Nuxt, so the example code will be Nuxt specific, but the principles are applicable to every PWA.

Table of contents 📖

🤔 Why?
🍪 Storage & Login Session
📨 Communication
🧭 Navigation

Why? 🤔

A good question. You might consider following points:

🏗 You may want to replace an existing iOS/Android app with a PWA step by step or build some new feature that should also work on the web
🤑 It reduces developer effort, you only need to develop once on one platform
🤖 The new feature should be indexable by search engines
🏃‍♂️ New features / fixes can be shipped faster, because you don't have to go through the publishing process
🏠 App will still be available at the App/Play Store, so users can find and install it over different channels
🦄 Maybe you want to do something that a PWA can't do (yet) like accessing the calendar, contacts or intercepting SMS/calls. Or do something iOS Safari can't do, because the API still is missing (e.g. background sync).

Storage & Login Session 🍪

The PWA will be displayed inside a WKWebView (>= iOS 8). You can think of it as an iframe for native apps. Every WKWebView has its own storage data (cookies, localStorage, IndexedDB, etc.) and it will be restored when closed and reopened again. But the native App doesn't share its own cookies with the WebView.

So if you need a logged in user, you should manually reuse the login session, to prevent the user from having to login in a second time, after opening the PWA in the WebView.

To achieve this, the app developer can set a cookie with the already established session/token that he got e.g. from the initial app login screen or from a fingerprint. To set a cookie for the WebView, he can use the WKHTTPCookieStore:

Communication 📨

You might want your PWA and native app to be able to talk to each other and tell them to execute actions. So we are going to build a bridge, where they can talk with each other.

For this we will add a global object (window.bridge) with two methods. One for invoking actions on the native app from inside the PWA (invokeNative) and a second one for receiving messages and commands (invokedByNative), which will be executed from within the native app. Inside this method, we can put the messages into our Vuex store, so that we can observe them.

The method names, the data structure you pass to the iOS/Android developer and data you receive are up to you and the app developer.

The app developer can inject JS Code into the WebView. For our example, he would have to define a global method window.invokeCSharpAction, which receives a JSON string. We can check for that function to detect whether we are inside the app or just in a normal browser.

Below, the code for the bridge, which was put into a Nuxt plugin:



// bridge.client.js nuxt plugin
export default (context, inject) => {
    // force app mode with ?app param to be able to test
    const { app } = context.query;
    // determine whether the app is opened inside native app
    const inApp = !!window.invokeCSharpAction
        || typeof app !== 'undefined';

    // inject global $inApp variable and 
    inject('inApp', inApp);
    context.store.commit('setInApp', inApp);

    // the bridge object in the global namespace
    window.bridge = {
        // invoke native function via PWA
        invokeNative(data) {
            if (!window.invokeCSharpAction) {
                return;
            }

            window.invokeCSharpAction(
                JSON.stringify(data)
            );
        },
        // called by native app
        invokedByNative(data) {
            // write passed data to the store
            context.store.commit(
                'addAppMessage',
                JSON.parse(data)
            );
        }
    }

    inject('bridge', window.bridge);
}

After setting up the bridge, we are able to invoke native actions inside our PWA like this:



// callable in stores, components & plugins
this.$bridge.invokeNative({
    function: 'Close'|'SaveSomething'
    payload: {
        lang, title, ...
    }
});

And the native app developer can call PWA actions by executing JS code like this:



// callable in native app
this.$bridge.invokedByNative({
    function: 'GoBack'|'HasSavedSomething'
    response: {
        success, ...
    }
});

A save action inside a Vuex store could look like this:



async saveSomething({ state, commit, rootGetters }) {
    // prevent saving while it's already saving 
    if (state.isSaving) {
        return;
    }

    commit('setIsSaving', true);

    // data we want to pass to the app or to our API
    const payload = { ... };

    // call the bridge method inside app
    if (this.$inApp) {
        this.$bridge.invokeNative({
            function: 'SaveSomething',
            payload
        });
    // otherwise we will call the API like we're used to
    } else {
        // await POST or PUT request response ...

        // finish saving and set response id
        if (response.success) {
            commit('setId', response.id);
        } else {
            // Failed, inform user 😢
        }

        commit('setIsSaving', false);
    }
}

You might noticed that we don't get a direct response from the bridge method like we would get from an ordinary API call. To be able to know when the app has finished the action and whether is was successful, the native app has to inform us by calling the invokedByNative method. In the PWA, we can listen to the received message like this:



// inside app / layout component
import { mapState, mapMutations } from 'vuex';

export default {
    computed: {
        // map messages and isSaving to show a loader e.g.
        ...mapState(['appMessages', 'isSaving'])
    },
    methods: {
        // map necessary mutations
        ...mapMutations(['setId', 'setIsSaving'])
    },
    watch: {
        // watch the messages from the store for any changes
        appMessages(mgs) {
            // get last received message
            const lastMsg = mgs[mgs.length - 1];
            const appFunction = lastMsg.function;
            const response = lastMsg.response || {};

            // check if last message belongs to function we expect a response from
            if (appFunction === 'HasSavedSomething') {
                if (response.success) {
                    this.setId(response.id);
                } else {
                    // Failed, inform user 😢
                }

                this.setIsSaving(false);
            }
        }
    }
};

Now we're done setting up the bridge and can send each other commands!

Navigation 🧭

When your PWA is running inside a WebView just as part of a native app, make sure that the user is always able to get back to the app, without having to close the entire app.

You can utilize the global $inApp variable we have set before in the Nuxt plugin to change your templates and components. You may want to display a close button in a menubar when the PWA is opened in the WebView or make other design adjustments:

Furthermore, the app developer should make sure to catch HTTP errors like 404 or 500, close the WebView and possibly show a message to inform the user.

Another challenge is implementing the back button/navigation. On Android we usually have a back button at the bottom. On iOS we don't have one, but could use a swipe gesture instead.

When the user navigates back, history.back should be called inside the PWA as long as there are previous visited sites, otherwise the WebView should be closed.

Unfortunately, the window.history API doesn't offer a possibility to detect on which position you are currently in your history entries or accessing them. Also the canGoBack property doesn't seem to work, when pushState is used inside the PWA, to update URLs.

We can solve this inside the PWA, by implementing our own history / back-forward list:



// inside app / layout component
export default {
    data() {
        return {
            history: []
        }
    },
    watch: {
        // watch route which updates when URL has changed
        '$route'(to, from) {
            // find if target page has been visited
            const entry = this.appRouteHistory
                .findIndex(
                    entry => to.path === entry.from.path
                );

            if (entry > -1) {
                // back navigation:
                // remove every entry that is
                // after target page in history
                this.appRouteHistory.splice(entry);
            } else {
                // forward navigation
                this.appRouteHistory.push({ to, from });
            }
        }
    },
    methods: {
        goBack() {
            const lastAppHistoryEntry = this.appRouteHistory.length > 0
                ? this.appRouteHistory[this.appRouteHistory.length-1]
                : null;

            if (lastAppHistoryEntry) {
                // go back to last entry
                this.$router.push(lastAppHistoryEntry.from);
            } else {
                // tell the app it should close the WebView
                this.$bridge.invokeNative({
                    function: 'Close'
                })
            }
        }
    }
}

Inside the app, the developer can overwrite the back button functionality to call this JS code:



// callable in native app to go back in PWA or close WebView
this.$bridge.invokedByNative({ function: 'GoBack' });

Finally, make also sure listen to the GoBack message inside the watch: { appMessages() }method (see implementation in the communication section above) and call the goBack method.



if (appFunction === 'GoBack') {

    this.goBack();

}

The End 🔚

I hope this article gave you an quick overview of establishing a connection between your PWA and (existing) native app. Leave a comment, if you have any questions!

Setup a Vendure E-Commerce API on a Dokku Droplet

Manuel Sommerhalder — Sun, 28 Jun 2020 12:10:44 +0000

If you haven't heard of Vendure, it is a "modern, headless GraphQL-based e-commerce framework built with TypeScript & Nodejs". It's still in beta but already used in production and a major release is planned until end of this year. Check it out on vendure.io!

This guide assumes that you have already installed a local Vendure project via @vendure/create. It will lead you through the setup of Vendure on a Dokku droplet, hosted by DigitalOcean with some tips for your production system. If you have no DigitalOcean account yet, you can use this referral link if you want, to get $100 over 60 days.

Create Droplet

First you can create the Dokku droplet with the one-click installer here: https://marketplace.digitalocean.com/apps/dokku

When creating the droplet, you will see three setting fields:

Public Key: For adding an SSH key to login into your server.
Hostname: For setting the hostname (e.g. example.com). You an also just use the IP address of your droplet.
Use virtualhost naming for apps: Enable this if you want the app URLs by default to be APP_NAME.example.com instead of example.com:APP_PORT_NUMBER.

Make sure your droplet has:

Enough disk space: I'm currently using 9.5GB including OS, Docker containers and around 200 product images.
Enough memory: Especially if you are going use the ElasticsearchPlugin to search through products. I would recommend at least 3GB of memory and a swapfile of 3GB (we will create one later). This should be enough in the beginning and the swapfile can cover possible memory peaks.
A firewall: To secure your droplet, make sure you restrict inbound rules to only HTTP(S) and also SSH if you want to login on your server via SSH. This will prevent outsiders from accessing your Elasticsearch instance on port 9200/9300. On your droplet overview click on Secure your Droplets and add a new firewall. Set the inbound rules to HTTPS and SSH and save. You firewall should look like this:

It might also make sense for you to enable backups for weekly snapshots, after the shop is up and running.

Setup Dokku Environment

When the droplet is ready and you are able to connect with your previously added SSH key (ssh -i SSH_KEY_NAME root@IP_OF_YOUR_DROPLET), we can start setting up Dokku and its services. First we will create the app:

dokku apps:create myshopapi

So our API is later going to be available on myshopapi.example.com/shop-api and the admin area on myshopapi.example.com/admin. Dokku will provide the ENV variable PORT, which we will use later in our config file.

Create storage folder

Then we will create a persistent storage folder that will get mounted to the /storage folder of the app when the application starts. It stores product assets, mail templates and test mails. On your droplet run the following:

# create folder and set correct ownership
mkdir -p  /var/lib/dokku/data/storage/myshopapi
chown -R dokku:dokku /var/lib/dokku/data/storage/myshopapi

# mount it to your app container to /storage
dokku storage:mount myshopapi /var/lib/dokku/data/storage/myshopapi:/app/storage

Then zip and upload the contents of the /static folder from your local computer:

# create zip file
cd ~/YOURLOCALPROJECTFOLDER/static
zip -r ../storage.zip . *

# upload it to your droplet
scp ~/YOURLOCALPROJECTFOLDER/storage.zip root@IP_OF_YOUR_DROPLET:/var/lib/dokku/data/storage/myshopapi

Back at your droplet unzip it:

# unzip folders
unzip /var/lib/dokku/data/storage/myshopapi/storage.zip
# remove the zip
rm /var/lib/dokku/data/storage/myshopapi/storage.zip

Now you should have your assets and email folders inside the /var/lib/dokku/data/storage/myshopapi folder.

Install MySQL Dokku Plugin

I choose MySQL but you can also use Postgres, MariaDB or SQLite if you like. Let's call the service myshopapi-mysql and link it to the app:

sudo dokku plugin:install https://github.com/dokku/dokku-mysql.git mysql
dokku mysql:create myshopapi-mysql
dokku mysql:link myshopapi-mysql myshopapi

After the installation is complete you should get some data/config directories and the ENV variable DATABASE_URL. The value should look like this: mysql://mysql:YOUR_MYSQL_PASSWORT@dokku-mysql-myshopapi-mysql:3306/myshopapi_mysql

For easier usage of the login data in our config file later, we set our own custom ENV variables:

dokku config:set --no-restart myshopapi MYSQL_PORT=3306
dokku config:set --no-restart myshopapi MYSQL_USER=mysql
dokku config:set --no-restart myshopapi MYSQL_PASSWORD=YOUR_MYSQL_PASSWORD
dokku config:set --no-restart myshopapi MYSQL_HOST=dokku-mysql-myshopapi-mysql
dokku config:set --no-restart myshopapi MYSQL_DB=myshopapi_mysql

Install Elasticsearch Dokku Plugin

First we install the plugin and create the service. Vendure should work with v7.0 or higher. I'm currently using v7.5.2. Then we increase the max_map_count option of the virtual machine to prevent out of memory exceptions:

# install plugin
sudo dokku plugin:install https://github.com/dokku/dokku-elasticsearch.git elasticsearch
# set version you want to use
export ELASTICSEARCH_IMAGE_VERSION="7.5.2"
# create service
dokku elasticsearch:create myshopapi-elasticsearch
# expose the service to ports
dokku elasticsearch:expose myshopapi-elasticsearch 9200 9300
# link the service to your app
dokku elasticsearch:link myshopapi-elasticsearch myshopapi
# increase max_map_count 
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf; sudo sysctl -p

Since Dokku seems to have an issue connecting with Elasticsearch v7.*, you will get an unable to connect error after creating the service. We also have to paste in following into the /var/lib/dokku/services/elasticsearch/myshopapi-elasticsearch/config/elasticsearch.yml file, to be able to connect to the instance:

node.name: node-1
cluster.name: docker-cluster
network.host: 0.0.0.0
cluster.initial_master_nodes:
  - node-1

We also get an ENV variable during this process named ELASTICSEARCH_URL which looks like this: http://dokku-elasticsearch-myshopapi-elasticsearch:9200

We will also split it in our own variables, to use it later in our config file:

dokku config:set --no-restart myshopapi ELASTICSEARCH_HOST=http://dokku-elasticsearch-myshopapi-elasticsearch
dokku config:set --no-restart myshopapi ELASTICSEARCH_PORT=9200

Create a Swapfile

I still experienced memory overflows sometimes on production when Elasticsearch was busy. We can create a 3GB swapfile to help cover those like previously mentioned. You can also create a larger one, the recommendations vary. Changing it or adding another file later is possible too.

Further, we will set the swappiness variable to 10, so the virtual machine is less likely going to use the swapfile instead of the memory.

# create 3GB swapfile
fallocate -l 3G /swapfile
# set correct permissions
chmod 600 /swapfile
# set up swap area
mkswap /swapfile
# turn swap one
swapon /swapfile
# save swap file in config to use after restart
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# check if the swap is on
swapon --show
# set the swappiness
sysctl vm.swappiness=10
# save config to use after restart
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

Install LetsEncrypt Dokku Plugin

What would be a good shop without SSL? So now we add the domain for the vendure instance and install the LetsEncrypt plugin and add a cronjob to renew the certificate automatically:

# add domain to dokku app
dokku domains:set myshopapi API.YOURDOMAIN.COM

# install letsencrypt
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

# set your email
dokku config:set --no-restart myshopapi DOKKU_LETSENCRYPT_EMAIL=YOUREMAIL@example.com

# install certificate for domain and add renewal cron job
dokku letsencrypt:enable myshopapi
dokku letsencrypt:cron-job --add

Set further Environment Variables

Since sensitive data should not be in your source code when checking into git, we will add some more ENV variables for the SMTP connection, which will be used to send emails and also one for the session secret.

dokku config:set --no-restart myshopapi SESSION_SECRET=YOUR_SESSION_SECRET_KEY

dokku config:set --no-restart myshopapi SMTP_HOST=YOUR_SMTP_HOST
dokku config:set --no-restart myshopapi SMTP_PORT=YOUR_SMTP_PORT
dokku config:set --no-restart myshopapi SMTP_USER=YOUR_SMTP_USER
dokku config:set --no-restart myshopapi SMTP_PASSWORD=YOUR_SMTP_PASSWORD

Change your `vendure-config.ts` File

Now that we have everything ready, we can update our config file with all the ENV variables. We will also add cors.origin setting to be able to query the API myshopapi.example.com from example.com and set the correct assetUrlPrefix. Here's how your config file could look:

import path from 'path';

import {
  VendureConfig,
  DefaultJobQueuePlugin,
  examplePaymentHandler
} from '@vendure/core'

import { Transport } from '@nestjs/microservices'

import { AssetServerPlugin } from '@vendure/asset-server-plugin';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { ElasticsearchPlugin } from '@vendure/elasticsearch-plugin';
import { EmailPlugin, defaultEmailHandlers } from '@vendure/email-plugin'

export const config: VendureConfig = {
  workerOptions: {
    transport: Transport.TCP,
    options: {
      host: 'localhost',
      port: 3020
    }
  },
  apiOptions: {
    port: Number(process.env.PORT) || 3000,
    adminApiPath: 'admin-api',
    shopApiPath: 'shop-api',
    cors: {
      origin: /example\.com$/
    }
  },
  authOptions: {
    sessionSecret: process.env.SESSION_SECRET
  },
  dbConnectionOptions: {
    type: 'mysql',
    synchronize: false,
    logging: false,
    port: Number(process.env.MYSQL_PORT) || 3306,
    database: process.env.MYSQL_DB,
    host: process.env.MYSQL_HOST,
    username: process.env.MYSQL_USER,
    password: process.env.MYSQL_PASSWORD,
    migrations: [path.join(__dirname, '../migrations/*.ts')]
  },
  paymentOptions: {
    paymentMethodHandlers: [examplePaymentHandler]
  },
  plugins: [
    DefaultJobQueuePlugin,
    AssetServerPlugin.init({
      port: 3001,
      route: 'assets',
      assetUploadDir: '/storage/assets',
      assetUrlPrefix: 'https://myshopapi.example.com/assets/'
    }),
    ElasticsearchPlugin.init({
      host: process.env.ELASTICSEARCH_HOST,
      port: Number(process.env.ELASTICSEARCH_PORT) || 9200
    }),
    EmailPlugin.init({
      handlers: defaultEmailHandlers,
      templatePath: '/storage/email/templates',
      transport: {
        type: 'smtp',
        host: process.env.SMTP_HOST || '',
        port: Number(process.env.SMTP_PORT) || 587,
        auth: {
          user: process.env.SMTP_USER || '',
          pass: process.env.SMTP_PASSWORD || ''
        }
      },
      globalTemplateVars: {
        fromAddress: '"Example" <info@example.ch>',
        verifyEmailAddressUrl: 'https://example.com/verify',
        passwordResetUrl: 'https://example.com/password-reset',
        changeEmailAddressUrl: 'https://example.com/verify-email-address-change'
      }
    }),
    AdminUiPlugin.init({
      port: 3002
    })
  ]
}

module.exports = { config };

Setup Git

Finally we can add the droplet as remote in our git repostory and push our code to it:

git remote add dokku dokku@IP_OF_YOUR_DROPLET:myshopapi
git push dokku master

Some useful Dokku commands

# output app logs
dokku logs myshopapi
# output Elasticsearch logs
dokku elasticsearch:logs myshopapi-elasticsearch
# restart the app
dokku ps:restart myshopapi
# connect to MySQL database
dokku mysql:connect myshopapi-mysql
USE myshopapi_mysql;
# export/import an SQL file from/into database
dokku mysql:export myshopapi-mysql > backup.sql
dokku mysql:import myshopapi-mysql < backup.sql

I hope this guide will help you setting up your shop API. Please comment if something is not working or if you have other tips, that you would like to share. You can also join the Slack channel or look into the real world Vendure project on Github, which might help you too.

Accessibility Developer Guide: Setup and use a blind user's environment

Manuel Sommerhalder — Sun, 23 Jun 2019 00:24:09 +0000

The awareness for accessibility in website development gladly seems to have increased a lot in the past few years. A great resource for how to build and test accessible websites and widgets is the Accessibility Developer Guide created by the Access4all foundation and its partner agencies. Check it out if you haven't done it yet!

In this article I want to get you started on how to setup an environment to test your websites from a blind user's perspective with a screen reader.

Setup Environment

Used software:

Create `Insert` Key

When using a screen reader, you sometimes need a modifier key for special key combinations. Caps Lock and Insert are offered but Caps Lock doesn't seem to work with VirtualBox.

For Mac Users: There is no native Insert key on a MacBook, but you can remap an unused key as Insert (e.g. right Command ⌘, Option ⌥ or Shift ⇧) like this:

Download, install and run karabiner-elements
Press Simple Modifications -> Add item and choose a desired From key and set To key to Insert

Install Virtual Machine

To install the screen reader software a Windows OS is required. It makes sense to install it as a virtual machine to prevent polluting your system and have a ready environment for testing. Microsoft gives away a free 90 days Windows trial for browser testing that you can use. I went for the MSEdge on Win10, since IE11 is also installed along with Edge and therefore also useful for normal cross browser testing, especially on a Mac.

Download & install VirtualBox (or use your already existing virtual machine software)
Download & setup Windows from Modern.IE

Install Screen Reader & Browsers

The two most commonly used screen readers are JAWS (66%) and NVDA (64.9%). As you see, screen reader users tend to use more than just one screen reader. Since NVDA is free to use, we will use that one.

Download & install NVDA

A screen reader software just lays on top of a normal browser and users can decide which browser they want to use. Hence you should also install other popular browsers besides IE. Usually JAWS is used with IE (24.7%) and NVDA is used with Firefox (23.6%). For Firefox you need to install a special extended support release (ESR).

Download & install Firefox ESR
Download & install Chrome

Configure NVDA

You should primarily go with the default configuration, but there are some options that are helpful with testing. If NVDA is running, press Insert + N to open the NVDA menu.

Open speech viewer by choosing Tools -> Speech viewer
- Check option Show Speech Viewer on Startup (always see what has been announced by the screen reader)
Open the settings window by choosing Preferences -> Settings...
- Choose General -> select the Language you want
- Choose Speech -> Synthesizer -> Press Change... -> select Windows OneCore voices and press OK. Then select the Voice you like most.
- Choose Keyboard -> Uncheck Speak typed characters (prevents announcing characters while typing)
- Choose Mouse -> Uncheck Enable mouse tracking (prevents announcing the objects below the mouse)
- Choose Browse Mode -> Uncheck Automatic Say All on page load (prevents starting to read the whole document on page load)

Additionally you should also install the Focus Highlight plugin. It shows you the current position of the navigator and focused object (see Focus and Browse Mode below).

Download & install Focus Highlight

Border	Description
green & thin (dashed)	indicates the navigator object
red & thin	indicates the focused object/control
red & thick	indicates when navigator object and focused object are overlapping
blue & thick (dashed)	indicates NVDA is in focus mode, i.e. key types are passed to the control

Important: After installing/configuring the screen reader and browsers you should take a snapshot from the system to be able to restore it after Windows has expired.

Usage of Screen Reader

Focus and Browse Mode

A screen reader essentially has two modes, browse and focus mode. When reading a page, blind users use browse mode by using Down/Up arrow keys to sequentially read line by line. It moves the navigator object. Other shortcuts are used to move it to certain elements of the website like headings or links (see Browse/Read Mode Shortcuts below).

If you want to interact with elements, like entering text into an input field, you have to enter focus mode. You can switch to it by pressing the Enter key when the navigator object is over the element or by using the Tab key to focus the next interactive element. In focus mode, the screen reader also tries to find and announce associated information (e.g. from a label or aria-describedby). You can go back to browse mode with ESC.

Keyboard Shortcuts

The following is an overview of most shortcuts for the NVDA screen reader.

General

Tab
Jump to next focusable element and activates focus mode where appropriate.

Ctrl
Abort announcing current stream of words

Ctrl + Home
Jump to beginning of the page

Ctrl + Alt + N
Start/Restart NVDA

Insert + N
Open NVDA menu

Insert + S
Toggle speech mode (on, off or beep mode)

Insert + F7
Shows the elements list.

Browse/Read Mode

Down / Up Arrow
Read content sequentially line by line

Ctrl + Down / Up Arrow
Read paragraph by paragraph (or any other kind of container)

Left / Right Arrow
Read next / previous character

Enter
Switch to focus mode if available (sound is played)

H
Move to next heading

1-6
Jump to next headings on specific level

K
Move no next link

V / U
Jump to visited / unvisited links

L / I
Jump to lists / list item

G
Jump to images

T / Ctrl + Alt + Left/Right/Up/Down
Jump to tables / navigate through

F
Jump to forms

B
Jump to buttons

D
Jump to landmarks

Focus/Interaction Mode

Esc
Switch to browse/read mode (sound is played)

Space
Toggle checkboxes / radios or expand / collapse comboboxes

Enter
Activate Links / submit forms

Alternative Tools

You may don't have the possibility to install a virtual machine on your computer. There are some alternative tools you can use to ensure accessibility to some extent. But be aware that the majority of blind users use NVDA or JAWS and they might behave differently.

Chrome Vox - browser extension for Chrome used as screen reader for chromebooks
WAVE - accessibility audits, as browser extension for Chrome and Firefox
A11y - accessibility audits, as npm module / cli (also integrated in Chrome Dev Tools)
Pa11y - accessibility audits, as npm module / cli, webservice, dashboard, etc.