javascript on tkainrad

Why Keyboard Shortcuts don't work on non-US Layouts and how Devs could fix it

Thu, 08 Apr 2021 00:00:00 +0000

Introduction

During the past 15 months, I have been thinking a lot about keyboard shortcuts and about how different applications handle them. I shouldn’t complain; I knew what I was getting into when I started to build KeyCombiner, an app for learning and looking up shortcuts and text snippets. Still, I didn’t quite know how much of a mess keyboard shortcut handling on the web is.

Do you use an international keyboard layout? Then you already know what I am talking about. You probably have had some issues typing keyboard shortcuts such as alt+/, or cmd+[. This post will help you to understand why this annoyance exists. However, the people who should most urgently read this post are web developers. Are you a web developer? Great! I will explain how you are currently letting down non-US users and how you can get us out of this mess.

I will focus on web applications. The behavior on desktop apps is often different. However, with the rise of Electron apps, web technologies are ever-present on the desktop as well. So, the arguments in this article probably apply to half of your installed apps as well.

Examples of Broken Apps

The problem I am talking about is so incredibly omnipresent that most international users are just used to the fact that they cannot type a good portion of a given web application’s keyboard shortcuts on their keyboards. However, web applications are becoming increasingly complex, and they are rapidly replacing desktop applications, making this problem bigger by the day.

This is most annoying when the most important keyboard shortcuts are inaccessible. A very common shortcut is / for accessing search functionality. Unfortunately, there is no /-key on most international layouts. Adding modifiers to produce this key with your layout rarely helps. For example, on my German layout, / is produced via Shift+7. Most web applications will ignore this. Similarly painful is when Electron apps use [ and ] for navigating backwards and forwards.

If you use a US layout, you might be surprised to hear about these problems. But rest assured, they are not new and I am not the only one who is affected. We are at a point where it is easy to find users complaining about this for almost any popular web application.

An interesting example are Google’s apps. For some reason, Google manages to handle international layouts correctly in Gmail, but fails to do so in any of its other applications. The web is full of complaints, e.g. for Google Sheets, Google Drive, and Google Docs.

Update: International Layouts now work in Google Chat. Interestingly, the fix was applied shortly after this article reached the front page of Hacker News. I am not saying that these events are correlated, but it is a nice thought.
Unfortunately, the problem persists for other Google Apps, such as GDrive.

Another, almost funny examply is Figma, the popular web-based vector-graphics editor. So many people complained that there is now a dedicated site with workarounds for different layouts.

This complaint in the Asana forums is funny too. They made some specific adjustments for some layouts, only to give up in the end and say that they will still not support more exotic layouts.

There are also plenty of complaints for Notion, see here or here. The competition doesn’t do much better, though, here is an open issue for Roam Research.

Finding all these applications with broken shortcut handling was very easy. I used KeyCombiner’s shortcut search to find all applications that use the US /-key in their shortcuts. Then I googled and found complaints for most of these apps. In the case of Notion and Google Drive/Docs/Sheets, I was already aware simply because I use these applications myself.

I want to be clear, broken keyboard shortcuts are not a law of nature. It is possible to implement web application shortcuts so that they can be typed with any layout. It shouldn’t be an excuse that even some of the most popular apps do not get it right.

Why is this happening?

What baffles me is that the problem exists in apps used by millions of people every day, developed by gigantic corporations who pride themselves with having the best engineers in the world. Why is this baffling? Because the underlying technical issues are rather trivial!

Web applications use JavaScript to process keyboard shortcuts. To do that, they listen to keyboard events that are emitted by your browser whenever your press a key. That’s where it gets a little messy. These keyboard events have several properties that can be used to identify which keys have been pressed. To make matters worse, three different events are associated with a single button press: keydown keypress keyup. Most applications use a Javascript library that handles all these things for them, primarily HotKeys.js or Mousetrap. Let’s look at what Hotkeys.js does:

let key = event.keyCode || event.which || event.charCode;

It uses keyCode, which, or charCode to find out which key was pressed. Why is this a problem? For starters, all three properties are deprecated. That isn’t even the main problem though. These event properties are simply not suited for finding out which character was pressed, at least when used with keydown or keyup. Still a vast majority of web applications use the keydown evente with these properties. It is very clearly documented that this should not be done and that it is not compatible across layouts, operating systems, and even browsers. To cite the MDN web docs:

Web developers shouldn’t use the keyCode attribute for printable characters when handling keydown and keyup events. As described above, the keyCode attribute is not useful for printable characters, especially those input with the Shift or Alt key pressed. When implementing a shortcut key handler, the keypress event is usually better.

Using Chrome on Linux with a german keyboard, my # key will produce the required keyCode for triggering / shortcuts. However, this does not work on Firefox, and neither does it work on Chrome on macOS. With many browser and OS combinations, there is no way to trigger this shortcut on a german layout. The same goes for many other international keyboard layouts that do not have a dedicated /-key.

If you want to see which button presses produce which event properties, you can use this neat little web tool: https://w3c.github.io/uievents/tools/key-event-viewer.html
Hint for developers: Switch your computer’s keyboard layout to something other than US to debug your application’s shortcut handling on different layouts.

Using this event viewer, you will see that the keypress event usually produces the correct code on any layout. Unfortunately, this event is deprecated as a whole and comes with its own problems. Still, the Mousetrap library can use the keypress event with fairly good results on international layouts.

As you can see, the situation is messy. However, developers are usually pretty good at dealing with complex problems. In the next section, I will point out some straightforward ways to do better than Google and other tech giants.

How you can do better

The good news is that this problem is easy to fix. Depending on your resources and the technical and semantical requirements of your application, there are a few things that you could do:

Simple Workarounds

If your web application does not have a huge amount of shortcuts, or if you don’t have the resources to spend a meaningful amount of engineering work on this problem, here are some trivial ways to work around the described issues.

Do not use special characters for your keyboard shortcuts.
That’s all you would need to do to make 99% of your international users happy. If you want to go one step further, you can try to stay on the home row or choose otherwise easy-to-type characters. In case you have an existing application with shortcuts that cannot be changed because your American users already learned them, consider the suggestion below.

Provide Alternatives
If you really do need to use special characters, provide alternatives that can be typed on all keyboard layouts. Both HotKeys.js and Mousetrap support multiple triggers when creating your bindings. For example if you have / as you shortcut for focusing the search field because your US users are accustomed to this behavior, just add alt+s as an alternative for international users. Some US users might welcome this change as well, because alt+s can be typed with just the left hand while / reqiures people to take their hand of the mouse.

Technical Fixes

Actually make the shortcuts work with any keyboard layout.
This means when the key combination is alt+/, the shortcut should be triggered when a german layout user presses alt+shift+7. This is surprisingly easy with some of the popular shortcut processing libraries. With Mousetrap, all you need to do is listen to the keypress events instead of keydown. In the next section of this post, I will mention some applications that work this way. Unfortunately, there is a minor downside to this approach. It can make some shortcuts tedious to type on some layouts, e.g. requiring two or three modifiers. It also has some potential for shortcut conflicts. Ctrl+/ is suddenly the same as ctrl+shift+7. You should be aware of that and not assign these things to two different bindings. The easiest way to avoid such conflicts is by staying away from the Shift modifier when defining your bindings.

If you want to go all the way, you could write your own shortcut processing code, and possibly make it into an open-source library. The current alternatives do not care too much about supporting different layouts. There are a lot of things one could do to solve all the issues described in this article. For example, you could use the key attribute, or even play around with the experimental keyboard.getLayoutMap API. KeyCombiner uses this API to display its on-screen virtual keyboards with the user’s layout. Sometimes, I think about making such a library myself. KeyCombiner already uses a fork of Mousetrap that has been customized quite a bit. However, I already have a demanding full-time job and a large side-project, so I would be happy if you beat me to it.

Allow users to change the default key bindings.
This way, users of international keyboard layouts, can change invalid bindings to something that works for them. As a bonus, you would make any shortcut enthusiast happy, and your marketing people could point out how all your sorry-ass competitors do not allow custom keyboard shortcuts.

Interestingly, I am not aware of a single web application that lets you customize keyboard shortcuts, even though it wouldn’t be that difficult to implement, especially with modern SPAs that would have to pull the custom bindings from the database only once. You could store them in your database, pull them out when a user logs in, and pass them to your shortcut processing library.

Wall of Fame

Fortunately, some applications already do it right. Three apps that I am using where my german layout works flawlessly are Gmail, Linear, and Discourse.

Gmail

It’s hard to believe that Gmail is created by the same company as Google Drive, Google Chat, and many other apps that do not handle shortcuts correctly on international layouts. The Gmail web interface works great on all layouts that I tested. On my german layout, I can even use AltGr+8 to archive a conversation ([). Similarly, search can be triggered via shift+7 (/). Note that this is the exact same shortcut that does not work in all the other Google apps. So, if you work at Google, maybe ask your colleagues on the Gmail team for a little help.

Discourse

Discourse is a great example because it is an open-source application, meaning that you can go to their GitHub repository and see how they are doing it. The answer is very simple: They use the Mousetrap library with keypress. As explained above, keyCode/which/charCode will contain the right code even on international layouts when used with keypress.

Linear

Linear is a relatively new and increasingly popular issue tracking software. It takes pride in having a keyboard first design, and being optimized for efficiency with extensive keyboard shortcuts. Their recent success story and my personal experience suggest that they deliver on this promise. Of course, many other web apps have a lot of keyboard shortcuts, too. However, with Linear, they actually work.

Do you know other applications that work with all keyboard layouts? Please let me know in the comments below, and I will add them here.

Conclusion

Next time you use an app that dangles its keyboard shortcut definitions in front of you, just so you can find out that they don’t work with your layout, please remember this post. You will know that there are ways to fix this.

If you are in the mood, you can write a nice message to the developers, explaining how they are probably misusing the keydown event and its keyCode property. We shouldn’t have to live like this.

Using VueJS alongside Django

Tue, 14 Apr 2020 00:00:00 +0000

Introduction

I am currently working on a very exciting project. The whole thing is quite challenging because the project’s scope is significant, and I am doing it alone in my spare time while working full time. So I have to be very efficient. Fortunately, I am using Django with its batteries-included approach.

The mentioned project is now in Open Beta! You can have a look at https://keycombiner.com.
It is a web application to organize the keyboard shortcuts you use, get better at using them, and to learn new ones.

I use all kinds of Django features that speed up my development, and I wouldn’t want to miss its template engine. Therefore, using Django only in the backend and building a JavaScript SPA for the frontend is not an option for me.
However, even the most avid backend developer has to admit that some things warrant a client-side implementation. Small user actions should not require page reloads. Also, some parts of the web application I am building require rather sophisticated user interaction.

Traditionally, one would mix Django with some jQuery to achieve the desired behavior. But there are newer JavaScript technologies now: React and Vue.
Since our goal is to find a framework that we can use alongside Django without rethinking everything, we will go for Vue as the more lightweight alternative. In this post, I will show that you can start to use Vue alongside Django’s template language with minimal effort.

Installation and Setup

One of the reasons to use Vue is its excellent documentation. It includes many examples, has a decent search, and a reasonably clear table of contents.

This post aims to show that you can start to use Vue with your Django projects immediately without any sophisticated setup that will take hours to complete. Therefore, we will use the simplest method to use Vue.js: Including it via a <script> tag.

<!-- development version, includes helpful console warnings -->
<script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.js"></script>

That is it, we are now ready to create our first Vue.js instance:

<div id="app">
  {{ message }}
</div>

var app = new Vue({
  delimiters: ["[[", "]]"],
  el: '#app',
  data: {
    message: 'Hello Vue!'
  }
})

This example is taken from the official Getting Started Guide. However, there is one addition. Per default, Django and Vue use the same template tags. Hence, we need to set the Vue delimiters explicitly to avoid conflicts with Django’s template engine.

Access Django Data from Vue

The simplest way to do so is the built-in Django jscon_script filter. This way you can immediately start using your Django models as data for your Vue instances.

In HTML:

{{ django_template_variable|json_script:"djangoData" }}

Then, in JavaScript, we load this data into a variable:

let jsVariable = JSON.parse(document.getElementById('djangoData').textContent);

And it is ready to use with Vue:

new Vue({
  delimiters: ["[[", "]]"],
  el: '#app',
  data: jsVariable
})

Make async Backend Requests

One of the most frequent tasks of a Vue frontend is to make requests to a backend server application. With a full-stack Django application, we don’t have to do this for every user interaction. In some cases, a full page reload might be perfectly fine, and Django’s templating system provides all kinds of advantages. But to enhance user experience and to reap the full benefits of using Vue, we may still want to make backend requests in some places.

Vue itself cannot handle requests. In this post, I will use axios, because it is also recommended in the official Vue Docs. Other alternatives are perfectly fine too.

To pass Django’s CSRF protection mechanism, axios needs to include the respective cookie in its requests. The easiest way to accomplish this is to set global axios defaults:

axios.defaults.xsrfCookieName = 'csrftoken';
axios.defaults.xsrfHeaderName = "X-CSRFTOKEN";

Alternatively, we could also create an axios instance with the required settings:

var instance = axios.create({
    xsrfCookieName: 'csrftoken',
    xsrfHeaderName: "X-CSRFTOKEN",
});

Your Django template needs to contain the tag {% csrf_token %} or, alternatively, the respective view must use the decorator ensure_csrf_cookie().

The rest of Django’s default session backend for authentication will work out of the box, meaning that you can annotate your backend services with things like loginRequired and it will just work. To make the request, we can use axios as usual:

axios.post('/django/backend/endpoint', {
    data: jsVariable 
})
    .then(function (response) {
        // handle response
    })
    .catch(function (error) {
        // handle error
    });

This call can be done within a Vue instance’s mounted hook or any other place where you can put JavaScript code.

If you activated CSRF_USE_SESSIONS or CSRF_COOKIE_HTTPONLY in your Django settings, you need to read the CSRF token from the DOM. For more details, see the official Django docs.

Conclusion

When you google for Django + Vue, most results will be focused on using Django for your backend and Vue for a separate frontend project. Having two independent projects increases complexity, and you lose access to Django’s template system, which is a very powerful timesaver. On the other hand, access to a frontend framework such as Vue can do wonders for web applications that go beyond CRUD functionality.

Fortunately, we do not need to decide between the two. This guide shows that you can have the cake and eat it too!