peterxjang

One year of using an Apple Watch Ultra as a phone replacement

2024-04-09T00:00:00Z

I bought the 1st generation Apple Watch Ultra last year in March, and I've been using it as a full-time phone replacement since then. There have definitely been some interesting pros and cons with this experiment, but long story short, this setup has been working phenomenally and I have no plans on switching back. If you're interested in this approach to fight back in the war for your attention, you can read on for the specifics of my setup and experiences.

Background #

Over the last several years I became uncomfortable with how my phone was quickly filling my spare time with mindless scrolling on sites like Reddit or YouTube. I think many people are familiar with the reflex of reaching for their phone anytime they are bored throughout the day. A commonly suggested solution to this problem is to delete specific apps, which I tried but didn't find that effective, as I would just look for a different app to fill the time (in the end, you can always just browse the web). For me, I actually don't think the issue is mindless scrolling itself - the issue is that we are carrying a device in our pocket 24/7 that's optimized to relentlessly promote mindless scrolling at all times. To use an analogy - I don't think sugar is inherently bad, but too much sugar is obviously bad for your health, and it can be an addictive substance. So it would be insane to carry a giant bag full of chocolates everywhere you go 24 hours a day.

So my solution to this problem is to never carry a smartphone with me, and replace it with a different device for essential tasks like messaging. One possibility is to use a dumb phone that can be used for texting and calling but not much else, but it seems far from ideal. Basically you're left with a device that is usually really bad at texting, has poor call quality, and doesn't have GPS navigation, which is one feature that I don't want to give up. My goal is to keep all the utility of a smart phone without the addictive features. A smart watch seemed like a good solution, as there are cellular models that can work without being tethered to a phone. But up until recently, the battery life wasn't nearly good enough to work as a phone replacement.

All that changed with the release of the Apple Watch Ultra. Nearly all of its features seems tailor-made for my use case as a phone replacement. Multi-day battery life. Built like a tank but with lightweight materials. Highest quality GPS. Highest quality for phone calls. All of this does come with hefty price tag - $799 USD for the watch, plus around $10/month to use the smartwatch cellular feature on most phone plans. And it can't be set up without an iPhone, which is an extra cost if you don't already own one. This seems crazy expensive, until you compare it with the cost of the higher end iPhones, which are over $1000 USD. Because the goal is to not use the phone itself on a daily basis, you can get away with buying the cheapest iPhone you can find that supports the latest iOS. At the time of this writing, it's possible to get a refurbished 1st generation Apple Watch Ultra for around $500 and a refurbished iPhone 11 for around $200. So this entire setup costs a lot less than a high-end iPhone, and I would honestly pay more money to have a setup like this that can curb internet addiction.

The setup #

I have a 1st generation Apple Watch Ultra paired with a hand-me-down iPhone 11. I wear my Apple Watch all day, and charge it every night when I go to bed. I keep the iPhone at home under my desk 99% of the time. When I am working at home, I use my 14-inch MacBook Pro laptop for anything internet related, with Handoff set up so I can answer texts and phone calls from my MacBook itself. If I'm at home not near my laptop, I can respond to text messages or phone calls directly from my watch.

You might think that using the internet on a laptop isn't that much different than using the internet on a phone, but I've found the difference to be profound. If you want to simplify it, a phone is optimized for consumption (with a touch-based interface), and a laptop is optimized for creation (with a keyboard-based interface). While you certainly can consume media on a laptop, it isn't designed to steal every moment of your attention the way a phone is. If you go to the bathroom, you won't take your laptop with you to watch a couple of quick videos. That example alone should give you an idea of how different the two devices are in this regard.

When I leave the house, the phone stays at home, the watch switches to cellular. On cellular, I can use my watch to take phone calls and text messages, check email, receive Slack notifications, use Apple Maps for directions, and listen to music or podcasts (I have my AirPod Pros on my keychain so I access to anything audio related when I'm out). It's worth noting that even though the cellular watch works untethered from a phone, you still need to have your phone on for certain features to work. This includes sending and receiving texts, as well as notifications from apps that don't have a watchOS app like Slack (read more here).

According to Apple, the Apple Watch Ultra has a 36 hour battery life with typical use (connected to an iPhone via Bluetooth 28 out of the 36 hours). If it's not connected to an iPhone at all, the watch runs on cellular which has an 18 hour battery life. Either way this is good enough to last all day if you charge it every night. I work from home full time, but if you work at an office I would suggest taking your phone with you to work (but keep it tucked away somewhere you won't use it). Your watch will tether to your phone during the day, leaving plenty of battery for the evening if you go out. I almost never use more than 50% of the battery on a daily basis, which means I never need to worry about running out of battery and finding a charger. That alone is kind of a game changer.

Not all Apple Watch apps work on cellular. Apple's default apps generally work - Mail, Calendar, Reminders, Maps, Music, and Podcasts all work great in my experience. I never used Apple Mail or Calendar before starting this experiment, all my work stuff is on Google accounts. But I was able to sync everything up to Apple Mail and Calendar, which has worked without major issues (more details below). I used to rely on Google Maps for navigation, but switching to Apple Maps has been a pleasant surprise. The quality of navigation directions has been equal to or better than Google Maps (although I heard it does depend on whether or not you live in a major city), and the Apple Maps interface on the Apple Watch is really good considering its small screen size.

Potential dealbreakers #

There are certain apps that don't work on cellular at all. Probably the most notable is the lack of ride-share apps like Uber and Lyft (both of which used to have Apple Watch apps but are no longer supported). My workaround is to simply take my phone with me when I'm going anywhere I think I'll need a ride-share. I definitely carry my phone in my pocket if I'm traveling out of town, but other than that I personally don't need a ride-share that often. There are other workarounds as well. You can keep the phone number to a taxi company handy. More recently, Uber offers a service for seniors to request an Uber by making a phone call, without using an app (I haven't tried this, but it certainly seems like a viable option).

The other big thing you'll be missing without your phone is a camera. I personally don't take a lot of photos, so this doesn't really affect me, but I can understand how it can be a dealbreaker for a lot of people. One workaround is to carry a separate camera, whether it's a compact point-and-shoot, maybe an analog camera for some old-school charm, or a modern vlogging camera like the DJI Osmo Pocket 3 (which is in some ways superior to the best iPhones for stabilized video). Basically, if photography is important to you, this can be a way to explore the hobby beyond the phone. But as they say, the best camera is the one you have with you, so you'd have to make a commitment to carrying a separate device on a regular basis.

Another issue with not having a camera when you're out and about is QR codes. Lots of restaurants have adopted using QR codes instead of physical menus. In general, I haven't found this to be a deal breaker, since I'm usually with other people in those situations. Also lots of restaurants will provide a physical menu if you ask for one. You can also try to use Siri to search for the restaurant's menu online, but this is pretty hit-or-miss. Overall, not a deal breaker for me, but definitely worth noting.

Finally, there are other apps you might use that don't offer an Apple Watch app at all. Slack is the biggest one for me. This isn't as big an issue as you might think, since you can still receive watch notifications for new Slack messages, and you can respond to messages in a notification. What you can't do is read prior messages or send a new message. For me, I don't need to do those things when I'm away from my computer, but I can definitely see this potentially being a problem for others.

The result #

Despite the limitations mentioned above, I've been living without a phone for over a year and have no intentions of going back. This setup absolutely solved the problem of filling empty moments in my day with mindless scrolling. I am now aware of the feeling of boredom in these moments, which allows me to be more present to observe my surroundings or just let my mind wander. The difference wasn't immediately noticeable - I wouldn't say I've changed in a profoundly spiritual way. But in the last couple of months I've been writing and coding more, and I would definitely attribute that to allowing my mind to be bored and inspired to do creative things.

I do want to stress again that I still spend a good amount of time mindlessly scrolling on sites like Reddit and YouTube - it's just taking place on my laptop instead of my phone. What ends up happening is that time is now contained, through no particular planning on my part. I'll do some mindless scrolling on my laptop first thing in the morning, then I'll start working. It's weird, but when I use my laptop, it's as if my work distracts me from my mindless scrolling, instead of it being the other way around. I never thought too much about how the form factor of a phone makes such a difference. Because a phone lacks a dedicated physical keyboard, doing prolonged work on it is almost impossible. So once you start mindlessly scrolling on a phone, there's nothing productive to distract you from that behavior.

I still use my phone in specific circumstances. As I mentioned above, if I'm heading out by myself and I know there isn't a good public transit option to get back home, I'll take my phone with me to be able to use an Uber or Lyft. If I'm out of town on vacation, I definitely take my phone with me, both for ride-share options as well as having access to more features on Maps (searching for nearby places, reviews, offline maps, etc). Occasionally I'll need the camera to scan a document. Basically I use the phone as a tool, not an entertainment device. To keep this distinction clear, I would recommend keeping the phone somewhere where you won't be tempted to use it. The hardest habit to break was mindless scrolling at night to help me fall asleep, so I think ideally you should keep it somewhere far from your bed. This allows your phone to become a tool that is used only when needed.

I don't know if I would recommend this Apple Watch Ultra setup for everyone. It works best if you are already deep in the Apple ecosystem and the potential dealbreakers I described above aren't dealbreakers for you. There are lots of alternative approaches that can work. Android users can find an LTE smartwatch that is compatible with that ecosystem. You can get a smart watch without cellular, and keep your phone near you but in a place that is harder to access. You can get a dumb phone to use for messaging and phone calls only. At the time I started this experiment, the dumb phone options seemed very limited, but I do think it's a growing space and there will be new devices that sit between a dumb phone and a smart phone. I think conversations around internet addiction and the war on our attention are becoming mainstream enough for a market to emerge that allows different people to address this issue in different ways that work best.

Detailed notes #

If case you want to try my specific approach of using the Apple Watch Ultra as a phone replacement, I've documented some notes on the apps that I use the most on my watch.

Messages: The default Messages app works great, even on cellular. It's obviously harder to type messages on a watch, but I find that voice dictation works really well, a lot better than I expected. I also set up some default replies which is more useful on a watch compared to an iPhone.
Phone: I don't take phone calls that often, but the call quality on the Apple Watch Ultra is definitely good enough in a pinch. I carry AirPod Pros on my keychain, but even without headphones you can have a quick conversation without any issue, even with some outside noise. I do notice that the cellular connection isn't perfect - I never have an issue sending or receiving texts, but sometimes I'm unable to make phone calls, which is weird. Obviously your mileage may vary, but something worth noting.
Email: I synced my work and personal Gmail accounts to the default Apple Mail app. I don't use the Mail app on my MacBook at all, I still use the GMail web interface which works fine for me. I only use the Apple Mail app on my watch, which works well for checking emails. You can compose emails too - it's not the worst experience if you use voice dictation, but obviously not the best experience either. This works to my advantage, since it stops me from doing too much work away from my computer, and I can still send an email if an emergency somehow arises. I also started practicing inbox zero, which makes it even easier to check for emails on a small watch screen.
Calendar: I synced my work Google Calendar to the default Apple Calendar app. I actually wasn't able to do this at first, because I had almost a hundred separate calendars in my Google account, and it took too long to sync to Apple Calendar. I don't think most people will run into this problem - in my case I made calendars for different classes I teach, which I don't need after a class ends, but I don't want to delete and end up with broken links. What I ended up doing is unsubscribing from each Google Calendar, but before doing so I saved each "Secret address in iCal format" in a note in case I need to resubscribe and manage a calendar. Once I got my calendars down to a reasonable number, I was able to sync with Apple Calendar without any issue.
Reminders: I started using Apple Reminders for all my todos. I'm actually trying to move as much information as possible into Apple Reminders, since I find that it meets most of my needs. I have Smart Lists for scheduled todos and unscheduled todos, and I have other lists for things like groceries, gifts, interesting articles, etc. If I'm browsing the web on my MacBook and come across an interesting article, I share it with Reminders (so it's essentially my "read it later" app). One of the best things about Reminders is how well it works with Siri. Saying something like "remind me in 45 minutes to pick up the laundry" or "remind me when I get home to check the mail" is faster than typing it out and configuring a time or location.
Notes: There is no Apple Notes app for watchOS, which is pretty weird. It's easy enough to work around, if you have an idea while you're out and about you can just make a reminder, then move it into a note when you get home. But you won't be able to read notes, so that's something to consider if you have notes you need to reference. You can move some of that information into Reminders (which is what I did), or you can use a third party app (Drafts is an excellent choice here, as it syncs across macOS, iOS, and watchOS using iCloud).
Maps: I switched from Google Maps to Apple Maps, and I've been really surprised with how far Apple Maps has come. For walking or driving directions, I find it to be every bit as good as Google Maps. Probably the biggest downside is that Apple Maps uses Yelp for reviews, which are not nearly as good as the reviews within Google Maps. Also Google Maps has better features for different things like booking hotels - but this is only relevant when you're using it on a computer or phone, not on a watch. So if I'm doing certain tasks on my computer like researching places for a vacation, I'll use Google Maps, but I'll save the places I want to visit in an Apple Maps Guide, which I can easily access from my watch at any time.
Music: I got a subscription to Apple Music, which costs a little over $10 a month. You can download music onto the watch itself, so you don't use data or need an internet connection to listen to music away from your phone. I used to pay for Spotify, then I switched over to YouTube Music (which comes free with a YouTube Premium account), and now Apple Music, so it's something I've been willing to pay for. It's nice to be able to listen to music on the go, but I actually find that I listen to podcasts way more than music, so you may be able to skip this and save some money.
Podcasts: I use the default Apple Podcasts app, which is a bit lacking in terms of configuration but it works well enough for my needs. I subscribe to different shows, then configure how many episodes to automatically download for each show. That way when I'm not tethered to my phone, I will have plenty of podcasts to listen to, even in places with poor cellular connection. If you want more customization options, many people swear by Overcast as a better podcast experience, and it does have a watchOS app. For me the default Podcasts app works well enough, but you do have options.
Home: I started adding home automation devices to my place, so far I have lights, window shades, a thermostat, and a front door lock. All of this can be controlled from my watch using the Home app, which is convenient. I almost never use the app itself, it's easier to use Siri. In general, I find Siri is pretty mediocre, but controlling home automation is an area where it's pretty good. If you're just getting started with home automation, then you should make sure to buy devices specifically compatible with HomeKit if you're staying with the Apple ecosystem. (All of my devices are HomeKit compatible except for the Nest thermostat, which came with my unit. I had to set up a Homebridge server on a NAS to make it compatible, which works reasonably well, but that's a topic for a different post).
Apple Wallet: Not much to say here, if you have a credit card set up in Apple Wallet, Apple Pay works perfectly from a watch, even without a cellular connection. I set up my transit card with Express Mode, so I can tap my watch to get on a train or bus without having to open or find anything on my watch. Between this and a smart lock, I basically don't need to carry a wallet or keys with me when I head out. I still carry both just in case, but 95% of the time the watch is all I need, which is pretty liberating.

Designing a 36-key custom keyboard layout

2021-03-29T00:00:00Z

GergoPlex keyboard by g Heavy Industries

Background #

Once you get into the world of custom mechanical keyboards, then you'll eventually run into keyboards with what looks like an impossibly small number of keys:

Ergonomic keyboard collection by u/chamzter22 from r/ErgoMechKeyboards

At first it may seem there is no good reason to build a keyboard like this, other than for aesthetic purposes or bragging rights. However, there are valid arguments to be made for reducing the number of keys on a standard keyboard. If you've ever tried to learn touch typing, then you were taught the importance of keeping your fingers on the home row. Yet there are many keys that force your hand to move off the home row. Even the number row can be hard to reach for people with smaller hands.

Here's the layout of a typical 78-key Mac keyboard, with the home row highlighted in green and all the keys that can take you off the home row highlighted in red:

Your mileage may vary depending on how long your fingers are, but there certainly a surprising number of important keys that require a significant stretch. This is why many ergonomic keyboards are designed with fewer keys, from the 48-key ortholinear Planck, to the 42-key split columnar Corne, to the 36-key split columnar GergoPlex. (You can of course design a keyboard with even fewer keys, but I would argue 36 keys is about the limit for a normal typing experience using the English alphabet.)

So what happens to all the keys that you lose with these smaller keyboards? The answer is to use custom keyboard firmware with layers. In same way you can hold the Shift key to access special keys keys like !, @, #, etc., you can create custom layers to access those missing keys. This does require you to memorize a whole set of inputs and potentially relearn years of muscle memory. However, it is possible to design a layout that minimizes this learning curve by following a set of principles, which we'll look into next.

Prior art #

If you're looking for a 36-key custom keyboard layout, a commonly recommended one that I've come across is the Miryoku layout:

That looks intense! Each thumb key activates a different layer for a total of 6 layers, so there's a lot to get used to. Furthermore, the Miryoku layout uses home row mods - the Super, Alt, Ctrl, and Shift keys are on the home row instead of the thumb keys. For example, if you hold down the T key, it will work as the Shift modifier. If you tap it instead, the letter T will output instead. This definitely makes sense in theory, as your fingers are always on the home row. In practice, it'll take some tweaking to get it to work well, as there can be timing issues where sometimes you want the modifier to activate, sometimes you want the letter to activate. This article goes over home row mods and the necessary tweaks to make it work well in meticulous detail.

Another alternative to managing the available keys is to use combos:

This is the default layout of the GergoPlex keyboard, described in detail here. Instead of using many different layers, this layout uses combo keys to activate different symbols. For example, pressing S and D simultaneously will trigger a Backspace, pressing J and K together will trigger a colon, etc. This provides a lot of interesting opportunities; however, there can be timing issues similar to home row mods. Also, pressing combos can be tiring if you happen to use heavy key switches.

In order to build these types of layouts, you'll need to program your own keyboard firmware. A popular open source keyboard firmware project is QMK, which allows you to program layers, combos, and many more features that enable you to map all the keys necessary to a 36-key custom keyboard. (You can get an overview of how to use QMK in my previous article.)

My design constraints #

Many people have found success with variations of the layouts described above. However, they didn't fit my particular needs, so I wanted to design something from scratch. Basically, I want to be able to switch between my 36-key custom keyboard and my normal laptop keyboard without issue. This doesn't seem to be a problem for some people, but for me, I noticed that I made a lot of mistakes reaching for the wrong keys when I switched between these different layouts. Keeping that in mind, these were the design constraints I used for my keyboard layout:

Avoid relocating keys whenever possible #

I found this to be essential if I wanted to switch between my custom layout and a standard keyboard. Many people redesign their layouts completely, using Dvorak, Colemak, or other non-QWERTY layouts. Which makes sense if your goal is to optimize ergonomics as much as possible. But that's not my goal - to me, reducing the key distance from the home row is ergonomic enough. My goal is to optimize other factors, namely minimizing the learning curve and minimizing the difficulty switching to a standard keyboard.

Keep any relocated keys on the same side they came from #

What this means is that the Escape key, which has to be relocated on a 36-key custom keyboard, will stay on the left side of the keyboard, the Enter key will stay on the right side of the keyboard, etc. This helps avoid any conflicts with keyboard shortcuts that involve two different hands (for example, Command Enter, which normally uses two different hands, would be difficult to execute if the Enter key was moved on the same hand as Command). I think this also helps with muscle memory, at least when I was experimenting. I tried moving the Tab key to the right hand, and my brain wasn't having it - moving it back to the left hand felt way more intuitive, even though it was a different position than normal. Again, your mileage may vary.

Avoid overloading commonly used letter keys #

When making custom keyboard firmware, you can program any single key to have multiple functions. The A key can be programmed to send A when tapped, send Control when held, send Tab when double-tapped, etc. This is an essential part of making a 36-key custom keyboard feasible. However, certain keys work better than others. Overloading the A key as in this example can cause errors when you type quickly - when you type "as", it may register as Control-S or "as" depending on how quickly you release the A key. You can tweak the firmware timings, but I'd rather avoid the issue altogether by not overloading these commonly used letter keys if at all possible.

Minimize the number of layers #

Some people find it effective to have many different layers, each with specific responsibilities. I tried this, but it didn't click for me to learn all these layers up front. Instead of making many single-purpose layers, I was able to make a single additional layer that contained all the commonly used symbols and navigation keys that didn't fit on the base layer. This made it easy for me to learn, as it helps you avoid having to remember what key was in which layer and activating the appropriate layer each time. Once you get used to a layout, it can definitely make sense to add additional layers, but this is a good constraint to start with in my experience.

Use mnemonic devices for positioning layer keys #

There are 78 keys on the standard Mac keyboard pictured above. That means for a 36-key custom keyboard, you need to memorize the positions of 42 keys that don't fit on the base layer. That's a daunting task, unless you have some mnemonic devices to aid your memory. For example, many layouts I've seen have the number keys rearranged to a numpad style formation. This is pretty cool, but it's more stuff to memorize up front. It's easier to start with the number keys in a layer directly across the top row, which is just one row down from where they are normally located. Similarly, the F1-F10 keys can go on a separate layer at the same positions - again, easy to memorize. Now we already have 20 out of the 42 keys taken care of with minimal effort! We can place the remaining keys in layers using similar mnemonic devices to keep the learning curve to a minimum.

These design constraints eliminated a lot of arbitrary choices, and led me to a keyboard layout that I'm pretty satisfied with.

My layout #

Here's the layout I created for a 36-key custom keyboard using the above design constraints:

(This layout was designed specifically for Mac modifier keys, but it shouldn't be hard to adjust for Windows or Linux.) Nearly every key towards the middle of a standard keyboard are kept at their original positions. All relocated keys stay on the same hand. The layout doesn't overload any commonly used letter keys. There are only 2 additional layers (and all the commonly used symbols are on the first layer). Let's look over each layer in detail.

The default base layer #

/* Layer 0: Base keys
 *
 * ,-----.-----.-----.-----.-----.                      ,-----.-----.-----.-----.-----.
 * | Q   | W   | E   | R   | T   |                      | Y   | U   | I   | O   | P   |
 * |-----+-----+-----+-----+-----|                      |-----+-----+-----+-----+-----|
 * | A   | S   | D   | F   | G   |                      | H   | J   | K   | L   | ' " | 
 * |-----+-----+-----+-----+-----+                      |-----+-----+-----+-----+-----|
 * |SHF/Z| X   | C   | V   | B   |                      | N   | M   | < , | > . |SHF/?|
 * `-----'-----'-----'-----'-----'                      `-----'-----'-----'-----'-----'
 *               .-------.-------.-------.      .-------.-------.-------.   
 *               |OPT/ESC|  CMD  |CTR/TAB|      | ENTER |L1/SPC |L2/BSP |
 *               '-------'-------'-------'      '-------'-------'-------' 
 */

The base layer is nearly identical to a standard layout, with Option, Command, and Space keys in the exact same positions (I happen to use my right thumb to hit space, but you can overload the left Command key to be space if you do the opposite). The Shift keys are in approximately similar positions (overloading infrequently typed letters, which works out perfectly). I did replace the semicolon key with the quotes key, because it is so frequently used, but this is an optional modification.

The Escape and Tab keys had to be relocated, so they now controlled by the left thumb. Same with the Enter and Backspace keys for the right thumb. Using your thumbs for these keys is a downright liberating experience. Those keys are used constantly throughout any work session, and you don't realize just how much your hands have to move hitting those keys until you bring them to a more usable position.

There is one downside to this layout - with the Tab key next to the Command key, it's difficult to hit Command Tab, an essential keyboard shortcut on a Mac. We'll come back to this at the end.

The symbols layer #

/* Layer 1: Symbols
 * ,-----.-----.-----.-----.-----.                      ,-----.-----.-----.-----.-----.
 * | 1!  | 2@  | 3#  | 4$  | 5%  |                      | 6^  | 7&  | 8*  | 9(  | 0)  |
 * |-----+-----+-----+-----+-----|                      |-----+-----+-----+-----+-----|
 * | `~  |HOME |PGUP |PGDN | END |                      |LEFT |DOWN | UP  |RGHT | ;:  |
 * |-----+-----+-----+-----+-----+                      |-----+-----+-----+-----+-----|
 * |SHFT |     |     |     |     |                      | -_  | =+  | [{  | ]}  |SHF\||
 * `-----'-----'-----'-----'-----'                      `-----'-----'-----'-----'-----'
 *               .-------.-------.-------.      .-------.-------.-------.   
 *               |       |       |       |      |       |(hold) |       |
 *               '-------'-------'-------'      '-------'-------'-------' 
 */

This layer is activated by holding down the right thumb middle key. Every commonly used symbol, including numbers and arrow keys, are on this layer. Most layouts I've seen have a separate layer for numbers and symbols. This seems to work for most people, but when I personally tried this, it messed with my head too much. I'm used to holding shift to get an !, which is how this layout works. Keeping my muscle memory and reducing the number of necessary layers is a win-win in my book.

I have Vim-style arrow keys here on the right hand home row, which is what I'm used to. If you're already comfortable with Vim, this is a great layout; if not, you may need to make some modifications (or spend some time learning Vim if you're so inclined). You can optionally add HOME/END/PGDN/PGUP keys on the left hand - these are less crucial, so experiment with rearranging them to something that makes sense for you.

The biggest learning curve is getting used to the remaining symbols that lost their dedicated keys (-_, =+, [{, }], and \|). I basically moved this cluster of keys to the bottom row of the right hand in order. The easiest way to remember this is to use some mental anchors. The open [{ key is at the same position as the base layer open <, key, and the close }] key is at the same position as the base layer close >. key. Also, the backslash \| key is at the same position as the base layer forward slash /? key. If you can remember those, then the only two left are the -_ and =+ keys at the remaining two positions. Again, you access the shifted versions of each of these keys by holding on shift as you would normally, so nothing new to remember there!

The function layer #

/* Layer 2: Function keys
* ,-----.-----.-----.-----.-----.                      ,-----.-----.-----.-----.-----.
* | F1  | F2  | F3  | F4  | F5  |                      | F6  | F7  | F8  | F9  | F10 |
* |-----+-----+-----+-----+-----|                      |-----+-----+-----+-----+-----|
* | F11 | F12 |PREV |PLAY |NEXT |                      |MUTE |Vol- |Vol+ | Br- | Br+ |
* |-----+-----+-----+-----+-----+                      |-----+-----+-----+-----+-----|
* |     |     |     |     |     |                      |     |     |     |     |     |
* `-----'-----'-----'-----'-----'                      `-----'-----'-----'-----'-----'
*               .-------.-------.-------.      .-------.-------.-------.   
*               |       |       |       |      |       |       |(hold) |
*               '-----------------------'      '-------'-------'-------' 
*/

This layer is activated by holding down the right thumb right key. I use this layer far less frequently than the symbols layer, but every function key is accounted for with room to spare. It's easy to remember the function key positions, as they are mentally anchored to the number key positions. You can optionally add volume controls, brightness controls, media keys, and any other miscellaneous keys as well - there's plenty of room.

Custom code #

I mentioned earlier that the only downside I found to the base layer was the difficulty in hitting Command Tab, which is a critical keyboard shortcut on the Mac. My solution to this is an odd one - I overwrote the keyboard shortcut to Command Q to be Command Tab instead, at a firmware level. It's worth mentioning that even before I started making this keyboard layout, I had disabled Command Q on my Mac (I was tired of accidentally quitting a program and losing all my tabs went I meant to enter Command W). So I didn't need this keyboard shortcut, and it is the closest physical location to Command Tab on a normal keyboard layout.

Here's the code to overwrite Command Q to be Command Tab using QMK if you're curious:

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  switch (keycode) {
  case KC_Q:
    if (record->event.pressed) {
      if (keyboard_report->mods & MOD_BIT(KC_LCMD) || keyboard_report->mods & MOD_BIT(KC_RCMD)){
        register_code(KC_TAB);
        return false;
      }
    } else {
      if (keyboard_report->mods & MOD_BIT(KC_LCMD) || keyboard_report->mods & MOD_BIT(KC_RCMD)){
        unregister_code(KC_TAB);
        return false;
      }
    }
    break;
  }
  return true;
};

To me, this is the perfect solution to my problem; however, I get that this may not be ideal for a lot of people. The good thing is that you have a lot of other options if you're using QMK. You could use tap dance to make double-tapping Q output a Tab key, or you could make a combo for QW to output a Tab key, or you could put Tab on some layer that's easily accessible, etc. There are endless possibilities when programming your own keyboard firmware; just be careful to keep these types of customizations to a minimum until you get used to your basic layout.

Next steps #

This layout has a lot of room for further customizations. There are many unused keys on the two additional layers, and there are keys available on the base layer to activate new layers if you're so inclined (the right thumb Enter key and the right pinky semicolon key are two good options). You could assign the right thumb Enter key as a Hyper key instead, which could be useful for other system-wide keyboard shortcuts.

If you're just getting started in the world of custom keyboard firmware, I'd recommend reading my previous post to get an overview of making a custom keyboard with programmable firmware. If you're looking to purchase a 36-key custom keyboard, there aren't too many vendors that mass produce them, as it's a pretty niche market. The Keyboardio Atreus is one of the more affordable mass produced options that can fit the bill; it's got more than 36 keys, but it should work well with this layout, and you can use the extra keys as you see fit. Otherwise, you can purchase parts or prebuilt options from smaller vendors who will make it to order, which will take more time. A good place to get advice is the /r/ErgoMechKeyboards subreddit, where they have a sticky to help you find the exact keyboard that meets your needs.

If after reading all this, you're not convinced it's worth it to switch to a 36-key custom keyboard, then I would definitely stick with your current preference. The ergonomics are a definite plus for some people who experience wrist or joint pain, but for most people this is probably not an issue. I would recommend getting into ergonomic keyboards the same way I would recommend someone to learn Vim; it should be because you enjoy spending time learning and mastering a complex skill, like learning a new musical instrument.

If you're already using a small keyboard with minimal keys, it's worth restating that I don't believe my layout is the best layout for everyone. If you've spent the time to master non-QWERTY layouts, home row mods, combos, or other advanced features, then you should use a layout that takes full advantage of your knowledge. But I do believe this layout is ideal as a starting point for most people, as it gives you the ability to be productive in the shortest amount of time. Once you feel comfortable with this layout, then you should definitely add more features incrementally, which is half the fun of building your own keyboard. Hope you find these tips useful on your journey!

Your First Custom Ortholinear Keyboard

2021-02-05T00:00:00Z

Custom ortholinear keyboard by u/ImportedGuy from r/mk

If you're a person who types on a keyboard for most of the day, then you may have come across the world of custom keyboard enthusiasts. One notable keyboard community is Reddit's mechanical keyboards subreddit, where you'll find a dizzying array of customization options, from switches to keycaps to keyboard layouts. Some of these customizations are purely cosmetic, some are in search of a particular tactile or aural aesthetic, and some are for improved ergonomics.

Staggered vs Ortholinear Layout #

One interesting customization from the world of custom keyboards is an ortholinear layout. An ortholinear layout has all the keys organized in a straight up and down grid, as opposed to the staggered layout of traditional keyboards.

Here is a traditional staggered keyboard layout:

Note the color coding based on finger positions. For proper touch typing, each finger is responsible for a certain set of keys. What's odd is due to the staggered nature of the keyboard, these sets of keys are all on a slant. This makes it a little tricky to learn. For example, the right index finger rests on the J key, and is responsible for the number 7. But you can see that 8 is the number key directly above the J key, which can create some cognitive dissonance. So why do most keyboards use a staggered layout? It's because they were modeled after old-school typewriters, which needed the staggered layout to make room for each hammer:

So most modern computer keyboards are designed with this staggered layout due to path dependency; it's just what people are used to. Once you realize this, it's hard not to ask the question "What would it be like to use a keyboard without any staggering?"

Enter the ortholinear layout:

From what I can tell, the term "ortholinear" was invented by Jack Humbert, who created the Planck keyboard described in the video. The Planck may not have been the first non-staggered keyboard on the market, but it was very influential in the relatively small world of custom keyboard enthusiasts. Originally you would have to buy keyboards like these as a kit, which required soldering and assembly to complete. Now there are quite a few pre-built ortholinear keyboard options to choose from - there's the minimalist Planck EZ, the ergonomically curved Kinesis Advantage, the fully-split Moonlander, etc. Prebuilt options are quite pricey, since it's a small market, so if you wanted to save money you could build your own from the individual components.

The ortholinear learning curve #

Before getting into how to build a custom ortholinear keyboard, it's worth mentioning the learning curve. I've come across multiple reviews of different ortholinear keyboards where the reviewer said the layout change was too much of a learning curve, and they prefer the staggered layout. Here are some example video reviews which discuss just how difficult the switch can be:

This wasn't at all similar to my experience with my first ortholinear keyboard. It took me about a day before I was just as fast on my new keyboard, and I was also able to switch between an ortholinear layout and my laptop's staggered layout without any issue. This is because my first ortholinear board was the XD75re, which has plenty of keys (5 rows and 15 columns), so I was able to create a layout that was nearly identical to a traditional keyboard.

First let's look at the default layout on a Planck keyboard:

The Planck has 4 rows and 12 columns, which means you're missing your number row and a lot of symbols. In order to type numbers, you'll need to hold down the Raise key, which activates the color-coded layer. Other symbols require holding the Lower key. The reasoning here is to keep every single key no more than one key away from your home row position, which is ideal from a touch typing perspective. But there is a huge learning curve involved with switching to a keyboard like this! The Planck allows you to customize your layout any way you want, but in the end you'll have to relearn where your numbers and symbols are located using several layers.

Now let's look at a layout on the XD75re:

This layout uses 14 columns, with extra keys left over to customize as you see fit. The only key that is moved is the escape key, which I moved to the normal location of the caps lock key (you can actually customize this keyboard's firmware such that the key is control on hold, escape on release). The most important thing is that you aren't required to use any layers to access your numbers or symbols (except for your function keys, which can map directly on your number keys).

Notice that the space bar takes up a huge number of keys, which isn't necessary. If you are okay with moving 2 more keys around, you could have a layout like this instead:

This layout uses 13 columns, with 2 extra columns in the middle and a couple of unused keys on the bottom to customize as you see fit. The extra two columns in the middle creates some space between your hands, which I find to be a little more comfortable. Only 3 keys are out of their normal positions, so it's pretty easy to get used to this layout. The point is that this particular keyboard gives you the flexibility to start with a traditional layout so you can focus on getting used to a non-staggered ortholinear layout. Once you feel comfortable, you can customize your layout to your heart's content!

If you're interested in trying an ortholinear layout, I would suggest trying a keyboard with labeled keycaps and at least 5 rows and 13 columns. Most available ortholinear keyboards have 12 columns, which keeps things symmetric (6 columns for each hand), but immediately requires repositioning several symbol keys on layers. You'll have a much easier time learning an ortholinear layout if you don't have to memorize new layer layouts at the same time. You can always add layers and optimize your layout with a larger keyboard as well, so it's a win-win!

Building a keyboard from scratch #

The only downside with the XD75re is that it does not come as a prebuilt keyboard, you'll need to source your own parts and assemble it yourself. Fortunately, this is all a lot easier than it sounds, because the XD75re board has all components already soldered on it. This means all you need to do is purchase the right parts and put it all together, no wiring or soldering necessary!

This video by Taeha Types does a good job of breaking down all the possibilities when it comes to building your own mechanical keyboard:

This particular build is as simple as it gets, since the XD75re is a hot-swap PCB, which means you don't need to solder any components. It is compatible with either PCB or plate-mounted switches, which makes it easier to find switches. And since every key is only 1 unit in size, you don't need any stabilizers. All you need to do is assemble the pieces. Here's what you need for this XD75re build:

PCB (KPRepublic sells the XD75re)
Case (the XD75re can theoretically fit in any 60% case, this one is specifically built for the XD75)
Switches (the XD75re uses MX switches, sold by NovelKeys, FlashQuark, many others)
Keycaps (you'll need uniform-profile MX keycaps with all 1u sizes, like this)
Plate (sometimes optional, the case linked above has a built-in plate)
Cable (the XD75re uses a USB C cable)

You can follow this build log by /u/snowypowers to see how to assemble this exact board with this exact case:

XD75 Re Build Log

One thing to note - I have this exact case, and the screws it came with were too short. This is probably because the case was made for the XD75 and the XD75re PCB, the latter being a little taller in height due to its hot-swap sockets. I had to purchase some longer M2 screws, which cost less than a dollar total. Easy enough fix, but something to be aware of.

The total cost of this build will be somewhere between 100 and 200 USD. Which is a pretty reasonable price for a custom keyboard, but definitely pricey compared to something you can buy at a store, no doubt. And this particular PCB is sold by KPRepublic, a store located in China, which means it will take more than a month to receive your package (I believe my order took about 2 months to ship to the US in Chicago). I had a great experience with KPRepublic and have ordered from them multiple times, but you can't avoid the long wait times for certain products like these, which are manufactured by small local vendors and not large corporations. Building custom mechanical keyboards is a great hobby, but it's characterized by long wait times and potentially expensive purchases. If that's unappealing, then turn around before it's too late! Otherwise, let's take a look at the last piece of the puzzle - programming your new keyboard.

Customizing the keyboard firmware #

The XD75re can be customized using the QMK firmware, which is an open source keyboard firmware project that enables complete customization of your keyboard. If you are a programmer, you can write custom C code to program your keyboard down to each keypress. If you are not a programmer, no worries - they provide an online graphical configuration tool which is much more user friendly. This tutorial by MechMerlin walks you through every step:

This is the fun part - you have complete control of the layout and functionality of each key. You can have dedicated buttons to control volume, brightness, and media playback. You can customize a key to be Control on hold, Escape on release, as I mentioned earlier. Literally every key can have a wide range of functionality. To start, I'd recommend keeping things simple, but once you get the hang of your layout, it's a lot of fun to revisit it and try to optimize it for your tastes!

Once you create your firmware using this online tool, you will need to load the compiled code onto your keyboard, a process known as flashing your keyboard.

Flashing the XD75re the first time is tricky, because it doesn't come with a reset button. The product page links to some documentation which is pretty unclear, as the instructions are for some firmware other than QMK. However, the first step is all you need - when your board is plugged in and ready to be flashed, you can reset the board by using paperclips or tweezers to short the two pins labeled in the picture:

If you're using the case from the steps above, you can see a cutout at the top of the case that gives you access to those specific pins at the exact center of the board (if you remove the keycaps). This is kind of an annoying process, but fortunately you don't have to do it often. When you design your keyboard layout, you can choose one of your keys to be a reset key. I would recommend putting it behind a layer so you don't press it accidentally. Once it's set, you can reset your keyboard with a key combination instead of having to remove those middle keys and short the pins from the top, which is a lot more convenient.

Conclusion #

If you are used to purchasing pre-built keyboards, the world of custom mechanical keyboards can certainly seem daunting. However, if you're willing to be patient through the different steps of choosing parts, assembling the keyboard, creating a layout, and flashing the firmware, then I definitely believe the payoff is worth it. If a Jedi constructs their own lightsaber from scratch, then anyone who uses a computer all day for a living should consider doing the same for their keyboard.

If you're interested in entering the world of ortholinear keyboards specifically, the XD75re PCB is pretty hard to beat, since it has plenty of buttons to avoid memorizing layers, it has compatibility with different types of switches, and it is hot-swappable so you can change switches without having to do any soldering. A lot of enthusiasts enjoy optimizing their layouts to use as few keys as possible, but starting with too many keys is the way to go, since you can always learn to use fewer keys using the same board. If you do get into the hobby, I hope you find this information helpful to begin your journey!

New video course platform from Actualize!

2020-09-27T00:00:00Z

Featured courses from Actualize First Class: https://firstclass.actualize.co

Just wanted to announce Actualize First Class, the new video course platform from Actualize coding bootcamp! These courses will cover topics for developers at every experience level, from beginners at the very start of their developer journey (macOS for developers), to seasoned developers looking to deepen their understanding of specific technologies (OAuth 2.0 Deconstructed).

Right now courses include video versions of some of my most widely shared articles, Modern JavaScript Explained For Dinosaurs and Modern CSS Explained For Dinosaurs. There will be more courses to come, you can follow me on Twitter @peterxjang for any updates!

Modern HTML Explained For Dinosaurs

2018-11-14T00:00:00Z

Images from Dinosaur Comics by Ryan North

Out of the three main frontend technologies (HTML, CSS, and JavaScript), HTML has remained the most consistent. If your only concern was creating content, an HTML document from the 1990s would look pretty similar to one created in 2018:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>My test page</title>
  </head>
  <body>
    <h1>Hello there!</h1>
  </body>
</html>

You have elements with tags and content, tags with attributes — other than the simplified doctype on the first line, not much has changed! However, over the years web development has taken a dramatic shift from creating static web sites (with a focus on content) to creating dynamic web applications (with a focus on interaction)— something the web wasn’t originally designed to do. Creating custom user interfaces that are still semantic and accessible, improving performance using attributes and tooling, organizing code for reuse and maintainability — there are now a whole new set of concerns at play.

The goal of this article is to provide a historical context of how HTML has evolved to the language it is today in 2018. We’ll start with the fundamentals of well structured and accessible HTML, just like the dinosaurs of old. Then we’ll introduce different techniques to improve performance, responsiveness, and maintainability. CSS and JavaScript will inevitably make its way into this conversation; for the purposes of this article, they will be covered from the perspective of how they impact the writing of HTML itself. By understanding this history, you will be able to take full advantage of both old and new features of the language that can often be overlooked. Let’s get started!

Writing content with semantic elements #

Let’s add some more content to the earlier HTML example. For now we’ll make a basic website with a navigation section with links and a search input, a large showcase section for displaying general site info (often referred to as a hero section or jumbotron), three column sections for articles, and a footer section for copyright info.

<!DOCTYPE html>  
<html>  
  <head>  
    <meta charset="utf-8">  
    <title>My test page</title>  
  </head>  
  <body>  
    <div class="navbar">  
      <ul>  
        <li>  
          <a href="#">Home</a>  
        </li>  
        <li>  
          <a href="#">Info</a>  
        </li>  
        <li>  
          <a href="#">About</a>  
        </li>  
      </ul>  
      <form>  
        <input type="text" placeholder="Search">  
        <button type="submit">Search</button>  
      </form>  
    </div>  
    <div class="main">  
      <div class="hero">  
        <h1>Hello there!</h1>  
        <p>General info about the page goes here</p>  
        <p><a href="#">Learn more</a></p>  
      </div>  
      <div class="grid">  
        <div class="column">  
          <h2>First Heading</h2>  
          <p>Article content goes here</p>  
          <p><a href="#">View details</a></p>  
        </div>  
        <div class="column">  
          <h2>Second Heading</h2>  
          <p>Article content goes here</p>  
          <p><a href="#">View details</a></p>  
        </div>  
        <div class="column">  
          <h2>Third Heading</h2>  
          <p>Article content goes here</p>  
          <p><a href="#">View details</a></p>  
        </div>  
      </div>  
    </div>  
    <div class="footer">  
      <p>Copyright info goes here</p>  
    </div>  
  </body>  
</html>

Here we’re using basic elements with tags like <div>, <h1>, <h2>, <p>, etc., to mark the content. The HTML here works, but it’s not fully semantic — that is to say, the tags do not communicate the meaning of the content as well as they could.

When HTML5 was introduced in 2008, it provided new elements to improve document semantics. Here’s an attempt to make the HTML more semantic:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    <meta charset="utf-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">  
    <meta name="description" content="">  
    <meta name="author" content="">  
    <title>My test page</title>  
      <!--[if lt IE 9]>  
        <script src="(https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js"></script>  
      <![endif]-->
  </head>  
  <body>  
    <nav role="navigation">  
      <ul>  
        <li>  
          <a href="#">Home</a>  
        </li>  
        <li>  
          <a href="#">Info</a>  
        </li>  
        <li>  
          <a href="#">About</a>  
        </li>  
      </ul>  
      <form>  
        <input type="text" placeholder="Search">  
        <button type="submit">Search</button>  
      </form>  
    </nav>  
    <main role="main">  
      <section class="hero">  
        <h1>Hello there!</h1>  
        <p>General info about the page goes here</p>  
        <p><a href="#">Learn more</a></p>  
      </section>  
      <section class="grid">  
        <article class="column">  
          <h2>First Heading</h2>  
          <p>Article content goes here</p>  
          <p><a href="#">View details</a></p>  
        </article>  
        <article class="column">  
          <h2>Second Heading</h2>  
          <p>Article content goes here</p>  
          <p><a href="#">View details</a></p>  
        </article>  
        <article class="column">  
          <h2>Third Heading</h2>  
          <p>Article content goes here</p>  
          <p><a href="#">View details</a></p>  
        </article>  
      </section>  
    </main>  
    <footer role="contentinfo">  
      <p>Copyright info goes here</p>  
    </footer>  
  </body>  
</html>

Let’s examine some of the these changes:

The <html lang="en"> specifies the language of the document, which helps search engines and browsers identify the appropriate content.
The additional <meta> tags provides information about the site not directly visible on page, used by search engines and other services. They also provide information about how to size the content on different devices.
The <nav>, <main>, <section>, <article>, and <footer> tags provide more accessible structure to the HTML document (compared to generic <div> tags). These tags were introduced with HTML5.
The  comment adds a JavaScript file that only gets loaded for older versions of Internet Explorer, since they don’t support the above HTML5 tags. Note that many recent websites don’t include that comment these days, as fewer sites support those browsers.
The role attributes provide accessibility information as well. Note that using a <nav> tag generally is enough for accessibility, adding the extra role="navigation" is used in case the <nav> tag isn’t recognized.

Writing semantic HTML can seem unimportant, especially when it doesn’t affect the visual appearance of a website. However, your website is being viewed by more than just human beings — web browsers, search engines, screen readers all depend on semantic HTML to function properly.

Improving accessibility with WAI-ARIA attributes #

Let’s look at the search input in the navbar from our example above:

      <form>  
        <input type="text" placeholder="Search">  
        <button type="submit">Search</button>  
      </form>

This input element uses a placeholder attribute instead of a label element to let the user know its purpose. This works for humans, but it’s not properly semantic HTML, and can be missed by screen readers and other technologies. The way to make this accessible is to use an aria-label attribute:

      <form>  
        <input type="text" placeholder="Search" aria-label="Search">  
        <button type="submit">Search</button>  
      </form>

WAI-ARIA, which stands for “Web Accessibility Initiative — Accessible Rich Internet Applications” (often simply ARIA for short), is a set of attributes that makes HTML more accessible when semantic tags aren’t enough. The role attribute seen in the previous section is an ARIA attribute. So far these attributes seem like minor changes, but it becomes much more important as we use HTML for things beyond basic documents.

Let’s look at a more complex example — say we want to add some tabbed content in our HTML to provide instructions on how to install some program on Windows, Mac, and Linux. Since there’s no native way of building tabs in HTML, we have to make do with things like unordered lists, links, and divs to construct our own tab markup. Here we can use accessibility attributes such as role, aria-controls, aria-selected, and aria-labelledby to mark up the HTML, as seen below:

<ul role="tablist">  
  <li>  
    <a id="windows-tab" href="#windows" role="tab" aria-controls="windows" aria-selected="true">Windows</a>  
  </li>  
  <li>  
    <a id="mac-tab" href="#mac" role="tab" aria-controls="mac" aria-selected="false">Mac</a>  
  </li>  
  <li>  
    <a id="linux-tab" href="#linux" role="tab" aria-controls="linux" aria-selected="false">Linux</a>  
  </li>  
</ul>

<div>  
  <div id="windows" role="tabpanel" aria-labelledby="windows-tab">  
    <img src="http://1000logos.net/wp-content/uploads/2017/04/Microsoft-Logo.png" alt="microsoft logo">  
    ...  
  </div>  
  <div id="mac" role="tabpanel" aria-labelledby="mac-tab">  
    <img src="https://i.ytimg.com/vi/ipOzBWuYZvg/maxresdefault.jpg" alt="apple logo">  
    ...  
  </div>  
  <div id="linux" role="tabpanel" aria-labelledby="linux-tab">  
    <img src="https://noware.tech/wp-content/uploads/sites/140/2018/04/linux-1024x565.jpg" alt="linux logo">  
    ...  
  </div>  
</div>

Without these accessibility attributes, the tabbed content would have no discernible relationship with the tab controls. Having these attributes helps screen readers identify content, enables keyboard shortcuts with proper tabbing, etc. Using appropriate ARIA attributes can be a whole study in and of itself — for a deeper dive, check out the official guidelines.

All this may seem like a lot of work just to improve the accessibility of a website. It’s important to acknowledge accessibility as an integral part of the web, which was designed as a platform to freely share information with everyone, not just a select few. Making a website accessible improves the experience for every visitor — for example, accessible keyboard shortcuts help those who can never use a mouse, those who temporarily can’t use a mouse, and those who prefer to not use a mouse (a.k.a., most programmers). Accessibility can be easy to overlook when dealing with other features, but it should not be ignored.

If you’re interested in improving the accessibility of your website, there are checklists such as this one from the A11Y project, which is a great place to start. However, making a website accessible isn’t purely about checking off items — it’s something that can always be improved, like any aspect of user experience. The best way to make your website accessible is to actually use your website as different people in your audience would — test it out using a screen reader, try only using a keyboard instead of a mouse, view your website using a color blind filter, etc.

Making it pretty with CSS and JavaScript #

If we take a look at the website so far, it looks pretty bare as you would expect:

In order to spruce it up, we’ll add a CSS file to apply styling. Now if you’re not particularly good at CSS, it could take you many days to make this website look pretty. Instead of writing your own CSS, you could always use a CSS framework, which is essentially CSS that someone else wrote in a reusable manner.

One popular CSS framework is Bootstrap, which came out in 2011 and quickly became adopted and used by literally millions of websites. Let’s see what some of the code would look like using Bootstrap:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    <meta charset="utf-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">  
    <meta name="description" content="">  
    <meta name="author" content="">  
    <title>My test page</title>  
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">  
    <!--[if lt IE 9]>  
      <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js"></script>  
    <![endif]-->  
  </head>  
  <body>  
    <nav class="navbar navbar-expand-lg navbar-light bg-light" role="navigation">  
      <ul class="navbar-nav mr-auto">  
        <li class="nav-item active">  
          <a class="nav-link" href="#">Home</a>  
        </li>  
        <li class="nav-item">  
          <a class="nav-link" href="#">Info</a>  
        </li>  
        <li class="nav-item">  
          <a class="nav-link" href="#">About</a>  
        </li>  
      </ul>  
      <form class="form-inline my-2 my-lg-0">  
        <input class="form-control mr-sm-2" type="text" placeholder="Search" aria-label="Search">  
        <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>  
      </form>  
    </nav>  
    <main role="main"> 
      <!-- ... --> 
    </main>  
    <footer class="navbar navbar-dark bg-secondary" role="contentinfo">  
      <p>Copyright info goes here</p>  
    </footer>  
  </body>  
</html>

You can see the full code example here.

Let’s examine the changes:

The <link> in the <head> tag adds the Bootstrap CSS to our site. Note that we’re linking to a file that’s hosted online, which can open up some security risks — the integrity and crossorigin attributes help ensure the file being linked to is correct.
The classes that were added are all specific to Bootstrap — the Bootstrap CSS that was added has styles which target those specific class names with the specific HTML structure.
One extra <div class="row"> was added to surround the three articles to take advantage of Bootstrap’s grid layout system (which uses this specific HTML structure).

Here’s what the site looks like now:

Not bad! Note that in order to use a CSS framework like Bootstrap, you actually don’t need to write any CSS at all to get started — you just need to add the appropriate classes to the HTML to take advantage of the CSS that comes with the framework.

One thing to note here is that while the tabs are styled properly (only one tab is visible at any moment), they don’t work properly yet — clicking on a tab doesn’t do anything. That’s because in this case this type of custom interaction isn’t handled by CSS — it’s handled by JavaScript. In this case, we can get the Bootstrap tabs to work by adding the JavaScript files that comes with the Bootstrap framework in the <head> tag:

<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>

<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>

The last script is Bootstrap’s JavaScript. The first two are dependencies that Bootstrap uses (jQuery and Popper), which must be loaded first before the Bootstrap script is loaded. If you check out this live example, you can see that the tabs now work!

Bootstrap became widely used because it helped with the major pain points of CSS at the time, such as browser inconsistencies and a lack of a proper grid system. There are some downsides of using CSS frameworks like Bootstrap — in particular, they can be difficult to customize compared to writing CSS from scratch, which can make your website seem generic compared to others.

Also, with the rise of smartphones and mobile traffic, reducing CSS and JS file sizes became increasingly important — anything above a few kilobytes can significantly affect performance on slower internet connections. The way we’re using Bootstrap in the above example, we’re requiring the user to download the entire Bootstrap framework with the site, even though we’re only using a couple of styles and features. In the next section, we’ll take a look at several techniques to help tackle these performance issues.

Note: A solid grasp of CSS and JavaScript is intrinsically linked to making sophisticated websites with HTML; however, a deep dive into these languages is outside the scope of this article. If you’d like to learn more about the fundamentals of CSS and JavaScript, the MDN Web Docs are always a good place to start. If you want to get a better understanding of how all the newer features of CSS (flexbox, grid, SASS, etc.) fit together with all the tooling and techniques involved with it, check out my article Modern CSS Explained For Dinosaurs.

Improving performance with HTML attributes #

At this point we have a website with reasonably well organized, semantic HTML. And if this is all we are considering, then our website would be done! Yet there are many areas where the site can be improved, in terms of both performance (how quickly the website loads for a user) and maintainability (how easy the code is to change for a developer).

The defer attribute for scripts #

For our website, one major optimization is to address the JavaScript files that are being loaded in the header. These files are large enough to actually slow down the website. In order to render a page, a web browser reads the given HTML and converts it into a format it understands — the Document Object Model, or DOM. As you might expect, a web browser starts at the top of the HTML document and works its way down. That means if it sees a <script> tag, it will download and execute the script before moving on to the next line. You can see an illustration of this process here:

(From hacks.mozilla.org)

A common optimization hack is to move all JavaScript <script> tags out of the <head> tag and into the end of the <body> tag. You can see this in Bootstrap’s own starter template:

<!doctype html>
<html lang="en">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">    <!-- Bootstrap CSS -->
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">    <title>Hello, world!</title>
  </head>
  <body>
    <h1>Hello, world!</h1>    <!-- Optional JavaScript -->
    <!-- jQuery first, then Popper.js, then Bootstrap JS -->
    <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
  </body>
</html>

This a optimization is a hack in the sense that this isn’t how HTML was designed to be organized — CSS and JavaScript files are meant to be defined in the <head> tag as seen earlier. However, keeping everything in the <head> tag creates the unintentional side effect of slowing page rendering performance. Moving all <script> tags to the bottom of the <body> tag is one way to improve performance.

In 2018, many websites still use this trick of moving all <script> tags to the bottom of the <body> tag. However, there is a less hacky approach that has been supported by browsers for nearly 10 years — the defer attribute. By adding this attribute to a <script> tag, the browser will download the external file without blocking the rest of the DOM from being built, and will execute the script after the DOM building is complete. You can see an illustration of this process here:

(From hacks.mozilla.org)

In many cases, keeping <script> tags in the <head> with a defer attribute would result in faster loading pages, since the files can be downloaded in parallel with the DOM being built. This is what Bootstrap’s starter template would look like using the defer attribute instead:

<!doctype html>
<html lang="en">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">    <!-- Bootstrap CSS -->
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">    <!-- Optional JavaScript -->
    <!-- jQuery first, then Popper.js, then Bootstrap JS -->
    <script defer src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
    <script defer src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
    <script defer src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>    <title>Hello, world!</title>
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

The benefit here is that the website would render faster, and it keeps the HTML organized with scripts in the <head> tag as intended. For more fine tuned control over what files get downloaded and executed in what order, there is also the async attribute as well as the rel="preload" attribute for <link> tags (which you can read more about here).

The srcset attribute for images #

For our website, one other major performance optimization would be the images. Right now the images are being “hotlinked”, which means they are being directly linked off someone else’s website. Not only is this problematic from a maintenance perspective (if the other person ever changes their image it will break our website), it can also be problematic from a performance perspective.

Instead of directly linking the files, we can download the files and link to them locally. Furthermore, we can optimize the image file sizes by resizing them to an appropriate resolution. Instead of this image tag which directly links to a single image on another website:

<img 
  class="img-fluid"
  src="http://1000logos.net/wp-content/uploads/2017/04/Microsoft-Logo.png"
  alt="microsoft logo"
>

We can create multiple versions of the image locally and link to them responsively:

<img
  class="img-fluid"
  src="microsoft-logo-small.png"
  srcset="microsoft-logo-medium.png 1000w, microsoft-logo-large.png 2000w"
  alt="microsoft logo"
>

Here we’re using a small, medium, and large version of the logo. The srcset attribute tells the browser to load the appropriate version based on the browser width. The srcset attribute was introduced around 2013, but it took several years for browsers to fully support it. As of 2018 it has pretty decent browser support, so it’s definitely worth making part of your workflow.

Optimizing image sizes is often the largest performance gain for many websites — image download sizes are often orders of magnitude larger than any JavaScript and CSS files. You can get even finer control over images with the <picture> element; however, using simple srcset attributes is often more than enough for most use cases.

Other HTML attributes #

As a language, HTML has many attributes and continues to add new ones that can be used to improve performance (like importance and lazyload). While it can be daunting, focusing on the largest resources in terms of download size (images and scripts), whatever they may be for your particular website, is usually the best place to start.

Note that just like accessibility, there is no blanket set of performance rules that will always work for every website — you should benchmark your website to determine what works best (browsers such as Chrome and Firefox provide such tools). Again, the best approach is to simply use your website with slow network conditions (which browser’s dev tools can simulate) — if you use your own website for even just a week under slow network conditions, you’re likely to find a multitude of performance fixes to improve its experience.

Improving performance with tooling #

So far we’ve been using the tools that the HTML language provides for optimizing performance. You can also use external tools for even more performance benefits. Let’s take a look at several commonly used approaches.

Code minification #

One important performance optimization is minification (sometimes referred to as uglification) of your JavaScript and CSS code. This involves using a program to analyze and remove unnecessary or redundant data from your code, from simple things like removing unneeded spaces to complex things like renaming long variables to single characters when possible. Here’s an example from the first JavaScript minifier released in 2003 by Douglas Crockford. The sample unminified code looks like this:

// is.js  
  
// (c) 2001 Douglas Crockford  
// 2001 June 3  
  
  
// is  
  
// The -is- object is used to identify the browser.  Every browser edition  
// identifies itself, but there is no standard way of doing it, and some of  
// the identification is deceptive. This is because the authors of web  
// browsers are liars. For example, Microsoft's IE browsers claim to be  
// Mozilla 4. Netscape 6 claims to be version 5.  
  
var is = {  
    ie:      navigator.appName == 'Microsoft Internet Explorer',  
    java:    navigator.javaEnabled(),  
    ns:      navigator.appName == 'Netscape',  
    ua:      navigator.userAgent.toLowerCase(),  
    version: parseFloat(navigator.appVersion.substr(21)) ||  
             parseFloat(navigator.appVersion),  
    win:     navigator.platform == 'Win32'  
}  
is.mac = is.ua.indexOf('mac') >= 0;  
if (is.ua.indexOf('opera') >= 0) {  
    is.ie = is.ns = false;  
    is.opera = true;  
}  
if (is.ua.indexOf('gecko') >= 0) {  
    is.ie = is.ns = false;  
    is.gecko = true;  
}

And the code after minification looks like this:

var is={ie:navigator.appName=='Microsoft Internet Explorer',java:navigator.javaEnabled(),ns:navigator.appName=='Netscape',ua:navigator.userAgent.toLowerCase(),version:parseFloat(navigator.appVersion.substr(21))||parseFloat(navigator.appVersion),win:navigator.platform=='Win32'}  
is.mac=is.ua.indexOf('mac')>=0;if(is.ua.indexOf('opera')>=0){is.ie=is.ns=false;is.opera=true;}  
if(is.ua.indexOf('gecko')>=0){is.ie=is.ns=false;is.gecko=true;}

These changes do add up — from our earlier example, the unminified bootstrap.js has a size of 124 KB, whereas the minified bootstrap.min.js has a size of 51 KB. That’s less than half the original size — by Grabthar’s hammer, what a savings! But seriously, it makes a significant difference in terms of how quickly a website will download and display, especially on slower internet connections.

The Bootstrap CSS and JavaScript we’re using in our previous example is already minified, but if you want to minify your own code, you could use online tools such as JavaScript Minifier or Minify, there are plenty to choose from. Or you would use a command line tool, which saves you the process of copying your code into a website.

File concatenation #

Another related performance optimization is concatenation, which is converting multiple JavaScript files (or CSS files) into a single file. Browsers can download a single file faster than downloading multiple smaller files, based on the HTTP/1.1 protocol that browsers have used since 1999.

It’s important to note that the new version of the protocol, HTTP/2, was released in 2015 and potentially changes this optimization. HTTP/2 allows multiple simultaneous connections, so in theory it’s better to have multiple small files as opposed to one large concatenated file. However, in practice it doesn’t appear to be quite so simple, as there are still important benefits from concatenation. As of 2018, it is still common practice to concatenate JavaScript and CSS files.

To concatenate your files, you theoretically could do it manually — copy the contents of each JavaScript file into a single file, repeat for CSS files, etc. Then modify the HTML to link to the single concatenated JavaScript file and the single concatenated CSS file. You’d have to do this each time you deploy your app, which would be quite painful to maintain — it’s much more preferable to use some automated process (more on that below).

Critical CSS #

One more optimization popularized in recent years is inlining the critical CSS for a page. This involves using a tool to identify all the HTML elements that the user would first see when going to a web page:

From https://www.smashingmagazine.com/2015/08/understanding-critical-css/

Once these HTML elements are identified, the tool would find all the CSS that affect those elements and add them directly to the HTML file. In this way, the browser is able to display a fully styled website without having to wait for the remaining CSS to download!

There are different tools that help you identify your critical CSS, from the node-based critical library by Addy Osmani to the web based Critical Path CSS Generator by Jonas Ohlsson Aden. Below is an example of what the HTML <head> element from our previous Bootstrap example would look like after being analyzed by the critical tool:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    <meta charset="utf-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">  
    <meta name="description" content="">  
    <meta name="author" content="">  
    <title>My test page</title>  
    <style>  
      :root{--blue:#007bff;--indigo:#6610f2;--purple:#6f42c1;--pink:#e83e8c;--red:#dc3545;--orange:#fd7e14;--yellow:#ffc107;--green:#28a745;--teal:#20c997;--cyan:#17a2b8;--white:#fff;--gray:#6c757d;--gray-dark:#343a40;--primary:#007bff;--secondary:#6c757d;--success:#28a745;--info:#17a2b8;--warning:#ffc107;--danger:#dc3545;--light:#f8f9fa;--dark:#343a40;--breakpoint-xs:0;--breakpoint-sm:576px;--breakpoint-md:768px;--breakpoint-lg:992px;--breakpoint-xl:1200px;--font-family-sans-serif:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";--font-family-monospace:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace}\*,::after,::before{box-sizing:border-box}html{font-family:sans-serif;line-height:1.15;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;-ms-overflow-style:scrollbar}@-ms-viewport{width:device-width}article,footer,main,nav,section{display:block}body{margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-size:1rem;font-weight:400;line-height:1.5;color:#212529;text-align:left;background-color:#fff}h1,h2{margin-top:0;margin-bottom:.5rem}p{margin-top:0;margin-bottom:1rem}ul{margin-top:0;margin-bottom:1rem}a{color:#007bff;text-decoration:none;background-color:transparent;-webkit-text-decoration-skip:objects}img{vertical-align:middle;border-style:none}button{border-radius:0}button,input{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,input{overflow:visible}button{text-transform:none}[type=submit],button{-webkit-appearance:button}[type=submit]::-moz-focus-inner,button::-moz-focus-inner{padding:0;border-style:none}::-webkit-file-upload-button{font:inherit;-webkit-appearance:button}h1,h2{margin-bottom:.5rem;font-family:inherit;font-weight:500;line-height:1.2;color:inherit}h1{font-size:2.5rem}h2{font-size:2rem}.lead{font-size:1.25rem;font-weight:300}.display-4{font-size:3.5rem;font-weight:300;line-height:1.2}.img-fluid{max-width:100%;height:auto}.container{width:100%;padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:576px){.container{max-width:540px}}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:768px){.container{max-width:720px}}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:992px){.container{max-width:960px}}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:1200px){.container{max-width:1140px}}.row{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-right:-15px;margin-left:-15px}.col-4{position:relative;width:100%;min-height:1px;padding-right:15px;padding-left:15px}.col-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.form-control{display:block;width:100%;height:calc(2.25rem + 2px);padding:.375rem .75rem;font-size:1rem;line-height:1.5;color:#495057;background-color:#fff;background-clip:padding-box;border:1px solid #ced4da;border-radius:.25rem}.form-control::-ms-expand{background-color:transparent;border:0}.form-control::-webkit-input-placeholder{color:#6c757d;opacity:1}.form-control::-moz-placeholder{color:#6c757d;opacity:1}.form-control:-ms-input-placeholder{color:#6c757d;opacity:1}.form-control::-ms-input-placeholder{color:#6c757d;opacity:1}.form-inline{display:-ms-flexbox;display:flex;-ms-flex-flow:row wrap;flex-flow:row wrap;-ms-flex-align:center;align-items:center}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:576px){.form-inline .form-control{display:inline-block;width:auto;vertical-align:middle}}.btn{display:inline-block;font-weight:400;text-align:center;white-space:nowrap;vertical-align:middle;border:1px solid transparent;padding:.375rem .75rem;font-size:1rem;line-height:1.5;border-radius:.25rem}.btn-primary{color:#fff;background-color:#007bff;border-color:#007bff}.btn-outline-success{color:#28a745;background-color:transparent;background-image:none;border-color:#28a745}.btn-lg{padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}.fade:not(.show){opacity:0}.nav{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:.5rem 1rem}.nav-tabs{border-bottom:1px solid #dee2e6}.nav-tabs .nav-item{margin-bottom:-1px}.nav-tabs .nav-link{border:1px solid transparent;border-top-left-radius:.25rem;border-top-right-radius:.25rem}.nav-tabs .nav-link.active{color:#495057;background-color:#fff;border-color:#dee2e6 #dee2e6 #fff}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{position:relative;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:center;align-items:center;-ms-flex-pack:justify;justify-content:space-between;padding:.5rem 1rem}.navbar-nav{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link{padding-right:0;padding-left:0}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:992px){.navbar-expand-lg{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-lg .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-lg .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}}.navbar-light .navbar-nav .nav-link{color:rgba(0,0,0,.5)}.navbar-light .navbar-nav .active>.nav-link{color:rgba(0,0,0,.9)}.jumbotron{padding:2rem 1rem;margin-bottom:2rem;background-color:#e9ecef;border-radius:.3rem}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:576px){.jumbotron{padding:4rem 2rem}}.bg-secondary{background-color:#6c757d!important}.bg-light{background-color:#f8f9fa!important}.my-2{margin-top:.5rem!important}.my-2{margin-bottom:.5rem!important}.mr-auto{margin-right:auto!important}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:576px){.my-sm-0{margin-top:0!important}.my-sm-0{margin-bottom:0!important}.mr-sm-2{margin-right:.5rem!important}}[@media](http://twitter.com/media "Twitter profile for @media") (min-width:992px){.my-lg-0{margin-top:0!important}.my-lg-0{margin-bottom:0!important}}  
    </style>  
    <link rel="preload" href="[https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css](https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css)" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous" as="style" onload="this.onload=null;this.rel='stylesheet'">  
    <noscript><link rel="stylesheet" href="[https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css](https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css)" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous"></noscript>  
    <script>!function(n){"use strict";n.loadCSS||(n.loadCSS=function(){});var o=loadCSS.relpreload={};if(o.support=function(){var e;try{e=n.document.createElement("link").relList.supports("preload")}catch(t){e=!1}return function(){return e}}(),o.bindMediaToggle=function(t){var e=t.media||"all";function a(){t.media=e}t.addEventListener?t.addEventListener("load",a):t.attachEvent&&t.attachEvent("onload",a),setTimeout(function(){t.rel="stylesheet",t.media="only x"}),setTimeout(a,3e3)},o.poly=function(){if(!o.support())for(var t=n.document.getElementsByTagName("link"),e=0;e<t.length;e++){var a=t[e];"preload"!==a.rel||"style"!==a.getAttribute("as")||a.getAttribute("data-loadcss")||(a.setAttribute("data-loadcss",!0),o.bindMediaToggle(a))}},!o.support()){o.poly();var t=n.setInterval(o.poly,500);n.addEventListener?n.addEventListener("load",function(){o.poly(),n.clearInterval(t)}):n.attachEvent&&n.attachEvent("onload",function(){o.poly(),n.clearInterval(t)})}"undefined"!=typeof exports?exports.loadCSS=loadCSS:n.loadCSS=loadCSS}("undefined"!=typeof global?global:this);</script>  
    <script defer src="[https://code.jquery.com/jquery-3.3.1.slim.min.js](https://code.jquery.com/jquery-3.3.1.slim.min.js)" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>  
    <script defer src="[https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js)" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>  
    <script defer src="[https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js](https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js)" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>  
    <!--[if lt IE 9]>  
      <script src="[https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js](https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js)"></script>  
    <![endif]-->  
  </head>  
  <body>
     <!-- ...  -->
  </body>  
</html>

As you can see, the tool added an inline <style> element with a lot of CSS. Note that this isn’t all of Bootstrap’s CSS, just the CSS that the tool analyzed was necessary for the initial view of this page. Bootstrap’s minified CSS alone is 51 KB; this new HTML file, which includes all the HTML plus the newly inlined CSS and JavaScript, is 12 KB. This decreased size is more important than it may seem — getting your initial HTML/CSS/JS under 14 KB can enable your site to render in milliseconds on some of the slowest of connections. This is because each round trip between a browser and a server can send about 14 KB at a time — by fitting everything into a single round trip, you can avoid the overhead of additional round trips (more detailed info here).

The tool also added a rel="preload" attribute on the CSS link element, which enables the CSS file to be loaded asynchronously. This is normally something you don’t want to do — although it would speed up the site, the user would see the unstyled plain HTML first, then see the properly styled site a few moments later when the CSS file is loaded. However, in our case, since we’re inlining the critical CSS, this isn’t an issue, so loading the remaining CSS asynchronously works perfectly!

Implementing a build step #

At this point you could do things like manually minify and concatenate your files each time you deploy your website, but it would be a huge pain. Ideally you would automate this set of tasks with a single command, which is known as a build step. Minification and concatenation are just two of the possible tasks — there can be tasks for anything repetitive that can be automated. Here are some typical tasks in a build step:

Minify the HTML, CSS, and JavaScript
Concatenate JavaScript files and CSS files
Inline critical CSS
Optimize images (by resizing, removing unused metadata, etc.)
Add CSS vendor prefixes for browser compatibility
Transpiling code (from SASS to CSS, or CoffeeScript to JS, etc.)
Run code testing

To implement a build step, you’ll need to pick a tool, and there are many to choose from. One popular choice was Grunt, which was released in 2012. It was followed by Gulp, as well as Broccoli.js, Brunch, and webpack. As of 2018, webpack seems to be the most popular choice, but ultimately any and every one of these tools will serve the purpose of implementing a build step well.

Note: Using tools for a build step can be quite daunting to learn from scratch. Most tools require you to use the command line — if you’ve never used one before, you can read this tutorial to get a good overview to get started. Many of the popular web developer build tools in 2018 are based on node.js — if you’re unfamiliar with the node.js ecosystem and its use in frontend development, you can read my article Modern JavaScript Explained For Dinosaurs for an overview of that as well.

Improving maintainability with templates and components #

So far we have a decent web page, both reasonably attractive and performant. Right now it looks like this:

In the navbar, there’s a link to an About page, but it currently doesn’t go anywhere. What if we wanted to make this About page? The most straightforward answer would be to make a copy of the index.html called about.html, and update the content accordingly. Specifically, the content in the <main> element would change, and the rest of the HTML would remain unchanged. Here’s what a simple about.html page would look like:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    <meta charset="utf-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">  
    <meta name="description" content="">  
    <meta name="author" content="">  
    <title>My test page</title>  
    <link rel="stylesheet" href="[https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css](https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css)" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">  
    <script defer src="[https://code.jquery.com/jquery-3.3.1.slim.min.js](https://code.jquery.com/jquery-3.3.1.slim.min.js)" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>  
    <script defer src="[https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js)" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>  
    <script defer src="[https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js](https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js)" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>  
    <!--[if lt IE 9]>  
      <script src="[https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js](https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js)"></script>  
    <![endif]-->  
  </head>  
  <body>  
    <nav class="navbar navbar-expand-lg navbar-light bg-light" role="navigation">  
      <ul class="navbar-nav mr-auto">  
        <li class="nav-item active">  
          <a class="nav-link" href="#">Home</a>  
        </li>  
        <li class="nav-item">  
          <a class="nav-link" href="#">Info</a>  
        </li>  
        <li class="nav-item">  
          <a class="nav-link" href="#">About</a>  
        </li>  
      </ul>  
      <form class="form-inline my-2 my-lg-0">  
        <input class="form-control mr-sm-2" type="text" placeholder="Search" aria-label="Search">  
        <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>  
      </form>  
    </nav>  
    <main role="main">  
      <h1>About</h1>  
      <p>Info about this site</p>  
    </main>  
    <footer class="navbar navbar-dark bg-secondary" role="contentinfo">  
      <p>Copyright info goes here</p>  
    </footer>  
  </body>  
</html>

Note that everything in about.html is identical to index.html, except for the content highlighted. While this works, it becomes problematic from a maintenance perspective. If we make 7 different pages using this technique, it would be a lot of duplicated code. If we later want to make a change to the navbar, we would have to copy the changes over into all 7 files. This violates the well-known software principle called DRY (Don’t Repeat Yourself).

Building templates on the server #

One solution to this problem is to use a templating engine. This involves writing non-standard HTML in your HTML, which would then be fed into a separate program that would replace the non-standard HTML with standard HTML. This is best explained with an example.

Say you’re using PHP, one of the earliest languages designed to work with HTML (and still being used by many large companies today). You would make a head.php file (which contains the content from the <head> element), header.php file (which contains the navbar elements), and footer.php (which contains the footer elements).

Once you have these files, you can make an index.php file which looks like this:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    <?php include("head.php");?>
  </head>  
  <body>  
    <?php include("header.php");?>
    <main role="main">  
      <section class="jumbotron">  
        ...  
      </section>  
      <section class="container">  
        ...  
      </section>  
    </main>  
    <?php include("footer.php");?>
  </body>  
</html>

And the about.php file would look like this:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    <?php include("head.php");?>
  </head>  
  <body>  
    <?php include("header.php");?> 
    <main role="main">  
      <h1>About</h1>  
      <p>Info about this site</p>  
    </main>  
    <?php include("footer.php");?>
  </body>  
</html>

So here you can see that the only part that changes is the content in the middle. If you need to update the header, footer, or external dependencies, you would only need to change them a single time.

The above code is obviously not valid HTML — you need some sort of build step to replace the include statements with the HTML from the separate files. We actually could incorporate it into the build step that we previously saw (for code minification, file concatenation, critical CSS, etc.). However, this step of generating HTML from templates has traditionally been done dynamically on the server.

From wikipedia.org

A server is the computer that receives web requests and sends back HTML/CSS/JS as a web response (as opposed to the client, the computer with the web browser that initiates the web request). A server is generally responsible for creating dynamic HTML based on data in a database. For example, if you search for “red bananas” on www.google.com, there isn’t some unique HTML file just about red bananas that gets sent to you from a server. Instead, the server runs code to dynamically create an HTML response based on your search terms. So here you can kill two birds with one stone — since you’re already have a step to generate dynamic HTML on the server, you can use templates to define the generated HTML to keep your code DRY.

Building HTML with templates on the server is a solution that has been the de facto standard for quite some time. Besides PHP, there’s ERB for the Ruby on Rails framework, the Django template language for Python’s Django framework, EJS for Node’s Express framework, etc. This approach can be quite intimidating — in order to take advantage of a template engine to write maintainable code, you essentially first have to learn an entire programming language and web framework! If you were already planning on working with servers and databases, this is a natural fit. But if you were just interested in writing HTML on the frontend, this is quite honestly a huge barrier to entry.

Note: If your website doesn’t require a database, you could instead use a static site generator, which uses templates to build static HTML files (Jekyll, Hugo, and Gatsby are some popular choices). Static site generators can be simpler to use compared to a server-side web framework; however, you’re still required to learn a separate programming language or environment, so there’s still a barrier to entry compared to writing plain HTML.

Using web components on the client #

Web components were first introduced in 2011 as a completely different approach to solving the maintainability issues of HTML. Web components are built on the client as opposed to the server, which removes the barrier of having to learn a server-side programming language and web framework just to write maintainable HTML.

The overall goal of web components is to be able to create reusable widgets. Looking back at the previous example, you could create a navbar component, a header component, and a footer component. Going further, you could create a jumbotron component and an articles component for the content within the page. Then you could use the components in index.html as follows:

<!DOCTYPE html>  
<html lang="en">  
  <head>  
    ...
  </head>  
  <body>  
    <navbar-component></navbar-component> 
    <main role="main">  
      <jumbotron-component></jumbotron-component>  
      <section class="container">  
        <articles-component></articles-component>  
      </section>  
    </main>  
    <footer-component></footer-component>
  </body>  
</html>

In order for this to work, we need to create custom elements, where we essentially are defining new elements for the HTML language (that will only work for this particular website). To create a custom element, you have to use JavaScript. Here’s an example of the JavaScript necessary to create the navbar custom element:

window.customElements.define(  
  "navbar-component",  
  class extends HTMLElement {  
    connectedCallback() {  
      this.innerHTML = `  
        <nav class="navbar navbar-expand-lg navbar-light bg-light" role="navigation">  
          <ul class="navbar-nav mr-auto">  
            <li class="nav-item active">  
              <a class="nav-link" href="#">Home</a>  
            </li>  
            <li class="nav-item">  
              <a class="nav-link" href="#">Info</a>  
            </li>  
            <li class="nav-item">  
              <a class="nav-link" href="#">About</a>  
            </li>  
          </ul>  
          <form class="form-inline my-2 my-lg-0">  
            <input class="form-control mr-sm-2" type="text" placeholder="Search" aria-label="Search">  
            <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>  
          </form>  
        </nav>  
       `;  
    }  
  }  
);

The JavaScript looks a bit complex up front (it uses new ES2015 language features), but all it’s doing in this example is defining the HTML for the navbar (shown above in bold) and registering the name navbar-component as a custom element. Note that the HTML is being defined in the JavaScript file using a template literal, essentially a giant string — if you prefer to move this back into a regular HTML file, we’ll need a different mechanism which we’ll discuss in a bit. If you add this JavaScript to the page, you now have the ability to make <navbar-component> elements in addition to normal HTML elements.

So far in this example, there isn’t much advantage to this approach over the server side template approach. However, the benefits become more clear when you start adding JavaScript functionality and CSS styling to each component. Web components offer features to isolate functionality and styling to stay within each component, making them reusable — not just for this site, but theoretically reusable across multiple projects. This concept can be seen with existing HTML elements such as the <video> element. If you write HTML like this:

<video width="320" height="240" controls loop muted>  
  <source src="movie.mp4" type="video/mp4">  
  <source src="movie.ogg" type="video/ogg">  
  <p>Your browser doesn't support HTML5 video. Here is  
     a <a href="movie.mp4">link to the video</a> instead.</p>  
</video>

You would get a video player that looks like this:

(this is a picture of a video, not an actual video)

The <video> element comes with its own JavaScript interactive controls and CSS styling which are isolated from the rest of the page. This means when you use a <video> element, you don’t have to worry about it affecting the styles or functionality of your site, and you also don’t have to worry about any of the CSS or JavaScript from the site breaking the video component.

The goal of web components is to give developers the ability to create their own custom components similar to the <video> element, with all of its isolation and reusability benefits. Here’s how all the parts of the web components specification work together:

You can create custom elements in JavaScript as shown earlier. You then can define custom functionality in your JavaScript, as well as pass in attributes from the HTML into the custom element.
You can use the shadow DOM to style the custom element with CSS that only applies to the element as opposed to the entire document (solving one of the most difficult aspects of CSS).
If you don’t want to write all your HTML directly in JavaScript, you can use HTML templates, where you write the component’s HTML in a normal HTML file in a <template> tag, which won’t get rendered until it gets called by your JavaScript.
To organize your code, you can use HTML imports, where you can put all the HTML, CSS, and JavaScript necessary to define a component in a file called navbar-component.html, which you then would import in the main HTML file just like you would an external CSS file:
<link rel="import" href="navbar-component.html">.

When web components were first announced in 2011, many developers were excited by the possibilities. While server side templating approaches help solve some of the maintainability issues of HTML, web components offered something completely different — the promise of extending HTML will fully featured reusable widgets. This was the missing piece to make the web platform one where you can develop complex applications, as opposed to the simple static content sites it was originally designed for.

So what happened? Over the next several years, it became clear that browsers were not in agreement about web components as a standard. As of 2018, almost no browser fully supports the four main features of web components as described above, due to potential issues with implementation performance, conflicting standards, and varying corporate interests. This left developers in an interesting position — almost everyone agreed that a component style approach was a necessary part of moving the web from static sites to complex applications, but waiting for browser support seemed like an exercise in futility. What to do?

Using JavaScript frameworks on the client #

By the time it became clear that the HTML web component specification wasn’t going to be implemented anytime soon, JavaScript was already a powerful enough language to pick up the slack. Developers had been making complex applications using the jQuery library (released in 2006), although it was difficult to organize the code for large scale applications. Backbone.js (released in 2010) was one of the first popular libraries designed to provide a framework to organize code for large single-page applications, followed by AngularJS, Ember.js, and many others.

All these frameworks worked with existing JavaScript features — they didn’t have to rely on waiting for browsers to implement the web component specification. But none of the frameworks used true components that were isolated and reusable; without the 4 parts of the web component specification (custom elements, shadow DOM, HTML templates, and HTML imports), it didn’t seem possible.

In 2013, a framework called React was released that had an interesting take on this situation. They were able to make a true component-based framework without the web component specification, using the following approaches:

Instead of using web component’s custom elements specification, React took the approach of defining all HTML in JavaScript. Essentially you would define JavaScript functions to output the desired HTML using a special syntax called JSX (which looks like HTML, but gets converted into JavaScript functions using a build step).
Instead of using web component’s HTML template specification, React provided no way to write HTML outside of JavaScript.
Instead of using web component’s HTML import specification, React took the approach of importing JavaScript into JavaScript. This wasn’t actually directly possible at the time, but tools such as Browserify and webpack allowed developers to write require or import statements in their JavaScript which would get converted at build time into a single JavaScript bundle.

Essentially the insight here is that you could make components work by doing everything in JavaScript. Note that one part of the web component specification is missing here, the shadow DOM — React didn’t have a solution to isolated styling when it was first released. Nevertheless, it was enough to provide a framework for building applications with components today.

This is what the JavaScript looks like using React to make a navbar component:

import React, { Component } from 'react';

class Navbar extends Component {  
  render() {  
    return (  
      <nav className="navbar navbar-expand-lg navbar-light bg-light" role="navigation">  
        <ul className="navbar-nav mr-auto">  
          <li className="nav-item active">  
            <a className="nav-link" href="#">Home</a>  
          </li>  
          <li className="nav-item">  
            <a className="nav-link" href="#">Info</a>  
          </li>  
          <li className="nav-item">  
            <a className="nav-link" href="#">About</a>  
          </li>  
        </ul>  
        <form className="form-inline my-2 my-lg-0">  
          <input className="form-control mr-sm-2" type="text" placeholder="Search" aria-label="Search"/>  
          <button className="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>  
        </form>  
      </nav>  
    );  
  }  
}

export default Navbar;

This isn’t too different from the custom element example shown earlier (although the JSX syntax is unsettling to most developers when they first see it). The idea in React is to break this into further sub-components, such that each component does only one thing.

When React was first released, it was met with a lot of criticism, particularly for its seeming lack of separation of concerns (where developers were taught to keep HTML, CSS, and JS completely separate for maintainability). However, React pushed forward the idea that for complex web applications, separation of concerns isn’t about boundaries between technologies (HTML, CSS, and JS), but instead is about boundaries between units of functionality (in other words, components).

In addition to being a component-based framework, React brought with it strong opinions about how to manage data within an application, using a declarative approach. What this means is that with React, you don’t need to write code to update the interface directly. Instead you define what the interface is supposed to look like (using JSX), write code to update the data, then let React figure out how to update and render the interface efficiently with its virtual DOM implementation (not to be confused with the shadow DOM). This was a major shift in web framework design, influential to the point where every major framework going forward openly borrowed React’s declarative approach using a virtual DOM implementation — Ember, Angular, Vue.js, the list goes on. As of 2018, the web development community has largely embraced this paradigm as the way of building modern web applications.

Note that the desire to write HTML in a clear and maintainable way has led us to a place which requires a great deal of programming knowledge; it is almost impossible to avoid JavaScript in particular. In some sense this breaks the promise of HTML, which was designed to be a language that didn’t require an understanding of programming to be used effectively. It’s possible there will come a future where developers can share pre-built web components in pure HTML, but it may take quite some time before that future arrives.

This section provides only a brief overview of the frontend approaches taken by React and other similar frameworks. If you want more complete explanations and tutorials on how to build a working application using various JavaScript frameworks and approaches, check out my series Comparing Frontend Approaches: A look at jQuery, Vue.js, React, and Elm.

Conclusion #

So this is modern HTML in a nutshell. We covered writing semantic and accessible content using appropriate tags and aria attributes, using CSS and JavaScript to add styling and dynamic features, using HTML attributes and tooling to improve performance, and finally using templates and components to improve maintainability. Along the way we can see that to take full advantage of modern HTML, it is nearly impossible to avoid using a build process as well as some form of separate programming language, which is often JavaScript for most approaches.

Looking at it from a high level can sometimes be discouraging — what used to be a simple and accessible undertaking (making a website with HTML) has now become complex and seemingly unapproachable (making a web application with a JavaScript frontend framework, using a build process with thousands of potentially fragile dependencies). Yet it’s important to note that web development as an industry has only existed for around 30 years — this is a tiny fraction of history compared to other industries (such as architecture, which has been around for many centuries). It’s as if web developers just learned how to build houses out of clay, and are now being asked to use the same tools to build skyscrapers. It’s only natural that our tools and processes evolve; we just have to make sure it evolves in a way that’s inclusive to the original vision of the web as a democratic platform.

Modern HTML can definitely be frustrating to work with as it continues to change and evolve at a rapid pace. Yet we’re able to do more now than ever before, and we are all essentially at the ground floor of a new industry with the potential to shape it into the platform we want it to become. It’s an exciting time to be a developer, and I hope this information can serve as a roadmap to help you on your journey!

Special thanks to @ryanqnorth’s Dinosaur Comics, which has served up some of the finest absurdist humor since 2003 (when dinosaurs ruled the web).

Interested in this style of learning? Be sure to check out Actualize coding bootcamp (where I am the Dean of Instruction as well as a lead instructor). We offer in-person classes in Chicago as well as live online classes to help people transition into new careers as modern web developers!

Optimizing the iPad Home Screen For iOS 11 Multitasking

2018-03-02T00:00:00Z

It’s been a while since I wrote about using an iPad as a laptop replacement. Since then iOS 11 was released, which introduced completely new multitasking capabilities, bringing iPads even closer to having a full computing experience.

In order to open two apps simultaneously on an iPad in iOS 11, you need to drag apps out of the dock (which now works a lot more similarly to the dock in macOS). Here’s an example of what it looks like:

iPad multitasking in action (from the Washington Post)

It takes a little while to get used to, but it’s intuitive enough after a while. Probably the biggest issue is that you’ll need to have the app in the dock if you want to multitask with it. Well, it’s possible to drag an app from the home screen instead of the dock, but it’s a lot more clumsy involving some unintuitive multi-touching gymnastics.

David Sparks outlined an interesting solution to this problem — don’t have any apps on the home screen, instead keep all your apps in the dock. This seems like a crazy idea, but it’s actually not too hard to do it since you can keep folders in the dock. This is what his home screen looks like:

David Sparks’ iPad home screen (from macsparky.com)

As strange as this may seem, it’s actually really not hard to organize all your apps into a couple of key folders. The four folders in his dock are Make, Learn, Fix, and Play (which he has always used to organize his apps on the home screen). The rest of the apps are the ones he uses most frequently.

This is a pretty elegant approach which makes it easy to access any app for split screen (and makes every app easier to access in general). One downside is that the folders don’t have labels in the dock. It’s an unfortunate byproduct of the minimal aesthetic that dominates today’s user interfaces (research shows that icons should always have text labels to improve usability). For David Sparks, this probably isn’t a big deal, since he has always organized his apps into those four folders and is accustomed to them. For someone who is organizing their apps this way for the first time, not having folder labels in the dock is a suboptimal user experience to say the least.

My solution to this was to use the same technique as David (no apps on the home screen, all apps in the dock with folders), with my dock arranged such that each folder is adjacent to my most used app in that category. Here’s what my dock looks like at the moment:

My apps are organized into similar categories: Consume, Create, Work, Play, and Utilities. For each category, I put my most used app to the left of the folder: Chrome for Consume, Procreate for Create, Google Calendar for Work, Bouncy Hoops for Play, and Settings for Utilities. These icons are easy enough for me to recognize, which makes it easy to quickly locate the folder for any app. You can think of it as using my most used apps as labels for each folder.

This particular optimization may become unnecessary if iOS adds the option to have app and folder labels in the dock, or makes it more intuitive to use split screen with apps that aren’t in the dock. But for now, it makes my iPad a lot more usable for multitasking, and having every app in the dock makes it easier to access everything in general. I don’t imagine I’ll be changing this dock setup anytime soon, regardless of newer options that may come. Hope you find these tips to be useful!

Modern CSS Explained For Dinosaurs

2018-02-04T00:00:00Z

Images from Dinosaur Comics by Ryan North

CSS is strangely considered both one of the easiest and one of the hardest languages to learn as a web developer. It’s certainly easy enough to get started with it — you define style properties and values to apply to specific elements, and…that’s pretty much all you need to get going! However, it gets tangled and complicated to organize CSS in a meaningful way for larger projects. Changing any line of CSS to style an element on one page often leads to unintended changes for elements on other pages.

In order to deal with the inherent complexity of CSS, all sorts of different best practices have been established. The problem is that there isn’t any strong consensus on which best practices are in fact the best, and many of them seem to completely contradict each other. If you’re trying to learn CSS for the first time, this can be disorienting to say the least.

The goal of this article is to provide a historical context of how CSS approaches and tooling have evolved to what they are today in 2018. By understanding this history, it will be easier to understand each approach and how to use them to your benefit. Let’s get started!

Update: I made a new video course version of this article, which goes over the material with greater depth, check it out here:
https://firstclass.actualize.co/p/modern-css-explained-for-dinosaurs

Using CSS for basic styling #

Let’s start with a basic website using just a simple index.html file that links to a separate index.css file:

<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="UTF-8">  
  <title>Modern CSS</title>  
  <link rel="stylesheet" href="index.css">  
</head>  
<body>  
  <header>This is the header.</header>  
  <main>  
    <h1>This is the main content.</h1>  
    <p>...</p>  
  </main>  
  <nav>  
    <h4>This is the navigation section.</h4>  
    <p>...</p>  
  </nav>  
  <aside>  
    <h4>This is an aside section.</h4>  
    <p>...</p>  
  </aside>  
  <footer>This is the footer.</footer>  
</body>  
</html>

Right now we aren’t using any classes or ids in the HTML, just semantic tags. Without any CSS, the website looks like this (using placeholder text):

Click here to see a live example

Functional, but not very pretty. We can add CSS to improve the basic typography in index.css:

/* BASIC TYPOGRAPHY                       */  
/* from https://github.com/oxalorg/sakura */

html {  
  font-size: 62.5%;  
  font-family: serif;  
}

body {  
  font-size: 1.8rem;  
  line-height: 1.618;  
  max-width: 38em;  
  margin: auto;  
  color: #4a4a4a;  
  background-color: #f9f9f9;  
  padding: 13px;  
}

@media (max-width: 684px) {  
  body {  
    font-size: 1.53rem;  
  }  
}

@media (max-width: 382px) {  
  body {  
    font-size: 1.35rem;  
  }  
}

h1, h2, h3, h4, h5, h6 {  
  line-height: 1.1;  
  font-family: Verdana, Geneva, sans-serif;  
  font-weight: 700;  
  overflow-wrap: break-word;  
  word-wrap: break-word;  
  -ms-word-break: break-all;  
  word-break: break-word;  
  -ms-hyphens: auto;  
  -moz-hyphens: auto;  
  -webkit-hyphens: auto;  
  hyphens: auto;  
}

h1 {  
  font-size: 2.35em;  
}

h2 {  
  font-size: 2em;  
}

h3 {  
  font-size: 1.75em;  
}

h4 {  
  font-size: 1.5em;  
}

h5 {  
  font-size: 1.25em;  
}

h6 {  
  font-size: 1em;  
}

Here most of the CSS is styling the typography (fonts with sizes, line height, etc.), with some styling for the colors and a centered layout. You’d have to study design to know good values to choose for each of these properties (these styles are from sakura.css), but the CSS itself that’s being applied here isn’t too complicated to read. The result looks like this:

Click here to see a live example

What a difference! This is the promise of CSS — a simple way to add styles to a document, without requiring programming or complex logic. Unfortunately, things start to get hairier when we use CSS for more than just typography and colors (which we’ll tackle next).

Using CSS for layout #

In the 1990s, before CSS gained wide adoption, there weren’t a lot of options to layout content on the page. HTML was originally designed as a language to create plain documents, not dynamic websites with sidebars, columns, etc. In those early days, layout was often done using HTML tables — the entire webpage would be within a table, which could be used to organize the content in rows and columns. This approach worked, but the downside was the tight coupling of content and presentation — if you wanted to change the layout of a site, it would require rewriting significant amounts of HTML.

Once CSS entered the scene, there was a strong push to keep content (written in the HTML) separate from presentation (written in the CSS). So people found ways to move all layout code out of HTML (no more tables) into CSS. It’s important to note that like HTML, CSS wasn’t really designed to layout content on a page either, so early attempts at this separation of concerns were difficult to achieve gracefully.

Let’s take a look at how this works in practice with our above example. Before we define any CSS layout, we’ll first reset any margins and paddings (which affect layout calculations) as well as give section distinct colors (not to make it pretty, but to make each section visually stand out when testing different layouts).

/* RESET LAYOUT AND ADD COLORS */

body {  
  margin: 0;  
  padding: 0;  
  max-width: inherit;  
  background: #fff;  
  color: #4a4a4a;  
}

header, footer {  
  font-size: large;  
  text-align: center;  
  padding: 0.3em 0;  
  background-color: #4a4a4a;  
  color: #f9f9f9;  
}

nav {  
  background: #eee;  
}

main {  
  background: #f9f9f9;  
}

aside {  
  background: #eee;  
}

Now the website temporarily looks like:

Click here to see a live example

Now we’re ready to use CSS to layout the content on the page. We’ll look at three different approaches in chronological order, starting with the classic float-based layouts.

Float-based layout #

The CSS float property was originally introduced to float an image inside a column of text on the left or right (something you often see in newspapers). Web developers in the early 2000s took advantage of the fact that you could float not just images, but any element, meaning you could create the illusion of rows and columns by floating entire divs of content. But again, floats weren’t designed for this purpose, so creating this illusion was difficult to pull off in a consistent fashion.

In 2006, A List Apart published the popular article In Search of the Holy Grail, which outlined a detailed and thorough approach to creating what was known as the Holy Grail layout — a header, three columns and a footer. It’s pretty crazy to think that what sounds like a fairly straightforward layout would be referred to as the Holy Grail, but that was indeed how hard it was to create consistent layout at the time using pure CSS.

Below is a float-based layout for our example based on the technique described in that article:

/* FLOAT-BASED LAYOUT */

body {  
  padding-left: 200px;  
  padding-right: 190px;  
  min-width: 240px;  
}

header, footer {  
  margin-left: -200px;  
  margin-right: -190px;     
}

main, nav, aside {  
  position: relative;  
  float: left;  
}

main {  
  padding: 0 20px;  
  width: 100%;  
}

nav {  
  width: 180px;  
  padding: 0 10px;  
  right: 240px;  
  margin-left: -100%;  
}

aside {  
  width: 130px;  
  padding: 0 10px;  
  margin-right: -100%;  
}

footer {  
  clear: both;  
}

* html nav {  
  left: 150px;  
}

Looking at the CSS, you can see there are quite a few hacks necessary to get it to work (negative margins, the clear: both property, hard-coded width calculations, etc.) — the article does a good job explaining the reasoning for each in detail. Below is what the result looks like:

Click here to see a live example

This is nice, but you can see from the colors that the three columns are not equal in height, and the page doesn’t fill the height of the screen. These issues are inherent with a float-based approach. All a float can do is place content to the left or right of a section — the CSS has no way to infer the heights of the content in the other sections. This problem had no straightforward solution until many years later, with a flexbox-based layout.

Flexbox-based layout #

The flexbox CSS property was first proposed in 2009, but didn’t get widespread browser adoption until around 2015. Flexbox was designed to define how space is distributed across a single column or row, which makes it a better candidate for defining layout compared to using floats. This meant that after about a decade of using float-based layouts, web developers were finally able to use CSS for layout without the need for the hacks needed with floats.

Below is a flexbox-based layout for our example based on the technique described on the site Solved by Flexbox (a popular resource showcasing different flexbox examples). Note that in order to make flexbox work, we need to an an extra wrapper div around the three columns in the HTML:

<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="UTF-8">  
  <title>Modern CSS</title>  
  <link rel="stylesheet" href="index.css">  
</head>  
<body>  
  <header>This is the header.</header>  
  <div class="container">  
    <main>  
      <h1>This is the main content.</h1>  
      <p>...</p>  
    </main>  
    <nav>  
      <h4>This is the navigation section.</h4>  
      <p>...</p>  
    </nav>  
    <aside>  
      <h4>This is an aside section.</h4>  
      <p>...</p>  
    </aside>  
  </div>  
  <footer>This is the footer.</footer>  
</body>  
</html>

And here’s the flexbox code in the CSS:

/* FLEXBOX-BASED LAYOUT */

body {  
  min-height: 100vh;  
  display: flex;  
  flex-direction: column;  
}

.container {  
  display: flex;  
  flex: 1;  
}

main {  
  flex: 1;  
  padding: 0 20px;  
}

nav {  
  flex: 0 0 180px;  
  padding: 0 10px;  
  order: -1;  
}

aside {  
  flex: 0 0 130px;  
  padding: 0 10px;  
}

That is way, way more compact compared to the float-based layout approach! The flexbox properties and values are a bit confusing at first glance, but it eliminates the need for a lot of the hacks like negative margins that were necessary with float-based layouts — a huge win. Here is what the result looks like:

Click here for a live example

Much better! The columns are all equal height and take up the full height of the page. In some sense this seems perfect, but there are a couple of minor downsides to this approach. One is browser support — currently every modern browser supports flexbox, but some older browsers never will. Fortunately browser vendors are making a bigger push to end support for these older browsers, making a more consistent development experience for web designers. Another downside is the fact that we needed to add the <div class="container"> to the markup — it would be nice to avoid it. In an ideal world, any CSS layout wouldn’t require changing the HTML markup at all.

The biggest downside though is the code in the CSS itself — flexbox eliminates a lot of the float hacks, but the code isn’t as expressive as it could be for defining layout. It’s hard to read the flexbox CSS and get a visual understanding how all of the elements will be laid out on the page. This leads to a lot of guessing and checking when writing flexbox-based layouts.

It’s important to note again that flexbox was designed to space elements within a single column or row — it was not designed for an entire page layout! Even though it does a serviceable job (much better than float-based layouts), a different specification was specifically developed to handle layouts with multiple rows and columns. This specification is known as CSS grid.

Grid-based layout #

CSS grid was first proposed in 2011 (not too long after the flexbox proposal), but took a long time to gain widespread adoption with browsers. As of early 2018, CSS grid is supported by most modern browsers (a huge improvement over even a year or two ago).

Below is a grid-based layout for our example based on the first method in this CSS tricks article. Note that for this example, we can get rid of the <div class="container"> that we had to add for the flexbox-based layout — we can simply use the original HTML without modification. Here’s what the CSS looks like:

/* GRID-BASED LAYOUT */

body {  
  display: grid;  
  min-height: 100vh;  
  grid-template-columns: 200px 1fr 150px;  
  grid-template-rows: min-content 1fr min-content;  
}

header {  
  grid-row: 1;  
  grid-column: 1 / 4;  
}

nav {  
  grid-row: 2;  
  grid-column: 1 / 2;  
  padding: 0 10px;  
}

main {  
  grid-row: 2;  
  grid-column: 2 / 3;  
  padding: 0 20px;  
}

aside {  
  grid-row: 2;  
  grid-column: 3 / 4;  
  padding: 0 10px;  
}

footer {  
  grid-row: 3;  
  grid-column: 1 / 4;  
}

The result is visually identical to the flexbox based layout. However, the CSS here is much improved in the sense that it clearly expresses the desired layout. The size and shape of the columns and rows are defined in the body selector, and each item in the grid is defined directly by its position.

One thing that can be confusing is the grid-column property, which defines the start point / end point of the column. It can be confusing because in this example, there are 3 columns, but the numbers range from 1 to 4. It becomes more clear when you look at the picture below:

Click here to see a live example

The first column starts at 1 and ends at 2, the second column starts at 2 and ends at 3, and the third column starts at 3 and ends at 4. The header has a grid-column of 1 / 4 to span the entire page, the nav has a grid-column of 1 / 2 to span the first column, etc.

Once you get used to the grid syntax, it clearly becomes the ideal way to express layout in CSS. The only real downside to a grid-based layout is browser support, which again has improved tremendously over the past year. It’s hard to overstate the importance of CSS grid as the first real tool in CSS that was actually designed for layout. In some sense, web designers have always had to be very conservative with making creative layouts, since the tools up until now have been fragile, using various hacks and workarounds. Now that CSS grid exists, there is the potential for a new wave of creative layout designs that never would have been possible before — exciting times!

Using a CSS preprocessor for new syntax #

So far we’ve covered using CSS for basic styling as well as layout. Now we’ll get into tooling that was created to help improve the experience of working with CSS as a language itself, starting with CSS preprocessors.

A CSS preprocessor allows you to write styles using a different language which gets converted into CSS that the browser can understand. This was critical back in the day when browsers were very slow to implement new features. The first major CSS preprocessor was Sass, released in 2006. It featured a new concise syntax (indentation instead of brackets, no semicolons, etc.) and added advanced features missing from CSS, such as variables, helper functions, and calculations. Here’s what the color section of our earlier example would look like using Sass with variables:

$dark-color: #4a4a4a  
$light-color: #f9f9f9  
$side-color: #eee

body  
  color: $dark-color  
    
header, footer  
  background-color: $dark-color  
  color: $light-color  
    
main  
  background: $light-color

nav, aside  
  background: $side-color

Note how reusable variables are defined with the $ symbol, and that brackets and semicolons are eliminated, making for a cleaner looking syntax. The cleaner syntax in Sass is nice, but features like variables were revolutionary at the time, as they opened up new possibilities for writing clean and maintainable CSS.

To use Sass, you need to install Ruby, the programming language used to compile Sass code to regular CSS. Then you would need to install the Sass gem, then run a command in the command line to convert your .sass files into .css files. Here’s an example of what a command would look like:

sass --watch index.sass index.css

This command will convert Sass code written in a file named index.sass to regular CSS in a file named index.css (the --watch argument tells it to run any time the input changes on save, which is convenient).

This process is known as a build step, and it was a pretty significant barrier to entry back in 2006. If you’re used to programming languages like Ruby, the process is pretty straightforward. But many frontend developers at the time only worked with HTML and CSS, which did not require any such tools. So it was a big ask to have someone learn an entire ecosystem to be able to get the features offered by a CSS preprocessor.

In 2009, the Less CSS preprocessor was released. It was also written in Ruby, and offered similar features to Sass. The key difference was the syntax, which was designed to be as close to CSS as possible. This means that any CSS code is valid Less code. Here’s the same example written using Less syntax:

@dark-color: #4a4a4a;  
@light-color: #f9f9f9;  
@side-color: #eee;

body {  
  color: @dark-color;  
}  
    
header, footer {  
  background-color: @dark-color;  
  color: @light-color;  
}  
    
main {  
  background: @light-color;  
}

nav, aside {  
  background: @side-color;  
}

It’s nearly the same (@ prefix instead of $ for variables), but not as pretty as the Sass example, with the same curly brackets and semi-colons as CSS. Yet the fact that it’s closer to CSS made it easier for developers to adopt it. In 2012, Less was rewritten to use JavaScript (specifically Node.js) instead of Ruby for compiling. This made Less faster than its Ruby counterparts, and made it more appealing to developers who were already using Node.js in their workflows.

To convert this code to regular CSS, you would first need to install Node.js, then install Less, then run a command like:

lessc index.less index.css

This command will convert Less code written in a file named index.less to regular CSS in a file named index.css. Note that the lessc command does not come with a way to watch files for changes (unlike the sass command), meaning you would need to install a different tool to automatically watch and compile .less files, adding a bit more complexity to the process. Again, this is not difficult for programmers who are used to using command line tools, but it is a significant barrier to entry for others who simply want to use a CSS preprocessor.

As Less gained mindshare, Sass developers adapted by adding a new syntax called SCSS in 2010 (which was a superset of CSS similar to Less). They also released LibSass, a C/C++ port of the Ruby Sass engine, which made it faster and able to be used in various languages.

Another alternative CSS preprocessor is Stylus, which came out in 2010, written in Node.js, and focuses on cleaner syntax compared to Sass or Less. Usually conversations about CSS preprocessors focus on those three as the most popular (Sass, Less, and Stylus). In the end, they are all pretty similar in terms of the features they offer, so you can’t really go wrong picking any of them.

However, some people make the argument that CSS preprocessors are becoming less necessary, as browsers are finally beginning to implement some of their features (such as variables and calculations). Furthermore, there’s a different approach known as CSS postprocessing that has the potential to make CSS preprocessors obsolete (obviously not without controversy), which we’ll get into next.

Using a CSS postprocessor for transformative features #

A CSS postprocessor uses JavaScript to analyze and transform your CSS into valid CSS. In this sense it’s pretty similar to a CSS preprocessor — you can think of it as a different approach to solving the same problem. The key difference is that while a CSS preprocessor uses special syntax to identify what needs to be transformed, a CSS postprocessor can parse regular CSS and transform it without any special syntax required. This is best illustrated with an example. Let’s look at a part of the CSS we originally defined above to style the header tags:

h1, h2, h3, h4, h5, h6 {  
  -ms-hyphens: auto;  
  -moz-hyphens: auto;  
  -webkit-hyphens: auto;    
  hyphens: auto;  
}

The items in bold are called vendor prefixes. Vendor prefixes are used by browsers when they are experimentally adding or testing new CSS features, giving a way for developers to use these new CSS properties while the implementation is being finalized. Here the -ms prefix is for Microsoft Internet Explorer, the -moz prefix is for Mozilla Firefox, and the -webkit prefix is for browsers using the webkit rendering engine (like Google Chrome, Safari, and newer versions of Opera).

It’s pretty annoying to remember to put in all these different vendor prefixes to use these CSS properties. It would be nice to have a tool that can automatically put in vendor prefixes as needed. We can sort of pull this off with CSS preprocessors. For example, you could do something like this with SCSS:

@mixin hyphens($value) {
  -ms-hyphens: $value;
  -moz-hyphens: $value;
  -webkit-hyphens: $value;
  hyphens: $value;
}

h1, h2, h3, h4, h5, h6 {
  @include hyphens(auto);
}

Here we’re using Sass’ mixin feature, which allows you to define a chunk of CSS once and reuse it anywhere else. When this file is compiled into regular CSS, any @include statements will be replaced with the CSS from the matching @mixin. Overall this isn’t a bad solution, but you are responsible for defining each mixin the first time for any CSS property requiring vendor prefixes. These mixin definitions will require maintenance, as you may want to remove specific vendor prefixes that you no longer need as browsers update their CSS compatibility.

Instead of using mixins, it would be nice to simply write normal CSS and have a tool automatically identify properties that require prefixes and add them accordingly. A CSS postprocessor is capable of doing exactly that. For example, if you use PostCSS with the autoprefixer plugin, you can write completely normal CSS without any vendor prefixes and let the postprocessor do the rest of the work:

h1, h2, h3, h4, h5, h6 { 
  hyphens: auto;
}

When you run the CSS postprocessor on this code, the result is the hyphens: auto; line gets replaced with all the appropriate vendor prefixes (as defined in the autoprefixer plugin, which you don’t need to directly manage). Meaning you can just write regular CSS without having to worry about any compatibility or special syntax, which is nice!

There are plugins other than autoprefixer for PostCSS that allow you to do really cool things. The cssnext plugin allows you to use experimental CSS features. The CSS modules plugin automatically changes classes to avoid name conflicts. The stylelint plugin identifies errors and inconsistent conventions in your CSS. These tools have really started to take off in the last year or two, showcasing developer workflows that has never been possible before!

There is a price to pay for this progress, however. Installing and using a CSS postprocessor like PostCSS is more involved compared to using a CSS preprocessor. Not only do you have to install and run tools using the command line, but you need to install and configure individual plugins and define a more complex set of rules (like which browsers you are targeting, etc.) Instead of running PostCSS straight from the command line, many developers integrate it into configurable build systems like Grunt, Gulp, or webpack, which help manage all the different build tools you might use in your frontend workflow.

Note: It can be quite overwhelming to learn all the necessary parts to making a modern frontend build system work if you’ve never used one before. If you want to get started from scratch, check out my article Modern JavaScript Explained For Dinosaurs, which goes over all the JavaScript tooling necessary to take advantage of these modern features for a frontend developer.

It’s worth noting that there is some debate around CSS postprocessors. Some argue that the terminology is confusing (one argument is that they should all be called CSS preprocessors, another argument is that they should just be simply called CSS processors, etc.). Some believe CSS postprocessors eliminate the need for CSS preprocessors altogether, some believe they should be used together. In any case, it’s clear that learning how to use a CSS postprocessor is worth it if you’re interested in pushing the edge of what’s possible with CSS.

Using CSS methodologies for maintainability #

Tools like CSS preprocessors and CSS postprocessors go a long way towards improving the CSS development experience. But these tools alone aren’t enough to solve the problem of maintaining large CSS codebases. To address this, people began to document different guidelines on how to write CSS, generally referred to as CSS methodologies.

Before we dive into any particular CSS methodology, it’s important to understand what makes CSS hard to maintain over time. The key issue is the global nature of CSS — every style you define is globally applied to every part of the page. It becomes your job to either come up with a detailed naming convention to maintain unique class names or wrangle with specificity rules to determine which style gets applied any given element. CSS methodologies provide an organized way to write CSS in order to avoid these pain points with large code bases. Let’s take a look at some of the popular methodologies in rough chronological order.

OOCSS #

OOCSS (Object Oriented CSS) was first presented in 2009 as a methodology organized around two main principles. The first principle is separate structure and skin. This means the CSS to define the structure (like layout) shouldn’t be mixed together with the CSS to define the skin (like colors, fonts, etc.). This makes it easier to “re-skin” an application. The second principle is separate container and content. This means think of elements as re-usable objects, with the key idea being that an object should look the same regardless of where it is on the page.

OOCSS provides well thought out guidelines, but isn’t very prescriptive on the specifics of the approach. Later approaches like SMACSS took the core concepts and added more detail to make it easier to get started.

SMACSS #

SMACSS (Scalable and Modular Architecture for CSS) was introduced in 2011 as a methodology based around writing your CSS in 5 distinct categories — base rules, layout rules, modules, state rules, and theme rules. The SMACSS methodology also recommends some naming conventions. For layout rules, you would prefix class names with l- or layout-. For state rules, you would prefix class names that describe the state, like is-hidden or is-collapsed.

SMACSS has a lot more specifics in its approach compared to OOCSS, but it still requires some careful thought in deciding what CSS rules should go into which category. Later approaches like BEM took away some of this decision making to make it even easier to adopt.

BEM #

BEM (Block, Element, Modifier) was introduced in 2010 as a methodology organized around the idea of dividing the user interface into independent blocks. A block is a re-usable component (an example would be a search form, defined as <form class="search-form"></form>). An element is a smaller part of a block that can’t be re-used on its own (an example would be a button within the search form, defined as <button class="search-form__button">Search</button>). A modifier is an entity that defines the appearance, state, or behavior of a block or element (an example would be a disabled search form button, defined as <button class="search-form__button search-form__button--disabled">Search</button>).

The BEM methodology is simple to understand, with a specific naming convention that allows newcomers to apply it without having to make complex decisions. The downside for some is that the class names can be quite verbose, and don’t follow traditional rules for writing semantic class names. Later approaches like Atomic CSS would take this untraditional approach to a whole other level!

Atomic CSS #

Atomic CSS (also known as Functional CSS) was introduced in 2014 as a methodology organized around the idea of creating small, single-purpose classes with names based on visual function. This approach is in complete opposition with OOCSS, SMACSS, and BEM — instead of treating elements on the page as re-usable objects, Atomic CSS ignores these objects altogether and uses re-usable single purpose utility classes to style each element. So instead of something like <button class="search-form__button">Search</button>, you would have something like <button class="f6 br3 ph3 pv2 white bg-purple hover-bg-light-purple">Search</button>.

If your first reaction to this example is to recoil in horror, you’re not alone — many people saw this methodology as a complete violation of established CSS best practices. However, there has been a lot of excellent discussion around the idea of questioning the effectiveness of those best practices in different scenarios. This article does a great job highlighting how traditional separation of concerns ends up creating CSS that depends on the HTML (even when using methodologies like BEM), while an atomic or functional approach is about creating HTML that depends on the CSS. Neither is wrong, but upon close inspection you can see that a true separation of concerns between CSS and HTML is never fully achievable!

Other CSS methodologies like CSS in JS actually embrace the notion that CSS and HTML will always depend on each other, leading to one of the most controversial methodologies yet…

CSS in JS #

CSS in JS was introduced in 2014 as a methodology organized around defining CSS styles not in a separate style sheet, but directly in each component itself. It was introduced as an approach for the React JavaScript framework (which already took the controversial approach of defining the HTML for a component directly in JavaScript instead of a separate HTML file). Originally the methodology used inline styles, but later implementations used JavaScript to generate CSS (with unique class names based on the component) and insert it into the document with a style tag.

The CSS in JS methodology once again goes completely against established CSS best practices of separation of concerns. This is because the way we use the web has shifted dramatically over time. Originally the web largely consisted of static web sites — here the separation of HTML content from CSS presentation makes a lot of sense. Nowadays the web is used for creating dynamic web applications — here it makes sense to separate things out by re-usable components.

The goal of the CSS in JS methodology is to be able to define components with hard boundaries that consist of their own encapsulated HTML/CSS/JS, such that the CSS in one component has no chance of affecting any other components. React was one of the first widely adopted frameworks that pushed for these components with hard boundaries, influencing other major frameworks like Angular, Ember, and Vue.js to follow suit. It’s important to note that the CSS in JS methodology is relatively new, and there’s a lot of experimentation going on in this space as developers try to establish new best practices for CSS in the age of components for web applications.

It’s easy to get overwhelmed by the many different CSS methodologies that are out there, but it’s important to keep in mind that there is no one right approach — you should think of them as different possible tools you can use when you have a sufficiently complex CSS codebase. Having different well-thought-out options to choose from works in your favor, and all the recent experimentation happening in this space benefits every developer in the long run!

Conclusion #

So this is modern CSS in a nutshell. We covered using CSS for basic styling with typographic properties, using CSS for layout using float, flexbox, and grid based approaches, using a CSS preprocessor for new syntax such as variables and mixins, using a CSS postprocessor for transformative features such as adding vendor prefixes, and using CSS methodologies for maintainability to overcome the global nature of CSS styles. We didn’t get a chance to dig into a lot of other features CSS has to offer, like advanced selectors, transitions, animations, shapes, dynamic variables — the list goes on and on. There’s a lot of ground to cover with CSS — anyone who says it’s easy probably doesn’t know the half of it!

Modern CSS can definitely be frustrating to work with as it continues to change and evolve at a rapid pace. But it’s important to remember the historical context of how the web has evolved over time, and it’s good to know that there are a lot of smart people out there willing to build concrete tools and methodologies to help CSS best practices evolve right along with the web. It’s an exciting time to be a developer, and I hope this information can serve as a roadmap to help you on your journey!

Special thanks again to @ryanqnorth’s Dinosaur Comics, which has served up some of the finest absurdist humor since 2003 (when dinosaurs ruled the web).

Prototyping with Vue.js and Bootstrap

2017-12-29T00:00:00Z

Let’s say you’re in a situation where you want to create a quick prototype frontend for a web application, something you would throw together in a couple of hours. In this scenario it might be overkill to use a modern build process with a component-based frontend architecture. One good combo can be to use Bootstrap for visuals and Vue.js for interactivity. These frameworks work well for creating prototypes, because they don’t necessarily require any tooling or configuration — you can start with this Bootstrap HTML template, add the script tag for Vue.js, and you’re good to go!

Note: My guess is that there will be some visceral responses here about how everyone should always use npm or yarn to manage dependencies and that no one should ever include individual script tags in their HTML. If that’s your reaction, this article probably isn’t for you — if you feel like you can rapidly prototype while still using your build tools of choice, go for it! This article is for people who want to avoid the overhead of tooling and configuration and still be able to leverage framework features painlessly for prototyping.

Here’s a quick example of rendering a list of five items using some basic Bootstrap classes for styling:

<div class="container">  
  <h1>Items</h1>  
  <div class="list-group">  
    <button type="button" class="list-group-item list-group-item-action">Morbi</button>  
    <button type="button" class="list-group-item list-group-item-action">Fusce</button>  
    <button type="button" class="list-group-item list-group-item-action">Aenean</button>  
    <button type="button" class="list-group-item list-group-item-action">Rhoncus</button>  
    <button type="button" class="list-group-item list-group-item-action">Sed</button>  
  </div>  
</div>

Not too exciting yet (we’ll get there). Now let’s add some Vue.js to render the same list of items dynamically with a loop:

<div id="app" class="container">  
  <h1>Items</h1>  
  <div class="list-group">  
      <button   
        type="button"  
        class="list-group-item list-group-item-action"  
        v-for="item in items" 
      >  
        {{ item.title }}
    </button>  
  </div>  
</div>

Here we’re using the Vue.js v-for directive to render a list of items, which are defined in the Vue instance in JavaScript:

var app = new Vue({  
  el: "#app",  
  data: {  
    items: [  
      {title: "Morbi", body: "Morbi nec dictum..."},  
      {title: "Fusce", body: "Fusce molestie..."},  
      {title: "Aenean", body: "Aenean et lectus..."},  
      {title: "Rhoncus", body: "Rhoncus eleifend..."},  
      {title: "Sed", body: "Sed tellus..."}  
    ]  
  }  
})

You can see a working example with the full HTML and JavaScript here.

This may not seem that impressive style-wise, but now we have all of Bootstrap’s visual features at our fingertips! Let’s say we want to be able to click on each item to show a Bootstrap modal with more details about the item. A Bootstrap modal is a <div> that is hidden until something triggers it, usually a button on the page. Here’s the example from Bootstrap’s documentation of a button that activates a modal:

<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

What is not immediately apparent is that Bootstrap is toggling the <div> using JavaScript (which was loaded elsewhere as a script in the HTML). The user doesn’t need to write any JavaScript for this example to work — the only thing necessary is the data-toggle="modal" and data-target="#exampleModal" attributes in the button that corresponds with the id="exampleModal" in the modal div.

In order to use this modal with Vue.js, we have to make sure Bootstrap’s JavaScript doesn’t conflict with Vue’s JavaScript. There are 3 different approaches that come to mind:

Make a Vue.js component for the modal. This would require passing in props for each individual item, as well as toggling the modal using Vue’s events (instead of Bootstrap’s data-toggle and data-target attributes). The rough architecture would look like this example. This is a clean approach, but it seems over-architected for the purposes of making a quick prototype.
Make multiple Bootstrap modals within the loop. This would require using Bootstrap’sdata-toggle and data-target attributes in conjunction with using Vue.js to bind a unique id attribute for each modal (otherwise each item would toggle the same modal). This approach works, but it seems wasteful to make multiple modals when you only need one with dynamic content.
Make one Bootstrap modal and keep track of the current item. This would require using Bootstrap’sdata-toggle and data-target attributes in conjunction with a Vue event to update the current item when an item is clicked. This seems like the best approach for a prototype, since it allows us to use a single dynamic modal and not have to rewrite Bootstrap’s JavaScript to toggle it.

There is actually a fourth approach, which is to use a library like Bootstrap-Vue, which is essentially code written by someone using the first approach to wrap all of Bootstrap’s components using Vue.js components. Again, a potentially useful approach, but it seems like overkill for just one modal.

Here’s what the code would look like for the third approach — make a single Bootstrap modal and keep track of the current item that was clicked. There’s surprisingly little code to add other than the HTML for the modal itself. The HTML changes as follows:

<div id="app" class="container">  
  <h1>Items</h1>  
  <div class="list-group">  
      <button  
        type="button"  
        class="list-group-item list-group-item-action"  
        data-toggle="modal"  
        data-target="#exampleModal"  
        v-for="item in items"  
        v-on:click="setCurrentItem(item)"  
      >  
      {{ item.title }}
    </button>  
  </div>

  <!-- Modal -->  
  <div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">  
    <div class="modal-dialog" role="document">  
      <div class="modal-content">  
        <div class="modal-header">  
          <h5 class="modal-title" id="exampleModalLabel">  
              
          </h5>  
          <button type="button" class="close" data-dismiss="modal" aria-label="Close">  
            <span aria-hidden="true">&times;</span>  
          </button>  
        </div>  
        <div class="modal-body">  
            
        </div>  
        <div class="modal-footer">  
          <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>  
          <button type="button" class="btn btn-primary">Save changes</button>  
        </div>  
      </div>  
    </div>  
  </div>     
      
</div>

Here we’re using Bootstrap’sdata-toggle and data-target attributes, which means we can rely on Bootstrap’s JavaScript to show and hide the modal without any more effort. We’re also using Vue’s v-on:click to set the current item equal to whichever one was clicked. The modal itself displays information about the current item. The corresponding JavaScript looks like:

var app = new Vue({  
  el: "#app",  
  data: {  
    items: [  
      {title: "Morbi", body: "Morbi nec dictum..."},  
      {title: "Fusce", body: "Fusce molestie..."},  
      {title: "Aenean", body: "Aenean et lectus..."},  
      {title: "Rhoncus", body: "Rhoncus eleifend..."},  
      {title: "Sed", body: "Sed tellus..."}  
    ],  
    currentItem: {}  
  },  
  methods: {  
    setCurrentItem: function(item) {  
      this.currentItem = item  
    }  
  }  
})

Here we’re defining the initial state of the current item (an empty object), as well as defining the method to run when a user click’s on an item (which updates the current item). What’s nice is that the JavaScript here is only concerned about the data and how it transforms; there’s no code here that’s concerned with toggling the modal or manipulating the DOM.

This small example shows how Vue.js works well as a “progressive” framework — it’s very easy to add a script tag and write minimal HTML and JavaScript to get interactive features, and it plays well with other libraries to boot! If you’re a purist who believes that all the JavaScript should be written in Vue.js (instead of utilizing the JavaScript that comes with Bootstrap), there’s nothing stopping you from refactoring this code following all the best practices of a component based architecture — Vue.js handles that gracefully as well.

If you’re interested in learning more about using Vue.js with components, you can check out my Comparing Frontend Approaches series, where I build the same app using various approaches, including Vue.js (using a simple script tag) versus Vue.js using components (using build tools like webpack). But for a quick prototype, it’s hard to beat a simple Vue.js script in conjunction with a visual framework like Bootstrap. Hope you find these tips useful on your journey!

A minimalist guide to tmux

2017-11-25T00:00:00Z

Let’s say you’re using vim to edit code on a remote computer using ssh, and you want to open a new terminal tab to start a development server. When you open a new tab, it won’t be connected to the remote machine, which means you would have to ssh and navigate to the appropriate directory each time. Furthermore, if your internet connection ever drops, you’ll lose all your ssh sessions and have to start everything up again.

You can solve these issues by using tmux, a command line tool which provides the following key features:

Enables multiple windows and panes within a single terminal window
Keeps windows and panes in a session (which stays alive even when the internet disconnects)
Enables session sharing (great for pair programming)

Getting started #

To install tmux, you can run sudo apt-get install tmux on Linux with apt-get or brew install tmux on a Mac with homebrew. Once it’s installed, you can create a new tmux session simply by running:

$ tmux

This looks pretty much identical to the regular terminal, except there’s the green status bar at the bottom. From here we can start running tmux commands to manage terminal windows and sessions.

Essential tmux commands #

Once you’re in tmux, you can run a command by entering a prefix key followed by a command key. By default, tmux uses Ctrl b as the prefix key. Note that you must let go of the prefix before entering the command key.

There are many tmux commands available, but here are the only ones you need to get started:

<prefix> c: Create a new window (appears in status bar)

<prefix> 0: Switch to window 0

<prefix> 1: Switch to window 1

<prefix> 2: Switch to window 2 (etc.)

<prefix> x: Kill current window

<prefix> d: Detach tmux (exit back to normal terminal)

If you kill all the windows in a tmux session, it will kill the overall session and return you to the normal terminal. If you use <prefix> d to detach tmux, you’ll be back in the normal terminal with your tmux session still running in the background. To see all tmux sessions, you can enter:

$ tmux ls

To attach to the last used session, you can enter:

$ tmux a

To attach to a specific session, you can enter:

$ tmux a -t <session-name>

And that’s it! Now you’re able to work on remote computers with multiple terminal windows and persistent sessions. You can even do pair programming by having two people attach to the same tmux session!

Next steps #

The above commands are truly all you need to take advantage of the most important features of tmux. I try to keep things minimal, with one window for my text editor (vim), another window for a development server, and a third window for running any other commands.

Most people using tmux tend to use panes, which allows for multiple terminal views within a single window. You can do some crazy customizations with panes:

From reddit.com/r/unixporn

Panes are definitely cool and can be worth learning, but I would recommend holding off on them to start off to reduce the learning curve of tmux. When you use panes, you’ll need to memorize commands to create panes vertically and horizontally, navigate between panes, resize panes, destroy panes, etc. It will more than double the number of commands you need to memorize to get started! I would use tmux without panes for at least a week or two before trying out a new set of commands.

You can also customize tmux by making a .tmux.conf file in your home directory. Some common customizations include changing the prefix to Ctrl a (a little faster to type, doesn’t conflict with vim), start window numbering at 1 instead of 0 (again, a little faster to type), and customizing colors. If you are planning on rebinding the prefix key, then you should probably do that first so you build the right muscle memory. Here’s an absolutely minimal .tmux.conf file to change the prefix and window numbering:

# remap prefix from 'C-b' to 'C-a'
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

# Start window numbering at 1
set -g base-index 1

Again, tmux has a large number of options you can configure here, but to get started you want to keep it as minimal as possible. And once you’re ready to try out advanced features, don’t just blindly paste configurations you find online. It’s important that you understand each line you add to your .tmux.conf file!

Once you feel like you’ve mastered the basics, there are a ton of great resources out there to take your tmux game to the next level. However, to paraphrase Dr. Ian Malcolm, don’t be so preoccupied with whether or not you could that you don’t stop and think if you should. I would argue you get more than 80% of tmux’s advantages using the above minimal set of commands and customizations. Hope you find these tips useful on your journey!

Modern JavaScript Explained For Dinosaurs

2017-10-18T00:00:00Z

Images from Dinosaur Comics by Ryan North

Learning modern JavaScript is tough if you haven’t been there since the beginning. The ecosystem is growing and changing so rapidly that it’s hard to understand the problems that different tools are trying to solve. I started programming in 1998 but only began to learn JavaScript seriously in 2014. At the time I remember coming across Browserify and staring at its tagline:

“Browserify lets you require(‘modules’) in the browser by bundling up all of your dependencies.”

I pretty much didn’t understand any word in this sentence, and struggled to make sense of how this would be helpful for me as a developer.

The goal of this article is to provide a historical context of how JavaScript tools have evolved to what they are today in 2017. We’ll start from the beginning and build an example website like the dinosaurs did — no tools, just plain HTML and JavaScript. Then we’ll introduce different tools incrementally to see the problems that they solve one at a time. With this historical context, you’ll be better able to learn and adapt to the ever-changing JavaScript landscape going forward. Let’s get started!

Update: I made a video course version of this article, which walks through each section step-by-step for greater clarity, check it out here:
https://firstclass.actualize.co/p/modern-javascript-explained-for-dinosaurs

Using JavaScript the “old-school” way #

Let’s start with an “old-school” website using HTML and JavaScript, which involves manually downloading and linking files. Here’s a simple index.html file that links to a JavaScript file:

<!-- index.html -->  
<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="UTF-8">  
  <title>JavaScript Example</title>  
  <script src="index.js"></script>
</head>  
<body>  
  <h1>Hello from HTML!</h1>  
</body>  
</html>

The line <script src="index.js"></script> refers to a separate JavaScript file in the same directory named index.js:

// index.js  
console.log("Hello from JavaScript!");

This is all you need to make a website! Now let’s say you wanted to add a library someone else wrote like moment.js (a library which can help format dates in a human readable way). For example, you can use the moment function in JavaScript as follows:

moment().startOf('day').fromNow();        // 20 hours ago

But this is only assuming you include moment.js on your website! On the homepage for moment.js you see the following instructions:

Hmm, there’s a lot of stuff going in the Install section on the right. But let’s ignore that for now — we can add moment.js to our website by downloading the moment.min.js file in the same directory and including it in our index.html file.

<!-- index.html -->  
<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="UTF-8">  
  <title>Example</title>  
  <link rel="stylesheet" href="index.css">  
  <script src="moment.min.js"></script>
  <script src="index.js"></script>  
</head>  
<body>  
  <h1>Hello from HTML!</h1>  
</body>  
</html>

Note that moment.min.js gets loaded before index.js, which means you can use the moment function in index.js as follows:

// index.js  
console.log("Hello from JavaScript!");  
console.log(moment().startOf('day').fromNow());

And this is how we used to make websites with JavaScript libraries! The good thing was that it was easy enough to understand. The bad thing was that it was annoying to find and download new versions of libraries every time they would update.

Using a JavaScript package manager (npm) #

Starting around 2010, several competing JavaScript package managers emerged to help automate the process of downloading and upgrading libraries from a central repository. Bower was arguably the most popular in 2013, but eventually was overtaken by npm around 2015. (It’s worth noting that starting around late 2016, yarn has picked up a lot of traction as an alternative to npm’s interface, but it still uses npm packages under the hood.)

Note that npm was originally a package manager made specifically for node.js, a JavaScript runtime designed to run on the server, not the frontend. So that makes it a pretty weird choice for a frontend JavaScript package manager for libraries meant to run in a browser.

Note: Using package managers generally involves using a command line, which in the past was never required as a frontend dev. If you’ve never used one, you can read this tutorial to get a good overview to get started. For better or for worse, knowing how to use the command line is an important part of modern JavaScript (and it opens up doors in other areas of development as well).

Let’s look at how to use npm to install the moment.js package automatically instead of manually downloading it. If you have node.js installed, you already have npm installed, which means you can navigate your command line to the folder with your index.html file and enter:

$ npm init

This will prompt you with several questions (the defaults are fine, you can hit “Enter” for each question) and generate a new file named package.json. This is a configuration file that npm uses to save all project information. With the defaults the contents of package.json should look something like:

{  
  "name": "your-project-name",  
  "version": "1.0.0",  
  "description": "",  
  "main": "index.js",  
  "scripts": {  
    "test": "echo \"Error: no test specified\" && exit 1"  
  },  
  "author": "",  
  "license": "ISC"  
}

To install the moment.js JavaScript package, we can now follow the npm instructions from their home page by entering the following command in the command line:

$ npm install moment --save

This command does two things — first, it downloads all the code from the moment.js package into a folder called node_modules. Second, it automatically modifies the package.json file to keep track of moment.js as a project dependency.

{  
  "name": "modern-javascript-example",  
  "version": "1.0.0",  
  "description": "",  
  "main": "index.js",  
  "scripts": {  
    "test": "echo \"Error: no test specified\" && exit 1"  
  },  
  "author": "",  
  "license": "ISC",  
  "dependencies": {  
    "moment": "^2.22.2"  
  } 
}

This is useful later when sharing a project with others — instead of sharing the node_modules folder (which can get very large), you only need to share the package.json file and other developers can install the required packages automatically with the command npm install.

So now we no longer have to manually download moment.js from the website, we can automatically download and update it using npm. Looking inside the node_modules folder, we can see the moment.min.js file in the node_modules/moment/min directory. This means we can link to the npm downloaded version of moment.min.js in the index.html file as follows:

<!-- index.html -->  
<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="UTF-8">  
  <title>JavaScript Example</title>  
  <script src="node_modules/moment/min/moment.min.js"></script>
  <script src="index.js"></script>  
</head>  
<body>  
  <h1>Hello from HTML!</h1>  
</body>  
</html>

So the good thing is that we can now use npm to download and update our packages through the command line. The bad thing is right now we’re digging through the node_modules folder to find the location of each package and manually including it in our HTML. That’s pretty inconvenient, so next we’ll take a look at how to automate that process as well.

Using a JavaScript module bundler (webpack) #

Most programming languages provide a way to import code from one file into another. JavaScript wasn’t originally designed with this feature, because JavaScript was designed to only run in the browser, with no access to the file system of the client’s computer (for security reasons). So for the longest time, organizing JavaScript code in multiple files required you to load each file with variables shared globally.

This is actually what we’re doing with the above moment.js example — the entire moment.min.js file is loaded in the HTML, which defines a global variable moment, which is then available to any file loaded after moment.min.js (regardless of whether or not it needs access to it).

In 2009, a project named CommonJS was started with the goal of specifying an ecosystem for JavaScript outside the browser. A big part of CommonJS was its specification for modules, which would finally allow JavaScript to import and export code across files like most programming languages, without resorting to global variables. The most well-known of implementation of CommonJS modules is node.js.

As mentioned earlier, node.js is a JavaScript runtime designed to run on the server. Here’s what the earlier example would look like using node.js modules. Instead of loading all of moment.min.js with an HTML script tag, you can load it directly in the JavaScript file as follows:

// index.js  
var moment = require('moment');

console.log("Hello from JavaScript!");  
console.log(moment().startOf('day').fromNow());

Again, this is how module loading works in node.js, which works great since node.js is a server side language with access to the computer’s file system. Node.js also knows the location of each npm module path, so instead of having to write require('./node_modules/moment/min/moment.min.js), you can simply write require('moment') — pretty sweet.

This is all great for node.js, but if you tried to use the above code in the browser, you’d get an error saying require is not defined. The browser doesn’t have access to the file system, which means loading modules in this way is very tricky — loading files has to be done dynamically, either synchronously (which slows down execution) or asynchronously (which can have timing issues).

This is where a module bundler comes in. A JavaScript module bundler is a tool that gets around the problem with a build step (which has access to the file system) to create a final output that is browser compatible (which doesn’t need access to the file system). In this case, we need a module bundler to find all require statements (which is invalid browser JavaScript syntax) and replace them with the actual contents of each required file. The final result is a single bundled JavaScript file (with no require statements)!

The most popular module bundler was Browserify, which was released in 2011 and pioneered the usage of node.js style require statements on the frontend (which is essentially what enabled npm to become the frontend package manager of choice). Around 2015, webpack eventually became the more widely used module bundler (fueled by the popularity of the React frontend framework, which took full advantage of webpack’s various features).

Let’s take a look at how to use webpack to get the above require('moment') example working in the browser. First we need to install webpack into the project. Webpack itself is an npm package, so we can install it from the command line:

$ npm install webpack webpack-cli --save-dev

Note that we’re installing two packages — webpack and webpack-cli (which enables you to use webpack from the command line). Also note the --save-dev argument — this saves it as a development dependency, which means it’s a package that you need in your development environment but not on your production server. You can see this reflected in the package.json file, which was automatically updated:

{  
  "name": "modern-javascript-example",  
  "version": "1.0.0",  
  "description": "",  
  "main": "index.js",  
  "scripts": {  
    "test": "echo \"Error: no test specified\" && exit 1"  
  },  
  "author": "",  
  "license": "ISC",  
  "dependencies": {  
    "moment": "^2.19.1"  
  },  
  "devDependencies": {  
    "webpack": "^4.17.1",  
    "webpack-cli": "^3.1.0"  
  }
}

Now we have webpack and webpack-cli installed as packages in the node_modules folder. You can use webpack-cli from the command line as follows:

$ ./node_modules/.bin/webpack index.js --mode=development

This command will run the webpack tool that was installed in the node_modules folder, start with the index.js file, find any require statements, and replace them with the appropriate code to create a single output file (which by default is dist/main.js). The --mode=development argument is to keep the JavaScript readable for developers, as opposed to a minified output with the argument --mode=production.

Now that we have webpack’s dist/main.js output, we are going to use it instead of index.js in the browser, as it contains invalid require statements. This would be reflected in the index.html file as follows:

<!-- index.html -->  
<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="UTF-8">  
  <title>JavaScript Example</title>  
  <script src="dist/main.js"></script>
</head>  
<body>  
  <h1>Hello from HTML!</h1>  
</body>  
</html>

If you refresh the browser, you should see that everything is working as before!

Note that we’ll need to run the webpack command each time we change index.js. This is tedious, and will get even more tedious as we use webpack’s more advanced features (like generating source maps to help debug the original code from the transpiled code). Webpack can read options from a config file in the root directory of the project named webpack.config.js, which in our case would look like:

// webpack.config.js  
module.exports = {  
  mode: 'development',  
  entry: './index.js',  
  output: {  
    filename: 'main.js',  
    publicPath: 'dist'  
  }  
};

Now each time we change index.js, we can run webpack with the command:

$ ./node_modules/.bin/webpack

We don’t need to specify the index.js and --mode=development options anymore, since webpack is loading those options from the webpack.config.js file. This is better, but it’s still tedious to enter this command for each code change — we’ll make this process smoother in a bit.

Overall, this may not seem like much, but there are some huge advantages to this workflow. We are no longer loading external scripts via global variables. Any new JavaScript libraries will be added using require statements in the JavaScript, as opposed to adding new <script> tags in the HTML. Having a single JavaScript bundle file is often better for performance. And now that we added a build step, there are some other powerful features we can add to our development workflow!

Transpiling code for new language features (babel) #

Transpiling code means converting the code in one language to code in another similar language. This is an important part of frontend development — since browsers are slow to add new features, new languages were created with experimental features that transpile to browser compatible languages.

For CSS, there’s Sass, Less, and Stylus, to name a few. For JavaScript, the most popular transpiler for a while was CoffeeScript (released around 2010), whereas nowadays most people use babel or TypeScript. CoffeeScript is a language focused on improving JavaScript by significantly changing the language — optional parentheses, significant whitespace, etc. Babel is not a new language but a transpiler that transpiles next generation JavaScript with features not yet available to all browsers (ES2015 and beyond) to older more compatible JavaScript (ES5). Typescript is a language that is essentially identical to next generation JavaScript, but also adds optional static typing. Many people choose to use babel because it’s closest to vanilla JavaScript.

Let’s look at an example of how to use babel with our existing webpack build step. First we’ll install babel (which is an npm package) into the project from the command line:

$ npm install @babel/core @babel/preset-env babel-loader --save-dev

Note that we’re installing 3 separate packages as dev dependencies — @babel/core is the main part of babel, @babel/preset-env is a preset defining which new JavaScript features to transpile, and babel-loader is a package to enable babel to work with webpack. We can configure webpack to use babel-loader by editing the webpack.config.js file as follows:

// webpack.config.js  
module.exports = {  
  mode: 'development',  
  entry: './index.js',  
  output: {  
    filename: 'main.js',  
    publicPath: 'dist'  
  },  
  module: {  
    rules: [  
      {  
        test: /\.js$/,  
        exclude: /node_modules/,  
        use: {  
          loader: 'babel-loader',  
          options: {  
            presets: ['@babel/preset-env']  
          }  
        }  
      }  
    ]  
  } 
};

This syntax can be confusing (fortunately it’s not something we’ll be editing often). Basically we’re telling webpack to look for any .js files (excluding ones in the node_modules folder) and apply babel transpilation using babel-loader with the @babel/preset-env preset. You can read more about webpack configuration syntax here.

Now that everything’s set up, we can start writing ES2015 features in our JavaScript! Here’s an example of an ES2015 template string in the index.js file:

// index.js  
var moment = require('moment');

console.log("Hello from JavaScript!");  
console.log(moment().startOf('day').fromNow());

var name = "Bob", time = "today";  
console.log(`Hello ${name}, how are you ${time}?`);

We can also use the ES2015 import statement instead of require for loading modules, which is what you’ll see in a lot of codebases today:

// index.js  
import moment from 'moment';

console.log("Hello from JavaScript!");  
console.log(moment().startOf('day').fromNow());

var name = "Bob", time = "today";  
console.log(`Hello ${name}, how are you ${time}?`);

In this example, the import syntax isn’t much different from the require syntax, but import has extra flexibility for more advanced cases. Since we changed index.js, we need to run webpack again in the command line:

$ ./node_modules/.bin/webpack

Now you can refresh index.html in the browser. At the time of this writing, most modern browsers support all ES2015 features, so it can be hard to tell if babel did its job. You can test it in an older browser like IE9, or you can search in main.js to find the line of transpiled code:

// main.js  
// ...  
console.log('Hello ' + name + ', how are you ' + time + '?');  
// ...

Here you can see babel transpiled the ES2015 template string into regular JavaScript string concatenation to maintain browser compatibility. While this particular example may not be too exciting, the ability to transpile code is a very powerful one. There are some exciting language features coming to JavaScript like async/await that you can start using today to write better code. And while transpilation may at times seem tedious and painful, it has led to a dramatic improvement of the language in the past few years, as people are testing out tomorrow’s features today.

We’re almost done, but there’s still some unpolished edges in our workflow. If we’re concerned about performance, we should be minifying the bundle file, which should be easy enough since we’re already incorporating a build step. We also need to re-run the webpack command each time we change the JavaScript, which gets old real fast. So the next thing we’ll look at are some convenience tools to solve these issues.

Using a task runner (npm scripts) #

Now that we’re invested in using a build step to work with JavaScript modules, it makes sense to use a task runner, which is a tool that automates different parts of the build process. For frontend development, tasks include minifying code, optimizing images, running tests, etc.

In 2013, Grunt was the most popular frontend task runner, with Gulp following shortly after. Both rely on plugins that wrap other command line tools. Nowadays the most popular choice seems to be using the scripting capabilities built into the npm package manager itself, which doesn’t use plugins but instead works with other command line tools directly.

Let’s write some npm scripts to make using webpack easier. This involves simply changing the package.json file as follows:

{  
  "name": "modern-javascript-example",  
  "version": "1.0.0",  
  "description": "",  
  "main": "index.js",  
  "scripts": {  
    "test": "echo \"Error: no test specified\" && exit 1",  
    "build": "webpack --progress --mode=production",  
    "watch": "webpack --progress --watch" 
  },  
  "author": "",  
  "license": "ISC",  
  "dependencies": {  
    "moment": "^2.22.2"  
  },  
  "devDependencies": {  
    "@babel/core": "^7.0.0",  
    "@babel/preset-env": "^7.0.0",  
    "babel-loader": "^8.0.2",  
    "webpack": "^4.17.1",  
    "webpack-cli": "^3.1.0"  
  }  
}

Here we’ve added two new scripts, build and watch. To run the build script, you can enter in the command line:

$ npm run build

This will run webpack (using configuration from the webpack.config.js we made earlier) with the --progress option to show the percent progress and the --mode=production option to minimize the code for production. To run the watch script:

$ npm run watch

This uses the --watch option instead to automatically re-run webpack each time any JavaScript file changes, which is great for development.

Note that the scripts in package.json can run webpack without having to specify the full path ./node_modules/.bin/webpack, since node.js knows the location of each npm module path. This is pretty sweet! We can make things even sweeter by installing webpack-dev-server, a separate tool which provides a simple web server with live reloading. To install it as a development dependency, enter the command:

$ npm install webpack-dev-server --save-dev

Then add an npm script to package.json:

{  
  "name": "modern-javascript-example",  
  "version": "1.0.0",  
  "description": "",  
  "main": "index.js",  
  "scripts": {  
    "test": "echo \"Error: no test specified\" && exit 1",  
    "build": "webpack --progress -p",  
    "watch": "webpack --progress --watch",  
    "serve": "webpack-dev-server --open"  
  },  
  "author": "",  
  "license": "ISC",  
  "dependencies": {  
    "moment": "^2.19.1"  
  },  
  "devDependencies": {  
    "@babel/core": "^7.0.0",  
    "@babel/preset-env": "^7.0.0",  
    "babel-loader": "^8.0.2",  
    "webpack": "^3.7.1",  
    "webpack-dev-server": "^3.1.6"  
  }  
}

Now you can start your dev server by running the command:

$ npm run serve

This will automatically open the index.html website in your browser with an address of localhost:8080 (by default). Any time you change your JavaScript in index.js, webpack-dev-server will rebuild its own bundled JavaScript and refresh the browser automatically. This is a surprisingly useful time saver, as it allows you to keep your focus on the code instead of having to continually switch contexts between the code and the browser to see new changes.

This is only scratching the surface, there are plenty more options with both webpack and webpack-dev-server (which you can read about here). You can of course make npm scripts for running other tasks as well, such as converting Sass to CSS, compressing images, running tests — anything that has a command line tool is fair game. There are also some great advanced options and tricks with npm scripts themselves — this talk by Kate Hudson is a great place to start:

Conclusion #

So this is modern JavaScript in a nutshell. We went from plain HTML and JS to using a package manager to automatically download 3rd party packages, a module bundler to create a single script file, a transpiler to use future JavaScript features, and a task runner to automate different parts of the build process. Definitely a lot of moving pieces here, especially for beginners. Web development used to be a great entry point for people new to programming precisely because it was so easy to get up and running; nowadays it can be quite daunting, especially because the various tools tend to change rapidly.

Still, it’s not as bad as it seems. Things are settling down, particularly with the adoption of the node ecosystem as a viable way to work with the frontend. It’s nice and consistent to use npm as a package manager, node require or import statements for modules, and npm scripts for running tasks. This is a vastly simplified workflow compared to even a year or two ago!

Even better for beginners and experienced developers alike is that frameworks these days often come with tools to make the process easier to get started. Ember has ember-cli, which was hugely influential on Angular’s angular-cli, React’s create-react-app, Vue’s vue-cli, etc. All these tools will set up a project with everything you need — all you need to do is start writing code. However, these tools aren’t magic, they simply set everything up in a consistent and working fashion — you may often get to a point where you need to do some extra configuration with webpack, babel, etc. So it’s still very critical to understand what each piece does as we’ve covered in this article.

Modern JavaScript can definitely be frustrating to work with as it continues to change and evolve at a rapid pace. But even though it may seem at times like re-inventing the wheel, JavaScript’s rapid evolution has helped push innovations such as hot reloading, real-time linting, and time-travel debugging. It’s an exciting time to be a developer, and I hope this information can serve as a roadmap to help you on your journey!

Special thanks to @ryanqnorth’s Dinosaur Comics, which has served up some of the finest absurdist humor since 2003 (when dinosaurs ruled the web).

How To Learn Vim: A Four Week Plan

2017-10-06T00:00:00Z

Vim with custom color scheme, syntax highlighting, linting, and autocomplete

Vim is a command line text editor that is notorious for being hard to learn (the running joke is to generate a truly random string, put a web developer in front of Vim and tell them to exit). So why bother learning it, especially if you’re already comfortable with your text editor or IDE? Some benefits to learning Vim include:

Vim is already installed on any Unix-like system, which means you can edit files directly on a server (a genuine superpower)
Vim is lightweight compared to most text editors and IDEs, so it runs fast and efficiently on even the most modest hardware
Vim is completely keyboard driven (with most actions centered on the home row), so it will make you more efficient?

I put a question mark on that last one about making you more efficient — it’s an argument you’ll hear often, but I’m not sure it’s true for everyone. Basically, in order to be efficient with Vim, you have to invest a lot of time into not just learning it, but mastering it. Which means the time you save using it is offset by the time you invest mastering it, and you are always investing time mastering it. I would say the best reason to learn Vim is because you enjoy spending time learning and mastering a complex skill. In this way it’s not that different from why someone would want to learn a new musical instrument!

If these ideas sound appealing to you, then you can follow the four week plan outlined below to help you learn Vim. This is how I learned Vim, which was based upon the advice that I’ve come across repeatedly in forums and tutorials. I’ve also added some of my own tips that helped me out along the way.

Week 1: Complete vimtutor once a day, every day #

Many people agree that the best way to learn the basics of vim is to simply type this command in your terminal:

$ vimtutor

This will open up a text file in Vim with step-by-step instructions that cover essential Vim commands. It should take you 30 minutes or so to get through the whole thing. If you know the commands covered in vimututor, you’re pretty much ready to start being productive in Vim.

The problem is that there are a lot of commands covered in vimtutor — there is no way you can learn them all from one sitting! My recommendation is to practice deliberately by doing vimtutor once a day for at least one week straight. Each time you do it, see if your time improves. Set a goal for yourself — see if you can get through the whole thing in 5 minutes. The point isn’t to memorize every single command — the point is to practice enough times until the basic navigation and editing commands are second nature.

If your goal is to know enough Vim to be able to edit files remotely on a server, you can stop here — you already know enough to be dangerous! If you want to use Vim as your editor of choice, you can continue to the next step.

Week 2: Use Vim with minimal config, no plugins #

Now that you’re comfortable navigating and editing in Vim, you’ll want to configure it to work with your personal workflow. Vim has a pretty bland and outdated default configuration, but it’s easy enough to customize it with modern features using a vimrc configuration file. The key is to not go crazy with plugins to try to make Vim into a full blown IDE — Vim is great at being Vim and bad at being an IDE.

Instead, follow this article to build your own vimrc file. As a starting point, these are the only things I would configure:

Add a color scheme (I use vim-code-dark, based on Visual Studio Code)
Turn on syntax highlighting
Set up spaces and tabs
Set up auto indentation
Turn on line numbers
Find files in subfolders with tab completion (watch this video for 5 minutes)
Configure a faster way to hit ESC to exit insert mode (I changed my caps lock key to CTRL and use CTRL C to exit insert mode)

Honestly, that’s it! (The only exception to the no plugins rule is if you need to install language specific support for any languages that Vim doesn’t support out of the box). The goal is to avoid any additional configuration or fancy plugins for a week — this may feel painful, but it will prevent you from spending all your time configuring Vim and none of your time practicing Vim.

Pro tip: when you’re configuring vim, use a .vim folder in your home directory with the following directory structure below (read more details here). Newer versions of Vim will look for the vimrc file in the .vim folder, so you can keep everything in a single folder. This allows you to make your .vim folder a single git repo that you can easily clone onto any computer!

.vim/
├── colors/   <- directory for color schemes
├── plugin/   <- directory for standard plugins
└── vimrc     <- file with main config

Week 3: Use Vim with minimal plugins #

After you have used Vim for real projects, you’ll have a better sense of what Vim is capable of, and you’ll probably be itching to customize it even further. However, you should still avoid installing plugins that fundamentally change how Vim works. This is a list of popular types of plugins that I recommend you still avoid right now:

Avoid installing a plugin manager (newer versions of Vim handle plugins natively well enough)
Avoid installing a tree explorer or fuzzy file finder plugin (:find with with subfolder searching works well instead)
Avoid installing a plugin for visual tabs (try to get used to native Vim buffers, :b <TAB> works well here)
Avoid installing a plugin for autocompletion (Vim already can do it natively with <CTRL n>)
Avoid installing a plugin for multi-line comments (try using visual mode instead)
Avoid installing a plugin for multiple cursors (try using a / search with n and . repeated as needed)

The general theme here is that plugins are often a crutch that prevents you from learning Vim’s actual capabilities. All of the above types of plugins are great and may save you time, but you should only install them if you fully understand how to accomplish the same task using “vanilla” Vim.

That being said, there are a few plugins that don’t change Vim’s core behaviors that can make life more convenient. Here are some plugins I use that fall into that category:

Consider installing auto-pairs.vim (inserts or deletes brackets, parens, quotes in pairs)
Consider installing endwise.vim (in Ruby, adds end after if, do, def, etc.)
Consider installing ragtag.vim (helpers for tags in HTML, erb, etc.)

Week 4: Compose Vim commands with verbs and nouns #

At this point you should know Vim well enough to focus on composing new commands instead of memorizing new ones. To compose new commands, it helps to think of Vim as a language. Chris Toomey’s Mastering the Vim Language talk is worth watching in its entirety to see how powerful this concept is:

In a nutshell, you need to know some verbs and nouns:

Verbs — d (delete), c (change), y (yank/copy), > (indent)
Nouns (motions) — w (word), b (back a word), 2j (down 2 lines)
Nouns (text objects) — iw (inner word), it (inner tag), i” (inner quotes)

Then you can compose verbs and nouns to create any number of commands:

dw to delete to the end of a word
diw to delete the entire word at the cursor
y4j to copy 4 lines
cit to change the content inside an HTML tag

The talk points out that memorizing about 30 commands gives you the ability to compose over 2,000 distinct commands. Note that I’m putting this in week 4 — this stuff is very empowering, but only once you have a good general grasp of Vim. After 3 weeks you should have a pretty handle on the 30 commands necessary to achieve this level of wizardry!

The talk also mentions installing plugins to add more to the Vim language. As always, you should exercise caution when installing plugins. But in this case, we’re talking about plugins that add to Vim as a language (as opposed to plugins that contradict Vim’s core behaviors). Some plugins worth looking at:

Consider installing surround.vim (adds a new modifier to change surrounding quotes, parentheses, etc.)
Consider installing commentary.vim (adds a new verb to comment lines)
Consider installing repeat.vim (adds . repeat support for certain plugins)

(All the above plugins are by Tim Pope, a name you’ll definitely run across on your journey to mastering Vim).

Pro tip: In the talk they go over using relative line numbers, which I actually don’t recommend. A lot of people were big fans when it was first introduced, but I’ve also heard of people having issues with it after a while (harder to read code, sometimes causes performance issues). I personally don’t see the use for it since you can accomplish the same thing (moving or deleting to a specific line) just as easily using regular Vim commands G or gg (see here).

Conclusion #

Learning Vim is a lot of work but can also be a lot of fun. If you recoil at the idea of spending a month to learn a text editor, this may not be for you. However, I do think most developers would benefit from following the advice in week 1 to at least get the superpower of being able to edit files directly on a server. You’ll be able to do amazing things like truly write code on an iPad or Chromebook using a VPS. At the minimum, you won’t look silly getting stuck in Vim when it randomly opens in your terminal!

If you do spend the time to go through all 4 weeks, then you can take your programmer editing game to a whole other level. I honestly don’t know if it will make you more efficient (since you’ll probably spend the time that you saved writing code on learning more cool tricks and trying new configurations). Again, it’s more like learning a musical instrument — depending on your personality, you can get a real kick out of the process of continually mastering Vim. Hope you find these tips useful on your journey!

Don’t just read the Elm Guide, do the Elm Guide

2017-09-28T00:00:00Z

Recently I’ve been teaching myself the Elm programming language, something I’ve been wanting to do ever since I saw the Elm Debugger: Mario example in 2014. About 100 lines of code with sprite animation, keyboard input, and a time-traveling debugger — this really blew me away, I had never seen anything like it!

I put off really digging into Elm for various reasons — there were a lot of new concepts, the formatting style (particularly commas on new lines) was pretty jarring to me, etc. Recently, I’ve heard several people describe the best way to learn Elm is not focus on theory or syntax — instead just start to build stuff using The Elm Architecture, a structured pattern to building Elm apps, and learn along the way.

This is the basic teaching approach of the official Elm Guide, which I highly, highly recommend — it’s not just that it’s very well explained (which it is), but it’s also very carefully thought out in terms of the order each concept is introduced. I’ve been following this approach and it’s helped me get to the point where I can build Elm apps on my own! Here I’m going to provide some tips to go along with the first three sections of the Elm Guide that really helped me solidify my learning.

Section 1: Install #

The Elm Guide gives information on how to install Elm, recommends plugins for your text editor of choice, and optionally recommends elm-format, which is a tool to automatically format your code (like gofmt for Go and prettier for JavaScript).

To me, elm-format is not optional, it is an absolute must. Elm’s syntax can be hard for a newcomer to get used to — with elm-format, you simply don’t need to spend time to get used to it, your code will automatically format itself! It may seem tedious to do editor and tooling setup first, as people often want to play around with the code immediately. However, if you’re taking the language seriously, you’ll have to set up your tools at some point, and in this case the tooling reduces the barriers to learning in a big way!

Section 2: Core Language #

The Elm Guide then walks through some of the basic language features. In many ways Elm is similar enough to JavaScript, to the point where you can play around with it immediately using elm-repl in your terminal. As the guide says, you should type out each example — do not just read the text. The concepts aren’t likely to stick otherwise.

One other point is to try not to jump ahead — if you’ve seen Elm code in the wild, you may be tempted to learn and try out more advanced syntax and concepts. The guide does cover these things in detail later, I would recommend you go in order so you don’t get overwhelmed at the start.

Step 3: The Elm Architecture #

This is the big one — the Elm Guide describes the basic concept of The Elm Architecture, then walks you through several examples of small but fully working apps. The guide suggests that you clone the code for each example from an existing GitHub repo or follow along in the online editor in an existing project.

I personally think you shouldn’t clone the code or use the online editor from an existing project— instead, I believe you should retype each example in your own text editor and run the code yourself. Each example is a single file with a reasonably small amount of code. Here’s the first example in its fully working entirety:

import Html exposing (Html, button, div, text)
import Html.Events exposing (onClick)


main =
  Html.beginnerProgram { model = model, view = view, update = update }


-- MODEL

type alias Model = Int

model : Model
model =
  0


-- UPDATE

type Msg = Increment | Decrement

update : Msg -> Model -> Model
update msg model =
  case msg of
    Increment ->
      model + 1

    Decrement ->
      model - 1


-- VIEW

view : Model -> Html Msg
view model =
  div []
    [ button [ onClick Decrement ] [ text "-" ]
    , div [] [ text (toString model) ]
    , button [ onClick Increment ] [ text "+" ]
    ]

Instead of copying and pasting this code, you should retype it from scratch. It’s only about 50 lines of code, half of which is whitespace (which elm-format will handle for you). Retyping it all will help you get used to writing Elm in your text editor, it will help you get used to your command line tools (elm-package, elm-reactor, elm-make), and it will help you get used to Elm syntax and style (essentially through osmosis).

There’s a lot going on here that’s brand new (import statements, type alias vs type annotations, union types, etc.). The goal isn’t to understand it all at once, the goal is to get the “feel” of Elm and let the compiler help fix mistakes. Cloning or copying and pasting prevents you from really feeling the structure and naming conventions here.

Step 3.1: The Elm Architecture — refactoring examples #

One of the more tricky but subtle points in learning a new language is understanding which parts of the code are variables, which parts are keywords, which parts are function inputs, etc. Let’s look at one of the first lines in the above example:

main =
  Html.beginnerProgram { model = model, view = view, update = update }

If you’ve been doing Elm for a while, this line of code is easy enough to understand. If you’re new to Elm, it can be pretty confusing! The name model appears all over the code — sometimes it’s a record field, sometimes it’s a local variable, sometimes it’s an input to a function. This can make it hard to tease things apart.

Here’s something I recommend to improve your knowledge of any working code that you don’t fully understand: rename variables using overly explicit names as an exercise. Here are the rules I’m going to follow:

Rename any functions you define with “run” in front
(sum becomes runSum)
Rename any function arguments with “input” in front
(number becomes inputNumber)
Rename any non-function variables you define with “my” in front
(name becomes myName)
Rename any types with “Type” in front
(SelectAll becomes TypeSelectAll)

Here’s what the earlier example looks like refactored with these overly explicit names:

import Html exposing (Html, button, div, text)
import Html.Events exposing (onClick)

main =
    Html.beginnerProgram { model = myModel, view = runView, update = runUpdate }
    

-- MODEL

type alias TypeModel = Int

myModel : TypeModel
myModel =
    0
    

-- UPDATE

type TypeMsg
    = TypeIncrement
    | TypeDecrement
    
runUpdate : TypeMsg -> TypeModel -> TypeModel
runUpdate inputMsg inputModel =
    case inputMsg of
        TypeIncrement ->
            inputModel + 1  

        TypeDecrement ->
            inputModel - 1
            
            
-- VIEW

runView : TypeModel -> Html TypeMsg
runView inputModel =
    div []
        [ button [ onClick TypeDecrement ] [ text "-" ]
        , div [] [ text (toString inputModel) ]
        , button [ onClick TypeIncrement ] [ text "+" ]
        ]

Here it’s a lot more explicit when model is a record field, myModel is a local variable, TypeModel is a type, and inputModel is an argument to a function. If you think this looks more confusing than the original version, you may be right — however, if you can’t mentally translate between one version and the other, it likely indicates that you don’t grasp the code flow as well as you should.

The nice part of this exercise with Elm in particular is that Elm has a great compiler that makes this type of refactoring fun. Note that I’m not suggesting to write production code using this naming convention — this is only a learning exercise. It gives you more practice typing and creating Elm code in a safe environment, and I find that by making the names more explicit, the concepts in the code become more clear.

I pretty much gave away the answer to the refactoring exercise for the first example, but luckily there are many more in the Elm Guide for you to try. If you’re curious for another example, you can also check out the Elm part of my series on building a notes app using different frontend approaches. I hope you find some of these tips useful on your journey to learning Elm!

Comparing Frontend Approaches Part 7: Final Thoughts

2017-09-27T00:00:00Z

If you’ve made it this far, congratulations! Here’s a brief summary of the pros and cons of each approach for building this particular notes app:

jQuery #

A direct DOM manipulation based approach.
Pros: Easy to install, easy to learn. Smaller in size than most frameworks.
Cons: Requires diligence with organizing code. Making all appropriate DOM updates when something changes can get complex (“jQuery spaghetti”).

Vue.js #

A template based approach (with a virtual DOM under the hood)
Pros: Easy to install, easy to learn. Smallest size in terms lines of code, one of the smallest in terms of payload.
Cons: Non-trivial amount of Vue specific syntax to learn. Can get harder to organize code in the single file and Vue instance as the app increases in complexity.

Vue.js with components #

The same Vue.js approach, this time with components
Pros: Single file components reduces cognitive load. Increased reusability and simplicity with components.
Cons: Requires complex build step. Passing data down and bubbling events up can be tedious with multiple parent-child components.

React #

A virtual DOM based component approach
Pros: Small API surface. Immutable state improves simplicity. Increased reusability and simplicity with components.
Cons: Requires complex build step. Harder to learn with heavy use of advanced and experimental JS features. Functional approach in JS requires particular care.

Elm #

A statically typed, purely functional approach with virtual DOM
Pros: Static types and immutable data prevent runtime errors. Clear code structure with The Elm Architecture. Smallest payload (as of version 0.19).
Cons: Harder to learn (a totally separate language from JS). Side effects require extra work to wire up.

Note that the purpose here has never been to help you choose which frontend approach is “best”. The answer is always it depends on the context. For an app this small in scale, Vue.js (without components) seems like a good fit, especially since it has the smallest payload and the code is well structured. (Edit: Elm version 0.19 has made a lot of optimizations to reduce payload size and currently is significantly smaller than all other approaches here!) But most apps tend to increase in scope, and even your most fundamental assumptions can change as you add, remove, or modify features.

Context also includes a person’s current level of knowledge. What’s easy for you might be hard for someone else, and vice versa. What’s hard for you today may be easy for you a year from now. This means Elm might be a terrible choice for someone with a tight deadline and no experience with functional programming, and yet would be a perfect choice for someone already experienced with Elm. All frontend approaches covered here have great merit, and the honest best choice has more to do with your team and company culture than it does with some definitive “winner”.

Going back to the original idea of learning a new programming language a year, my hope is that you gained a better understanding of how each frontend approach works. This will help you write better code, regardless of your choice of library or framework. I also hope this inspired you to dig deeper into a frontend approach, whether you’re new to functional programming or a React developer who never learned jQuery. Thanks for reading!

Comparing Frontend Approaches Part 6: Elm

2017-09-26T00:00:00Z

In this part we will be implementing the web based clone of the Mac Notes app using Elm. Elm (which is not a JavaScript framework but a completely different language that compiles down to JavaScript) came out in 2012 and is currently gaining a lot of traction, with more and more companies using it in production.

Elm is a statically typed purely functional language inspired by Haskell, but with a design that makes it easier for beginners to functional programming to get started. It uses a virtual DOM approach similar to React (even though the two were created independently). Elm doesn’t use a framework per se, but instead uses a pattern called The Elm Architecture. Let’s dive in and check it out!

Note — this article is not meant to teach Elm from scratch, but rather give an overview of what building an Elm app looks like in comparison to other JavaScript frontend approaches. You don’t need experience with the language to get something out of the article, but if you want a sense of the language before continuing, I would recommend reading this Elm vs. JavaScript syntax comparison and looking over the official guide (which is an excellent resource for learning the language).

Installation #

Like Vue.js with components and React, we’re going to need a build process to use Elm. First we need to install Elm itself if you don’t already have it on your computer:

$ npm install -g elm

Now we’re going to create a new directory and copy the HTML and CSS files from the original notes app template. The only thing left is the JavaScript, which we will generate from Elm code. First run the command:

$ elm init

This will prompt you to create an elm.json file (which is similar to JavaScript’s package.json file). By default it included the necessary dependencies for Elm to work with a web browser.

Next we’re going to create a new file called Notes.elm, which will contain our Elm code. Right now we aren’t going to add any new functionality, we just want to convert the HTML template into Elm code, like we did with React and JSX. However, Elm doesn’t use JSX — it uses plain old functions instead. Here’s what the Notes.elm file looks like:

module Notes exposing (..)

import Html exposing (..)
import Html.Attributes exposing (..)


main =
    div [ id "app" ]
        [ div [ class "toolbar" ]
            [ button [ class "toolbar-button" ] [ text "New" ]
            , button [ class "toolbar-button" ] [ text "Delete" ]
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []
            ]
        , div [ class "note-container" ]
            [ div [ class "note-selectors" ]
                [ div [ class "note-selector active" ]
                    [ p [ class "note-selector-title" ] [ text "First note..." ]
                    , p [ class "note-selector-timestamp" ] [ text "Timestamp here..." ]
                    ]
                , div [ class "note-selector" ]
                    [ p [ class "note-selector-title" ] [ text "Second note..." ]
                    , p [ class "note-selector-timestamp" ] [ text "Timestamp here..." ]
                    ]
                , div [ class "note-selector" ]
                    [ p [ class "note-selector-title" ] [ text "Third note..." ]
                    , p [ class "note-selector-timestamp" ] [ text "Timestamp here..." ]
                    ]
                ]
            , div [ class "note-editor" ]
                [ p [ class "note-editor-info" ] [ text "Timestamp here..." ]
                , textarea [ class "note-editor-input" ] [ text "First note..." ]
                ]
            ]
        ]

This is our first look at Elm code! Some notes:

The first line is defining the code in this file as a module named Notes, which we will refer to later in the HTML.
The next two lines are importing functions from the Html library.
The next line main = is defining the main function. Functions in Elm do not have parentheses or keyword declarations, so they’re a bit hard to notice when coming from JavaScript.
The rest of the code is defining the HTML using functions like div, button, p, etc. Each of these functions take two arguments — a list of attributes and a list of child nodes. So for example, a simple <p> tag would look like p [class "info"] [text "Sample text"]. This app starts with the parent div [ id "app" ] [ … ], and every other HTML element is a child node of this parent and are inside the second argument list (which is a bit hard to see here).
The convention in Elm is to write multi-line lists with commas at the start of each line instead of at the end, which can be pretty jarring coming from languages like JavaScript. The good news is that you can install a tool called elm-format, which can automatically format your Elm code (similar to gofmt for Go and prettier for JavaScript). You can configure it to format your code every time you hit save in your editor, so you don’t need to worry about comma placement, indentation, or other style concerns!

To compile the code, we need to run this command in the terminal:

$ elm make Notes.elm --output js/notes.js

This will use the elm make command line tool to compile the Elm code in Notes.elm into a JavaScript file named notes.js in a folder named js. Note that it will also download the appropriate packages to a new folder called elm-stuff (similar to Node’s node_modules folder).

The last step is to edit the index.html file by removing all the HTML elements that now live in the Elm code and adding code to load up the Elm library:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Notes</title>
  <link rel="stylesheet" href="css/notes.css"></link>
  <script src="js/notes.js"></script>
</head>
<body>
  <div id="app"></div>
    <script>
      var app = Elm.Notes.init({
        node: document.querySelector('#app')
      });
    </script>
</body>
</html>

Open the index.html file in your browser and you should see the familiar notes app starting point! You can see the code so far here for reference.

Display note titles from an array of notes #

Now we can start to make the HTML more dynamic by storing notes as a list (think JS array) of records (think JS objects) and looping through them to generate note selectors. We will do this by structuring the code using The Elm Architecture, which essentially boils down to defining 4 functions that Elm wires together to create the app.

First let’s look at the main function itself. Here we’re using the Browser.element function that does all the work of wiring up our app. All we need to do is define each of the 4 functions — init, view, update, and subscriptions.

main =
    Browser.element
        { init = init
        , view = view
        , update = update
        , subscriptions = subscriptions
        }

Before we look at the 4 functions, let’s first look at how we’re defining the model, which is the data we’re using in our app (think state in React or data in Vue.js). Elm is a statically typed language, so we are defining the types on all the data up front. An individual Note type is defined with the line type alias Note = { id : Int, body : String, timestamp : Int }, which means a note must be a record with an integer id, string body, and integer timestamp. Now we define the Model itself with the line type alias Model = { notes : List Note }. This is saying that the Model must be a record with a key of notes and a value of a list of Note records. Defining these static types up front can seem like extra work, but they help prevent runtime errors later (if you forget to add a timestamp to a new note, etc.).

-- MODEL

type alias Note =
    { id : Int, body : String, timestamp : Int }


type alias Model =
    { notes : List Note }

Now let’s take a look at the init function, which initializes the model. The init function itself has a type annotation of init : () -> ( Model, Cmd Msg ), which means it must return a Model and a Cmd (command). Commands are how Elm handles side effects, which is a significant departure from the world of JavaScript. Elm is a pure functional language, which means functions aren’t allowed to have side effects, so you need different mechanisms to handle them. As of this moment, the init function doesn’t have any need for side effects so we’re outputting no command with Cmd.none. Also note that I’m leaving the timestamps as 0 for now — we need some sort of Elm equivalent to JavaScript’s Date.now(). But if you consider it closely, getting the current time is an impure function with side effects! Which means we actually will need a command in the init function, which we’ll wire up in a bit...

init : () -> ( Model, Cmd Msg )
init _ =
    ( { notes =
            [ { id = 1, body = "First note...", timestamp = 0 }
            , { id = 2, body = "Second note...", timestamp = 0 }
            , { id = 3, body = "Third note...", timestamp = 0 }
            ]
      }
    , Cmd.none
    )

The next function is the update function, which defines how the model gets updated. Right now the update function isn’t doing anything, so this is mostly placeholder code for now. The type annotation for the update function is update : Msg -> Model -> ( Model, Cmd Msg ), which says the function takes in two arguments (a Msg and a Model) and returns a tuple of type ( Model, Cmd Msg ), which contains the updated model and a command for side effects. Right now our app doesn’t have any messages, so we have the line type Msg = NoOp as a placeholder for now — eventually we’ll have messages for selecting notes, clicking on the new button, etc.

-- UPDATE

type Msg
    = NoOp

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    ( model, Cmd.none )

The next function is the subscriptions function, which are used to listen to events. Again, we’re not using subscriptions right now, so this code is essentially doing nothing. Subscriptions are for listening to events like mouse movements, web sockets, etc., which we won’t need for this app.

-- SUBSCRIPTIONS

subscriptions : Model -> Sub Msg
subscriptions model =
    Sub.none

The final function is the view function, which defines the HTML output. This is the same code we started with to generate the HTML, broken down into sub-functions. The view function type annotation is view : Model -> Html Msg, which means it takes in the model (our list of notes) as the argument and outputs HTML.

-- VIEW

view : Model -> Html Msg
view model =
    div [ id "app" ]
        [ div [ class "toolbar" ]
            [ button [ class "toolbar-button" ] [ text "New" ]
            , button [ class "toolbar-button" ] [ text "Delete" ]
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []
            ]
        , div [ class "note-container" ]
            [ viewNoteSelectors model
            , div [ class "note-editor" ]
                [ p [ class "note-editor-info" ] [ text "Timestamp here..." ]
                , textarea [ class "note-editor-input" ] [ text "First note..." ]
                ]
            ]
        ]

viewNoteSelectors : Model -> Html Msg
viewNoteSelectors model =
    div [ class "note-selectors" ]
        (List.map (\note -> viewNoteSelector note) model.notes)

viewNoteSelector : Note -> Html Msg
viewNoteSelector note =
    div [ class "note-selector" ]
        [ p [ class "note-selector-title" ] [ text note.body ]
        , p [ class "note-selector-timestamp" ] [ text (String.fromInt note.timestamp) ]
        ]

You can see the complete Notes.elm file here.

Unlike our React approach, we aren’t going to break this app into components up front, or ever for that matter. We will be breaking things up into functions, but only when there’s a need to do so. In this case I made a sub-function viewNoteSelectors which is responsible for generating the <div class="note-selectors"> HTML. It does this by mapping over the list of notes and calling up the viewNoteSelector function, which takes in a note and outputs the <div class="note-selector"> HTML.

Although this seems like a lot of code to get started, keep in mind that every Elm app will consist of the same 4 functions (init, view, update, and subscriptions). This takes away a lot of the decision fatigue that comes with building frontend apps.

Compute current timestamps #

Now let’s circle back and properly compute the current timestamps. This was trivial in JavaScript, but since it involves side effects it takes more effort to wire up in Elm. First we need to install a new package to handle time:

$ elm install elm/time

Once it’s installed, you would change the code in Notes.elm as follows (I’m not showing the subscriptions and view functions since they didn’t change):

module Notes exposing (..)

import Browser
import Html exposing (..)
import Html.Attributes exposing (..)
import Task
import Time

main =
    Browser.element
        { init = init
        , view = view
        , update = update
        , subscriptions = subscriptions
        }
        
-- MODEL

type alias Note =
    { id : Int, body : String, timestamp : Int }
    
type alias Model =
    { notes : List Note }
    
init : () -> ( Model, Cmd Msg )
init _ =
    ( { notes =
            [ { id = 1, body = "First note...", timestamp = 0 }
            , { id = 2, body = "Second note...", timestamp = 0 }
            , { id = 3, body = "Third note...", timestamp = 0 }
            ]
      }
    , Task.perform InitializeNotesTimestamps Time.now
    )
    
-- UPDATE

type Msg
    = InitializeNotesTimestamps Time.Posix
    
update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        InitializeNotesTimestamps time ->
            ( { model
                | notes = List.map (\note -> { note | timestamp = Time.posixToMillis time }) model.notes
              }
            , Cmd.none
            )
            
-- SUBSCRIPTIONS
-- ...

-- VIEW
-- ...

Let’s break this down piece by piece:

First we import the Task and Time libraries, which are needed to create timestamps.
The init function now runs a command with the Task.perform function, which takes in two arguments — in this case the InitializeTimestamps message and Time.now, which gets the POSIX representation of time when the task is run (similar to JavaScript’s Date.now(), although it isn’t stored in Elm as an integer).
The update section now has something to do! First we change the Msg definition to be a message called InitializeNotesTimestamps (which our init function will send out), which comes with the time result from Time.now.
Now we can change the update function itself to respond to the case where the message is InitializeNotesTimestamps (right now this is the only possibility, but we will be adding more cases soon). In that case the function will update every note with the given time (which in this case must first be converted into milliseconds using Time.posixToMillis).

There’s no doubt that this is quite a bit of work in Elm for something that was trivial in JavaScript. Consider this an up front cost — this architecture provides some absolute guarantees about the safety and structure of the code. The purity in a functional language like Elm makes certain features with side effects harder to implement, but makes it literally impossible to be lazy and write something like jQuery spaghetti.

Use functions to sort and format notes #

Now let’s write more functions, this time to sort and format the notes. Here’s the code in Notes.elm (focusing on the changes in the view function):

-- VIEW

view : Model -> Html Msg  
view model =  
    div [ id "app" ]  
        [ div [ class "toolbar" ]  
            [ button [ class "toolbar-button" ] [ text "New" ]  
            , button [ class "toolbar-button" ] [ text "Delete" ]  
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []  
            ]  
        , div [ class "note-container" ]  
            [ viewNoteSelectors model  
            , div [ class "note-editor" ]  
                [ p [ class "note-editor-info" ] [ text "Timestamp here..." ]  
                , textarea [ class "note-editor-input" ] [ text "First note..." ]  
                ]  
            ]  
        ]

viewNoteSelectors : Model -> Html Msg  
viewNoteSelectors model =  
    div [ class "note-selectors" ]  
    (model.notes  
            |> List.sortBy .timestamp  
            |> List.reverse  
            |> List.map (note -> viewNoteSelector note)  
        )

viewNoteSelector : Note -> Html Msg  
viewNoteSelector note =  
    div [ class "note-selector" ]  
        [ p [ class "note-selector-title" ] [ text (formatTitle note.body) ]  
        , p [ class "note-selector-timestamp" ] [ text (formatTimestamp note.timestamp) ]  
        ]

-- HELPERS

formatTitle : String -> String  
formatTitle body =  
    let  
        maxLength =  
            20  
        length =  
            String.length body  
    in  
    if length > maxLength then  
        String.left (maxLength - 3) body ++ "..."  
    else if length == 0 then  
        "New note"  
    else  
        body

formatTimestamp : Int -> String  
formatTimestamp timestamp =  
    let  
        time =  
            Time.millisToPosix timestamp  
        hour =  
            String.fromInt (Time.toHour Time.utc time)  
        minute =  
            String.fromInt (Time.toMinute Time.utc time)  
        second =  
            String.fromInt (Time.toSecond Time.utc time)  
    in  
    hour ++ ":" ++ minute ++ ":" ++ second ++ " UTC"

Let’s go over the changes one at a time:

In the viewNoteSelectors function, we are adding extra function calls to sort the notes by timestamp in reverse order. Note the use of the |> operator, which is an alternative syntax for passing arguments to functions ((arg |> func) is the same as (func arg)), which helps reduce parentheses.
In the viewNoteSelector function, we are using the formatTitle and formatTimestamp functions, defined below.
The formatTitle function is using the same logic we’ve used in the past. Note the use of the let...in... syntax, which is required when creating temporary variables in a function.
The formatTimestamp function uses the Date library to format the given timestamp (like JavaScript’s .toUTCString()). I’m also using String.slice to remove parts of the formatted string that aren’t needed.

Note that the formatted timestamp isn’t as detailed as JavaScript’s .toUTCString(). Elm doesn’t come with an equivalent function, so I’m using a simplified formatting helper function that only returns the hours/minutes/seconds. To make it more detailed can get quite involved (getting the user’s time zone, formatting weekday, month names, etc.), which is outside the scope of this article, so the simplified function will do for now.

Select a note on title click #

Now let’s implement the ability to actually select notes. Clicking on a note title should both highlight the selected note on the left as well as display the contents in the editor on the right. The code in Notes.elm will change accordingly:

module Notes exposing (..)
  
import Browser  
import Html exposing (..)  
import Html.Attributes exposing (..)  
import Html.Events exposing (..)  
import Task  
import Time  
  
  
main =  
    Browser.element  
        { init = init  
        , view = view  
        , update = update  
        , subscriptions = subscriptions  
        }  
  
  
  
-- MODEL  
  
  
type alias Note =  
    { id : Int, body : String, timestamp : Int }  
  
  
type alias Model =  
    { notes : List Note, selectedNoteId : Int }  
  
  
init : () -> ( Model, Cmd Msg )  
init _ =  
    ( { notes =  
            [ { id = 1, body = "First note...", timestamp = 0 }  
            , { id = 2, body = "Second note...", timestamp = 0 }  
            , { id = 3, body = "Third note...", timestamp = 0 }  
            ]  
      , selectedNoteId = 1  
      }  
    , Task.perform InitializeNotesTimestamps Time.now  
    )  
  
  
  
-- UPDATE  
  
  
type Msg  
    = InitializeNotesTimestamps Time.Posix  
    | SelectNote Int  
  
  
update : Msg -> Model -> ( Model, Cmd Msg )  
update msg model =  
    case msg of  
        InitializeNotesTimestamps time ->  
            ( { model  
                | notes = List.map (\note -> { note | timestamp = Time.posixToMillis time }) model.notes  
              }  
            , Cmd.none  
            )

        SelectNote id ->  
            ( { model | selectedNoteId = id }, Cmd.none )  
  
  
  
-- SUBSCRIPTIONS  
  
  
subscriptions : Model -> Sub Msg  
subscriptions model =  
    Sub.none  
  
  
  
-- VIEW  
  
  
view : Model -> Html Msg  
view model =  
    div [ id "app" ]  
        [ div [ class "toolbar" ]  
            [ button [ class "toolbar-button" ] [ text "New" ]  
            , button [ class "toolbar-button" ] [ text "Delete" ]  
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []  
            ]  
        , div [ class "note-container" ]  
            [ viewNoteSelectors model  
            , viewNoteEditor model  
            ]  
        ]  
  
  
viewNoteSelectors : Model -> Html Msg  
viewNoteSelectors model =  
    div [ class "note-selectors" ]  
        (model.notes  
            |> List.sortBy .timestamp  
            |> List.reverse  
            |> List.map (\note -> viewNoteSelector note model.selectedNoteId)  
        )  
  
  
viewNoteSelector : Note -> Int -> Html Msg  
viewNoteSelector note selectedNoteId =  
 div [ classList [ ( "note-selector", True ), ( "active", note.id == selectedNoteId ) ], onClick (SelectNote note.id) ]  
        [ p [ class "note-selector-title" ] [ text (formatTitle note.body) ]  
        , p [ class "note-selector-timestamp" ] [ text (formatTimestamp note.timestamp) ]  
        ]  
  
  
viewNoteEditor : Model -> Html Msg  
viewNoteEditor model =  
    case model.notes |> List.filter (\note -> note.id == model.selectedNoteId) |> List.head of  
        Nothing ->  
            div [ class "note-editor" ] []  
  
        Just selectedNote ->  
            div [ class "note-editor" ]  
                [ p [ class "note-editor-info" ] [ text (formatTimestamp selectedNote.timestamp) ]  
                , textarea [ class "note-editor-input" ] [ text selectedNote.body ]  
                ]

-- HELPERS

formatTitle : String -> String  
formatTitle body =  
    let  
        maxLength =  
            20

    length =  
            String.length body  
    in  
    if length > maxLength then  
        String.left (maxLength - 3) body ++ "..."

    else if length == 0 then  
        "New note"

    else  
        body

formatTimestamp : Int -> String  
formatTimestamp timestamp =  
    let  
        time =  
            Time.millisToPosix timestamp

        hour =  
            String.fromInt (Time.toHour Time.utc time)

        minute =  
            String.fromInt (Time.toMinute Time.utc time)

        second =  
            String.fromInt (Time.toSecond Time.utc time)  
    in  
    hour ++ ":" ++ minute ++ ":" ++ second ++ " UTC"

Let’s go over the changes one at a time:

First we import the Html.Events functions, which we will use later.
In the MODEL section, we are adding a new piece of data to keep track of in the model — the selectedNoteId, which we initialize to 1 to start off.
In the UPDATE section, we add a union type to Msg — now it can be a InitializeTimestamps or a SelectNote message. So we also add another case to the update function — if the message is SelectNote, we will update the selectedNoteId in the model accordingly.
In the VIEW section, the viewNoteSelector function has the code onClick (SelectNote note.id), which is binding the DOM click event to trigger the SelectNote message with the note’s id.
In the VIEW section, the viewNoteSelector function also changed to take in one more argument, the selectedNoteId. This enables us to apply the right CSS active class to the div if the note is the selected note with the code classList [ ( "note-selector", True ), ( "active", note.id == selectedNoteId ) ].
In the VIEW section, we also extracted the code which generates the <div class="note-editor"> into a separate function called viewNoteEditor. This function uses the model notes and selectedNoteId data to identify which note matches the selectedNoteId. If nothing matches, the note editor will be an empty div. If there is a match, then the note editor will show the editor with the appropriate formatted timestamp and body.

Here we see another benefit of Elm — it forces you to deal with the case where the selectedNoteId doesn’t match any of the notes. There’s literally no other way to write the code and have it compile. The zero notes scenario wasn’t going to be a problem until we implemented the delete functionality, but it’s reassuring to know that these safety guarantees are built in from the start!

Edit the selected note on editor input #

At this point we can select a note and it highlights accordingly, but the content of the selected note aren’t showing up in the note editor. We also need to be able to update the selected note as the user enters text in the editor. Here’s how the UPDATE and VIEW sections of the code would change in Notes.elm:

-- UPDATE  
  
  
type Msg  
    = InitializeNotesTimestamps Time.Posix  
    | SelectNote Int  
    | UpdateSelectedNoteBody String  
    | UpdateSelectedNoteTimestamp Time.Posix  
  
  
update : Msg -> Model -> ( Model, Cmd Msg )  
update msg model =  
    case msg of  
        InitializeNotesTimestamps time ->  
            ( { model  
                | notes = List.map (\note -> { note | timestamp = Time.posixToMillis time }) model.notes  
              }  
            , Cmd.none  
            )  
  
        SelectNote id ->  
            ( { model | selectedNoteId = id }, Cmd.none )  
  
        UpdateSelectedNoteBody newText ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | body = newText }  
  
                            else  
                                note  
  
                        newNotes =  
                            List.map updateSelectedNote model.notes  
                    in  
                    ( { model | notes = newNotes }  
                    , Task.perform UpdateSelectedNoteTimestamp Time.now  
                    )  
  
        UpdateSelectedNoteTimestamp newTime ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | timestamp = Time.posixToMillis newTime }  
  
                            else  
                                note  
  
                        newNotes =  
                            List.map updateSelectedNote model.notes  
                    in  
                    ( { model | notes = newNotes }, Cmd.none )  
  
  
  
-- SUBSCRIPTIONS  
  
  
subscriptions : Model -> Sub Msg  
subscriptions model =  
    Sub.none  
  
  
  
-- VIEW  
  
  
view : Model -> Html Msg  
view model =  
    div [ id "app" ]  
        [ div [ class "toolbar" ]  
            [ button [ class "toolbar-button" ] [ text "New" ]  
            , button [ class "toolbar-button" ] [ text "Delete" ]  
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []  
            ]  
        , div [ class "note-container" ]  
            [ viewNoteSelectors model  
            , viewNoteEditor model  
            ]  
        ]  
  
  
viewNoteSelectors : Model -> Html Msg  
viewNoteSelectors model =  
    div [ class "note-selectors" ]  
        (model.notes  
            |> List.sortBy .timestamp  
            |> List.reverse  
            |> List.map (\note -> viewNoteSelector note model.selectedNoteId)  
        )  
  
  
viewNoteSelector : Note -> Int -> Html Msg  
viewNoteSelector note selectedNoteId =  
    div [ classList [ ( "note-selector", True ), ( "active", note.id == selectedNoteId ) ], onClick (SelectNote note.id) ]  
        [ p [ class "note-selector-title" ] [ text (formatTitle note.body) ]  
        , p [ class "note-selector-timestamp" ] [ text (formatTimestamp note.timestamp) ]  
        ]  
  
  
viewNoteEditor : Model -> Html Msg  
viewNoteEditor model =  
    case getSelectedNote model of  
        Nothing ->  
            div [ class "note-editor" ] []  
  
        Just selectedNote ->  
            div [ class "note-editor" ]  
                [ p [ class "note-editor-info" ] [ text (formatTimestamp selectedNote.timestamp) ]  
                , textarea [ class "note-editor-input", onInput UpdateSelectedNoteBody, value selectedNote.body ] []  
                ]  
  
  
  
-- HELPERS  
  
  
getSelectedNote : Model -> Maybe Note  
getSelectedNote model =  
    model.notes |> List.filter (\note -> note.id == model.selectedNoteId) |> List.head

Let’s examine the changes:

In the UPDATE section, the Msg now gets two more types — UpdateSelectedNoteBody and UpdateSelectedNoteTimestamp. The two are related — if the user enters text in the note editor, it will trigger the UpdateSelectedNoteBody case in the update function, which will update the body of the selected note. When it’s done, it will trigger the Time.now task, which will trigger the UpdateSelectedNoteTimestamp message when it’s ready. When the update function is called with the UpdateSelectedNoteTimestamp case, it will update the selected note with the given time. Note that it has to determine which note matches the selectedNoteId, which is logic we’ve already defined, so I’ve extracted the logic into a function called getSelectedNote which is defined later.
In the VIEW section, we’ve refactored the viewNoteEditor to use the getSelectedNote function. We are also adding new attributes to the textarea element with the line textarea [ class "note-editor-input", onInput InputNoteBody, value selectedNote.body ] []. This is binding the DOM input event to trigger the UpdateSelectedNoteBody message, as well as binding the selected note’s body to the textarea value.
In the HELPERS section, we define the getSelectedNote method, which is just the extracted logic of finding the selected note as before.

Create a new note with a button #

Now let’s implement the ability to create a new note. Clicking on the “New” button should create a new note (new id, no body, current timestamp). The new note should become the currently selected note and appear at the top of the list of note selectors. Here’s how the UPDATE and VIEW sections of the code would change in Notes.elm:

-- UPDATE  
  
  
type Msg  
    = InitializeNotesTimestamps Time.Posix  
    | SelectNote Int  
    | UpdateSelectedNoteBody String  
    | UpdateSelectedNoteTimestamp Time.Posix  
    | ClickNew  
    | CreateNote Time.Posix  
  
  
update : Msg -> Model -> ( Model, Cmd Msg )  
update msg model =  
    case msg of  
        InitializeTimestamps time ->  
            ( { model  
                | notes = List.map (\note -> { note | timestamp = time }) model.notes  
              }  
            , Cmd.none  
            )  
  
        SelectNote id ->  
            ( { model | selectedNoteId = id }, Cmd.none )  
  
        InputNoteBody newText ->  
            ( model, Time.now |> Task.perform (UpdateNote newText) )  
  
        UpdateNote newText newTimestamp ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | body = newText, timestamp = newTimestamp }  
                            else  
                                note  
                    in  
                    ( { model | notes = List.map updateSelectedNote model.notes }  
                    , Cmd.none  
                    )  
  
        ClickNew ->  
            ( model, Time.now |> Task.perform CreateNote )  
  
        CreateNote newTimestamp ->  
            let  
                newId =  
                    round (Time.inMilliseconds newTimestamp)  
            in  
            ( { model  
                | notes = [ { id = newId, body = "", timestamp = newTimestamp } ] ++ model.notes  
                , selectedNoteId = newId  
              }  
            , Cmd.none  
            )  
  
  
  
-- VIEW  
  
  
view : Model -> Html Msg  
view model =  
    div [ id "app" ]  
        [ div [ class "toolbar" ]  
            [ button [ class "toolbar-button", onClick ClickNew ] [ text "New" ]  
            , button [ class "toolbar-button" ] [ text "Delete" ]  
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []  
            ]  
        , div [ class "note-container" ]  
            [ viewNoteSelectors model  
            , viewNoteEditor model  
            ]  
        ]

Let’s examine the changes:

In the UPDATE section, the Msg now gets two more types — ClickNew and CreateNote. The two are related — if the user clicks the “New” button, it will trigger the ClickNew message, which will in turn trigger the Time.now task which will run the CreateNote message when it’s ready. At that point the CreateNote case in the update function will have the timestamp and can update the model with a new note and selectedNoteId.
In the VIEW section, the only thing that changes is the “New” button — we add an onClick ClickNew attribute to the button, which binds the DOM on click event to trigger the ClickNew message.

Here we’re really starting to see the beauty of The Elm Architecture. Features like this are very simple to wire up, without any of the overhead that we saw with different JavaScript component approaches where we had to pass around a lot of info between parents and children.

Delete the selected note with a button #

Wiring up this feature is pretty similar to the new note feature, with a couple of extra considerations. Here’s how the UPDATE and VIEW sections of the code would change in Notes.elm:

-- UPDATE  
  
  
type Msg  
    = InitializeNotesTimestamps Time.Posix  
    | SelectNote Int  
    | UpdateSelectedNoteBody String  
    | UpdateSelectedNoteTimestamp Time.Posix  
    | ClickNew  
    | CreateNote Time.Posix 
    | ClickDelete  
  
  
update : Msg -> Model -> ( Model, Cmd Msg )  
update msg model =  
    case msg of  
        InitializeNotesTimestamps time ->  
            ( { model  
                | notes = List.map (\note -> { note | timestamp = Time.posixToMillis time }) model.notes  
              }  
            , Cmd.none  
            )  
  
        SelectNote id ->  
            ( { model | selectedNoteId = id }, Cmd.none )  
  
        UpdateSelectedNoteBody newText ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | body = newText }  
  
                            else  
                                note  
  
                        newNotes =  
                            List.map updateSelectedNote model.notes  
                    in  
                    ( { model | notes = newNotes }  
                    , Task.perform UpdateSelectedNoteTimestamp Time.now  
                    )  
  
        UpdateSelectedNoteTimestamp newTime ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | timestamp = Time.posixToMillis newTime }  
  
                            else  
                                note  
  
                        newNotes =  
                            List.map updateSelectedNote model.notes  
                    in  
                    ( { model | notes = newNotes }, Cmd.none )  
  
        ClickNew ->  
            ( model, Task.perform CreateNote Time.now )  
  
        CreateNote newTime ->  
            let  
                newTimestamp =  
                    Time.posixToMillis newTime  
  
                newId =  
                    newTimestamp  
            in  
            ( { model  
                | notes = [ { id = newId, body = "", timestamp = newTimestamp } ] ++ model.notes  
                , selectedNoteId = newId  
              }  
            , Cmd.none  
            )

        ClickDelete ->  
            let  
                newNotes =  
                    List.filter (\note -> note.id /= model.selectedNoteId) model.notes  
  
                firstVisibleNote =  
                    newNotes |> sortNotes |> List.head  
            in  
            case firstVisibleNote of  
                Nothing ->  
                    ( { model | notes = newNotes }, Cmd.none )  
  
                Just availableNote ->  
                    ( { model | notes = newNotes, selectedNoteId = availableNote.id }, Cmd.none )  
  

  
-- VIEW  
  
  
view : Model -> Html Msg  
view model =  
    div [ id "app" ]  
        [ div [ class "toolbar" ]  
            [ button [ class "toolbar-button", onClick ClickNew ] [ text "New" ]  
            , button [ class "toolbar-button", onClick ClickDelete ] [ text "Delete" ]  
            , input [ class "toolbar-search", type_ "text", placeholder "Search..." ] []  
            ]  
        , div [ class "note-container" ]  
            [ viewNoteSelectors model  
            , viewNoteEditor model  
            ]  
        ]  
  
  
viewNoteSelectors : Model -> Html Msg  
viewNoteSelectors model =  
    div [ class "note-selectors" ]  
        (model.notes  
            |> sortNotes  
            |> List.map (\note -> viewNoteSelector note model.selectedNoteId)  
        )  
  
  
viewNoteSelector : Note -> Int -> Html Msg  
viewNoteSelector note selectedNoteId =  
    div [ classList [ ( "note-selector", True ), ( "active", note.id == selectedNoteId ) ], onClick (SelectNote note.id) ]  
        [ p [ class "note-selector-title" ] [ text (formatTitle note.body) ]  
        , p [ class "note-selector-timestamp" ] [ text (formatTimestamp note.timestamp) ]  
        ]  
  
  
viewNoteEditor : Model -> Html Msg  
viewNoteEditor model =  
    case getSelectedNote model of  
        Nothing ->  
            div [ class "note-editor" ] []  
  
        Just selectedNote ->  
            div [ class "note-editor" ]  
                [ p [ class "note-editor-info" ] [ text (formatTimestamp selectedNote.timestamp) ]  
                , textarea [ class "note-editor-input", onInput UpdateSelectedNoteBody, value selectedNote.body ] []  
                ]  
  
  
  
-- HELPERS  
  
  
sortNotes : List Note -> List Note  
sortNotes notes =  
    notes |> List.sortBy .timestamp |> List.reverse

Let’s examine the changes:

In the UPDATE section, the Msg now one more type— ClickDelete, which will be wired up to run whenever the user clicks the “Delete” button. The update function with the ClickDelete case has to both delete the selected note (using List.filter) and select a new note, which should be the top of the sorted notes. Here I extracted the logic to sort the notes into a separate sortNotes function (defined later) to keep the code DRY.
In the VIEW section, the only significant change is the “Delete” button — we add an onClick ClickDelete attribute to the button, which binds the DOM on click event to trigger the ClickDelete message. The only other change is refactoring the viewNoteSelectors function to use the sortNotes function to keep the code DRY.

Again, this change was a lot simpler to make compared to our other approaches, particularly in this case because Elm forced us to handle the case of no notes earlier!

Filter notes on search input #

The final feature is to be able to search notes immediately as you type in the search input. Since this is the last feature, let’s look at the code in Notes.elm in its entirety:

module Notes exposing (..)  
  
import Browser  
import Html exposing (..)  
import Html.Attributes exposing (..)  
import Html.Events exposing (..)  
import Task  
import Time  
  
  
main =  
    Browser.element  
        { init = init  
        , view = view  
        , update = update  
        , subscriptions = subscriptions  
        }  
  
  
  
-- MODEL  
  
  
type alias Note =  
    { id : Int, body : String, timestamp : Int }  
  
  
type alias Model =  
    { notes : List Note, selectedNoteId : Int, searchNoteText : String }  
  
  
init : () -> ( Model, Cmd Msg )  
init _ =  
    ( { notes =  
            [ { id = 1, body = "First note...", timestamp = 0 }  
            , { id = 2, body = "Second note...", timestamp = 0 }  
            , { id = 3, body = "Third note...", timestamp = 0 }  
            ]  
      , selectedNoteId = 1  
      , searchNoteText = ""  
      }  
    , Task.perform InitializeNotesTimestamps Time.now  
    )  
  
  
  
-- UPDATE  
  
  
type Msg  
    = InitializeNotesTimestamps Time.Posix  
    | SelectNote Int  
    | UpdateSelectedNoteBody String  
    | UpdateSelectedNoteTimestamp Time.Posix  
    | ClickNew  
    | CreateNote Time.Posix  
    | ClickDelete  
    | InputSearch String  
  
  
update : Msg -> Model -> ( Model, Cmd Msg )  
update msg model =  
    case msg of  
        InitializeNotesTimestamps time ->  
            ( { model  
                | notes = List.map (\note -> { note | timestamp = Time.posixToMillis time }) model.notes  
              }  
            , Cmd.none  
            )  
  
        SelectNote id ->  
            ( { model | selectedNoteId = id }, Cmd.none )  
  
        UpdateSelectedNoteBody newText ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | body = newText }  
  
                            else  
                                note  
  
                        newNotes =  
                            List.map updateSelectedNote model.notes  
                    in  
                    ( { model | notes = newNotes }  
                    , Task.perform UpdateSelectedNoteTimestamp Time.now  
                    )  
  
        UpdateSelectedNoteTimestamp newTime ->  
            case getSelectedNote model of  
                Nothing ->  
                    ( model, Cmd.none )  
  
                Just selectedNote ->  
                    let  
                        updateSelectedNote note =  
                            if note.id == model.selectedNoteId then  
                                { note | timestamp = Time.posixToMillis newTime }  
  
                            else  
                                note  
  
                        newNotes =  
                            List.map updateSelectedNote model.notes  
                    in  
                    ( { model | notes = newNotes }, Cmd.none )  
  
        ClickNew ->  
            ( model, Task.perform CreateNote Time.now )  
  
        CreateNote newTime ->  
            let  
                newTimestamp =  
                    Time.posixToMillis newTime  
  
                newId =  
                    newTimestamp  
            in  
            ( { model  
                | notes = [ { id = newId, body = "", timestamp = newTimestamp } ] ++ model.notes  
                , selectedNoteId = newId  
              }  
            , Cmd.none  
            )  
  
        ClickDelete ->  
            let  
                newNotes =  
                    List.filter (\note -> note.id /= model.selectedNoteId) model.notes  
  
                firstVisibleNote =  
                    getFirstVisibleNote newNotes model.searchNoteText  
            in  
            case firstVisibleNote of  
                Nothing ->  
                    ( { model | notes = newNotes }, Cmd.none )  
  
                Just availableNote ->  
                    ( { model | notes = newNotes, selectedNoteId = availableNote.id }, Cmd.none )  
  
        InputSearch searchNoteText ->  
            let  
                firstVisibleNote =  
                    getFirstVisibleNote model.notes searchNoteText  
            in  
            case firstVisibleNote of  
                Nothing ->  
                    ( { model | searchNoteText = searchNoteText, selectedNoteId = -1 }, Cmd.none )  
  
                Just availableNote ->  
                    ( { model | searchNoteText = searchNoteText, selectedNoteId = availableNote.id }, Cmd.none )  
  
  
  
-- SUBSCRIPTIONS  
  
  
subscriptions : Model -> Sub Msg  
subscriptions model =  
    Sub.none  
  
  
  
-- VIEW  
  
  
view : Model -> Html Msg  
view model =  
    div [ id "app" ]  
        [ div [ class "toolbar" ]  
            [ button [ class "toolbar-button", onClick ClickNew ] [ text "New" ]  
            , button [ class "toolbar-button", onClick ClickDelete ] [ text "Delete" ]  
            , input [ class "toolbar-search", type_ "text", placeholder "Search...", onInput InputSearch ] []  
            ]  
        , div [ class "note-container" ]  
            [ viewNoteSelectors model  
            , viewNoteEditor model  
            ]  
        ]  
  
  
viewNoteSelectors : Model -> Html Msg  
viewNoteSelectors model =  
    div [ class "note-selectors" ]  
        (model.notes  
            |> transformNotes model.searchNoteText  
            |> List.map (\note -> viewNoteSelector note model.selectedNoteId)  
        )  
  
  
viewNoteSelector : Note -> Int -> Html Msg  
viewNoteSelector note selectedNoteId =  
    div [ classList [ ( "note-selector", True ), ( "active", note.id == selectedNoteId ) ], onClick (SelectNote note.id) ]  
        [ p [ class "note-selector-title" ] [ text (formatTitle note.body) ]  
        , p [ class "note-selector-timestamp" ] [ text (formatTimestamp note.timestamp) ]  
        ]  
  
  
viewNoteEditor : Model -> Html Msg  
viewNoteEditor model =  
    case getSelectedNote model of  
        Nothing ->  
            div [ class "note-editor" ] []  
  
        Just selectedNote ->  
            div [ class "note-editor" ]  
                [ p [ class "note-editor-info" ] [ text (formatTimestamp selectedNote.timestamp) ]  
                , textarea [ class "note-editor-input", onInput UpdateSelectedNoteBody, value selectedNote.body ] []  
                ]  
  
  
  
-- HELPERS  
  
  
getFirstVisibleNote : List Note -> String -> Maybe Note  
getFirstVisibleNote notes searchText =  
    notes  
        |> transformNotes searchText  
        |> List.head  
  
  
transformNotes : String -> List Note -> List Note  
transformNotes searchNoteText notes =  
    notes  
        |> List.filter (\note -> String.contains (String.toLower searchNoteText) (String.toLower note.body))  
        |> List.sortBy .timestamp  
        |> List.reverse  
  
  
getSelectedNote : Model -> Maybe Note  
getSelectedNote model =  
    model.notes  
        |> transformNotes model.searchNoteText  
        |> List.filter (\note -> note.id == model.selectedNoteId)  
        |> List.head  
  
  
formatTitle : String -> String  
formatTitle body =  
    let  
        maxLength =  
            20  
  
        length =  
            String.length body  
    in  
    if length > maxLength then  
        String.left (maxLength - 3) body ++ "..."  
  
    else if length == 0 then  
        "New note"  
  
    else  
        body  
  
  
formatTimestamp : Int -> String  
formatTimestamp timestamp =  
    let  
        time =  
            Time.millisToPosix timestamp  
  
        hour =  
            String.fromInt (Time.toHour Time.utc time)  
  
        minute =  
            String.fromInt (Time.toMinute Time.utc time)  
  
        second =  
            String.fromInt (Time.toSecond Time.utc time)  
    in  
    hour ++ ":" ++ minute ++ ":" ++ second ++ " UTC"

Let’s examine the changes:

In the MODEL section, we are adding a new piece of data to keep track of in the model — the searchNoteText, which we initialize to an empty string.
In the UPDATE section, the Msg now one more type— InputSearch, which will be wired up to run whenever the user enters text in the search input. The update function with the InputSearch case has to filter notes that match the searchNoteText as well as select the first visible note. Since I already had logic in the ClickDelete case for getting the first visible note, I extracted it into a method called getFirstVisibleNote to be DRY and use it in both the ClickDelete and InputSearch cases.
In the VIEW section, we add an onInput InputSearch attribute to the button, which binds the DOM input event to trigger the InputSearch message. We also change the viewNoteSelectors function to not use sortNotes function and use transformNotes instead, which both filters the list of notes as well as sorts them.
After the VIEW section, we define the new helper functions getFirstVisibleNote as well as transformNotes (which used to be sortNotes).

There may be some further refactoring that can be done to make the use of transformNotes more clear. The beauty of Elm is that the compiler works well enough to give you confidence when making such refactors — if it compiles, it works.

The only file we’ve been changing this whole time is Notes.elm, which you see above. If you’re curious, you can check out the entire project at this repository. (Side note — if you’re not a fan of having all the code in one file, there are definite patterns you can use to organize your code, but they won’t necessarily be the same patterns you may be used to in JavaScript. Check out Richard Feldman’s talk on scaling Elm apps to get a sense of what I mean!)

Conclusion #

Working with Elm is a pretty large departure from every other framework we looked at. It’s a purely functional language, which means it provides certain guarantees that a JavaScript framework simply can’t. React uses functional patterns like immutability, but since JavaScript is not an immutable language you’re required to work harder to avoid breaking the code. Programming in React often comes with using libraries like Immutable.js for immutable types and Flow for static type checking, essentially bolting on language features onto JavaScript that it doesn’t naturally support. Using Elm makes the whole process much smoother to work with.

The downsides to Elm are the learning curve and dealing with the outside world. For the learning curve, Elm works hard to utilize difficult functional concepts in a way that’s easy to get started. The best way to learn Elm isn’t to try and master the language — it’s to start building apps and learn as you go. The other downside is dealing with the outside world — as we saw, something as simple as getting a timestamp was fairly involved to wire up in Elm. Working with HTTP requests, JSON responses, WYSIWYG editors — these all require a lot more work compared to quick and dirty (but dangerous) JavaScript approaches.

In the last part of this series, I’ll wrap up with some final thoughts about each frontend approach and how you might choose the right tool for the job. Stay tuned!

Comparing Frontend Approaches Part 5: React

2017-09-23T00:00:00Z

In this part we will be implementing the web based clone of the Mac Notes app using React. React is a JavaScript framework that was created around 2011 and open-sourced in 2013. It currently has won over developer mindshare in a big way and is the most popular framework in 2017 by various metrics (over 75,000 stars on GitHub).

React pioneered the virtual DOM approach (at least in JavaScript frameworks), where the HTML is completely generated through JavaScript instead of a template. It also was one of the first frontend frameworks to push for a completely component centered approach. Unlike Vue.js, which bills itself as a progressive framework (i.e., you don’t need to start with components, you can work your way up there), React is a bit more insistent (the very first step they recommend is to break the UI into components). Let’s see what it looks like in practice!

Note — this isn’t meant to be a tutorial for people completely new to React. In particular, React uses a lot of new JavaScript ES2015+ features, which I won’t be covering in full detail. You can check out this resource first if you’d like an overview of these new features before reading this post.

Installation #

Like Vue.js with components, getting started with React can be a bit tricky, since writing code with components involves bundling code in separate files, requiring a build step. Fortunately, like Vue.js, React offers an official command line tool to scaffold your projects, called Create React App. If you don’t already have it installed, you can install it with the command:

$ npm install -g create-react-app

Once you have it installed, you can navigate to the directory you want to create your project in and run:

$ create-react-app my-app

You should replace my-app with whatever name you want your particular project to have. This will take a little while to create files and folders and download the necessary packages from npm. In the end you will end up a new folder called my-app with the following project structure:

my-app
├── README.md
├── node_modules
├── package.json
├── .gitignore
├── public
│   └── favicon.ico
│   └── index.html
│   └── manifest.json
└── src
    └── App.css
    └── App.js
    └── App.test.js
    └── index.css
    └── index.js
    └── logo.svg
    └── registerServiceWorker.js

Again, even though there’s a lot of files, you don’t need to worry about most of them for right now — pretty much all of our work will be in the src directory. At this point you already have a hello world app built for you, which you can see by entering the following commands:

$ cd my-app$ npm start

The last command will run a dev server and automatically open up your browser to localhost:3000, where you should see something like this:

This is pretty cool, and what’s cooler is that you have a hot-reloading environment already set up for you. What that means is that if you make changes to your code, the browser at localhost:3000 will automatically refresh. As it says, the place to start making changes is src/App.js, which right now looks like this:

import React, { Component } from "react";
import logo from "./logo.svg";
import "./App.css";

class App extends Component {
  render() {
    return (
      <div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <h1 className="App-title">Welcome to React</h1>
        </header>
        <p className="App-intro">
          To get started, edit <code>src/App.js</code> and save to reload.
        </p>
      </div>
    );
  }
}

export default App;

This is a React component — it makes heavy use of both ES2015 JavaScript features (imports, destructuring, classes) as well as JSX. JSX is syntax which allows you to write what looks like HTML in the middle of your JavaScript (it’s not actually HTML, it gets converted into JavaScript statements during a build step). So your HTML template is defined in your JavaScript, there are no separate files for your HTML. In this example, the CSS is defined in the separate App.css file and is imported into the JavaScript as well. This means we can install our notes template by changing src/App.js as follows:

import React, { Component } from "react";
import "./App.css";

class App extends Component {
  render() {
    return (
      <div id="app">
        <div className="toolbar">
          <button className="toolbar-button">New</button>
          <button className="toolbar-button">Delete</button>
          <input className="toolbar-search" type="text" placeholder="Search..." />
        </div>
        <div className="note-container">
          <div className="note-selectors">
            <div className="note-selector active">
              <p className="note-selector-title">First note...</p>
              <p className="note-selector-timestamp">Timestamp here...</p>
            </div>
            <div className="note-selector">
              <p className="note-selector-title">Second note...</p>
              <p className="note-selector-timestamp">Timestamp here...</p>
            </div>
            <div className="note-selector">
              <p className="note-selector-title">Third note...</p>
              <p className="note-selector-timestamp">Timestamp here...</p>
            </div>
          </div>
          <div className="note-editor">
            <p className="note-editor-info">Timestamp here...</p>
            <textarea className="note-editor-input"></textarea>
          </div>
        </div>
      </div>
    );
  }
}

export default App;

Note that I had to convert the HTML to JSX, which is mostly the same but with minor differences to keep the syntax compatible with JavaScript. In this case, the HTML class attribute had to be renamed to className (since class is a reserved word in JavaScript). Once the JavaScript is set up, we can add the note template’s CSS in the App.css file as follows:

/* RESET */
* {
  margin: 0;
  padding: 0;
  border: 0;
  outline: none;
  box-sizing: border-box;
}

/* LAYOUT */
#app {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
}
.toolbar {
  padding: 0.5em;
}
.toolbar-button,
.toolbar-search {
  padding: inherit;
  border-radius: 0.3em;
}
.toolbar-search {
  float: right;
}
.note-container {
  display: flex;
  flex: 1;
}
.note-selectors {
  flex: 0 0 13em;
}
.note-selector {
  padding: 1em;
}
.note-selector p {
  margin: 0;
}
.note-editor {
  display: flex;
  flex: 1;
  flex-direction: column;
}
.note-editor-info {
  padding: 0.5em;
  text-align: center;
}
.note-editor-input {
  display: flex;
  flex: 1;
  width: 100%;
  padding: 0 2em 0 2em;
}

/* COLORS */
* {
  color: #454545;
  background-color: #fafaf8;
}
.toolbar {
  background-color: #dcdadc;
}
.toolbar-button {
  background-color: #ffffff;
}
.toolbar-button:active {
  background-color: #aaaaaa;
}
.note-selectors {
  border-right: 1px solid #dcdadc;
}
.note-selector {
  border-bottom: 1px solid #dcdadc;
}
.note-selector.active {
  background-color: #fce18d;
}
.note-selector-title {
  background-color: inherit;
}
.note-selector-timestamp {
  color: #626262;
  background-color: inherit;
}
.note-editor-info {
  color: #dcdadc;
}

/* TYPOGRAPHY */
body {
  font-family: sans-serif;
}
.note-selector-title {
  font-weight: bold;
}
.note-selector-timestamp {
  font-size: 0.7em;
}
.note-editor,
.note-editor-input {
  font-size: 0.9em;
}

If you look at your browser, you should see our familiar notes app starting point!

Refactor into components #

The next step is to break this src/App.js file into components. Here is a diagram of the different components we can break this app into:

<App>
├── <Toolbar>
└── <NoteContainer>
    ├── <NoteSelectors>
    │   └── <NoteSelector>
    │   └── <NoteSelector>
    │   └── <NoteSelector>
    └── <NoteEditor>

You could of course break it down even further (with individual button components for the toolbar for example), but this is a good starting point. Using this structure, the src/App.js file would now look like:

import React, { Component } from "react";
import Toolbar from "./components/Toolbar";
import NoteContainer from "./components/NoteContainer";
import "./App.css";

class App extends Component {
  render() {
    return (
      <div id="app">
        <Toolbar />
        <NoteContainer />
      </div>
    );
  }
}

export default App;

The template essentially only contains the <Toolbar /> and <NoteContainer />custom component tags, which are imported above (note the self closing tags, which is the recommended style for components without any content). Let’s take a look at one of the sub-components, src/components/Toolbar.js:

import React, { Component } from "react";

class Toolbar extends Component {
  render() {
    return (
      <div className="toolbar">
        <button className="toolbar-button">New</button>
        <button className="toolbar-button">Delete</button>
        <input className="toolbar-search" type="text" placeholder="Search..." />
      </div>
    );
  }
}

export default Toolbar;

As you can see, it’s the same as before — you create a new class which extends the React Component class, and you write a render function which defines the JSX template.

So breaking things into components is a pretty straightforward task. The harder part comes when dealing with data and events. If you want to see what the rest of the components look like right now (they pretty much follow the same pattern), you can check them out in full detail here.

Display note titles from an array of notes #

Now that things are broken into components, we have to make some choices when it comes to storing and passing data. For the array of notes, it makes sense for the main <App> component to keep track of the notes and pass it down to its children. This would make the code in src/App.js look like:

import React, { Component } from "react";
import Toolbar from "./components/Toolbar";
import NoteContainer from "./components/NoteContainer";
import "./App.css";

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      notes: [
        { id: 1, body: "This is a first test", timestamp: Date.now() },
        { id: 2, body: "This is a second test", timestamp: Date.now() },
        { id: 3, body: "This is a third test", timestamp: Date.now() },
      ],
    };
  }

  render() {
    return (
      <div id="app">
        <Toolbar />
        <NoteContainer notes={this.state.notes} />
      </div>
    );
  }
}

export default App;

Here we have to make a custom constructor function for the class, which first runs the Component constructor with super(props);, then defines the custom state for the instance (which is equivalent to Vue.js’ data option). Once the state is stored upon initialization, we can pass it to the <NoteContainer> component with the line:

        <NoteContainer notes={this.state.notes} />

In JSX, you can write any JavaScript you want in single curly brackets (as opposed to double curly brackets in Vue.js). Here we’re taking the notes initialized in the component’s state and binding it to the child <NoteContainer> component. The <NoteContainer> component doesn’t directly use the notes data — instead it passes it down to the next child component. The code in src/components/NoteContainer.js looks like:

import React, { Component } from "react";
import NoteSelectors from "./NoteSelectors";
import NoteEditor from "./NoteEditor";

class NoteContainer extends Component {
  render() {
    return (
      <div className="note-container">
        <NoteSelectors notes={this.props.notes} />
        <NoteEditor />
      </div>
    );
  }
}

export default NoteContainer;

Note the change in terminology — this time notes is referred to using props, not state. It’s worth going over in more detail here:

The parent <App> component contains the note data, stored in its state. It has the ability to make changes to its own state, as well as pass any part of it down to its child components.
Any data a child component receives from its parent component is stored in props. In this case the child <NoteContainer> component receives the notes data in its props. A child component is not allowed to make changes to the props, since the data belongs to the parent component.

This means in the child <NoteContainer> component, the line

        <NoteSelectors notes={this.props.notes} />

is taking the this.props.notes data it received from its parent and passing it to the child <NoteSelectors> component as new props with a key of notes.

Finally, we get to <NoteSelectors> component, which does actually use the notes. This is what the code in src/components/NoteSelectors.js looks like:

import React, { Component } from "react";
import NoteSelector from "./NoteSelector";

class NoteSelectors extends Component {
  render() {
    const noteSelectors = this.props.notes.map((note) => (
      <NoteSelector 
        key={note.id}
        body={note.body}
        timestamp={note.timestamp}
      />
    ));

    return (
      <div className="note-selectors">
        {noteSelectors}
      </div>
    );
  }
}

export default NoteSelectors;

React doesn’t provide a special mechanism to loop through data — instead we’re using the built-in array map function to create an array of <NoteSelector> components, stored in the variable noteSelectors and rendered in the JSX. Finally, the <NoteSelector> component renders the data bound to its props, as you can see in src/components/NoteSelector.js:

import React, { Component } from "react";

class NoteSelector extends Component {
  render() {
    return (
      <div className="note-selector">
        <p className="note-selector-title">
          {this.props.body}
        </p>
        <p className="note-selector-timestamp">
          {this.props.timestamp}
        </p>
      </div>
    );
  }
}

export default NoteSelector;

For now, I’m using the note’s body and raw timestamp as placeholders, we’ll look at formatting them next.

Use functions to sort and format notes #

Unlike Vue.js, React doesn’t provide special mechanisms for things like computed properties and filters. Instead, you simply write functions as needed. This is what the src/components/NoteSelector.js code looks like with text formatting:

import React, { Component } from "react";

function formatTitle(body) {
  var maxLength = 20;
  if (body.length > maxLength) {
    return body.substring(0, maxLength - 3) + "...";
  } else if (body.length === 0) {
    return "New note";
  } else {
    return body;
  }
}

function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

class NoteSelector extends Component {
  render() {
    return (
      <div className="note-selector">
        <p className="note-selector-title">
          {formatTitle(this.props.body)}
        </p>
        <p className="note-selector-timestamp">
          {formatTimestamp(this.props.timestamp)}
        </p>
      </div>
    );
  }
}

export default NoteSelector;

Similarly, this is what the src/components/NoteSelectors.js code looks like to sort the child <NoteSelector> components by timestamps:

import React, { Component } from "react";
import NoteSelector from "./NoteSelector";

class NoteSelectors extends Component {
  render() {
    const sortedNotes = this.props.notes.slice().sort((a, b) => 
      b.timestamp - a.timestamp
    );
    const noteSelectors = sortedNotes.map((note) => (
      <NoteSelector
        key={note.id}
        body={note.body}
        timestamp={note.timestamp}
      />
    ));

    return (
      <div className="note-selectors">
        {noteSelectors}
      </div>
    );
  }
}

export default NoteSelectors;

This is one of the promises of React as a framework — it tries to keep its API to a minimum, relying on vanilla JavaScript whenever possible to implement features.

Select a note on title click #

Now let’s implement the ability to actually select notes. Clicking on a note title should both highlight the selected note on the left as well as display the contents in the editor on the right. First we’ll change the template in src/App.js as follows:

import React, { Component } from "react";
import Toolbar from "./components/Toolbar";
import NoteContainer from "./components/NoteContainer";
import "./App.css";

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      notes: [
        { id: 1, body: "This is a first test", timestamp: Date.now() },
        { id: 2, body: "This is a second test", timestamp: Date.now() },
        { id: 3, body: "This is a third test", timestamp: Date.now() },
      ],
      selectedNoteId: 1,
    };
  }

  handleClickNote = (id) => {
    this.setState({ selectedNoteId: id });
  };

  render() {
    return (
      <div id="app">
        <Toolbar />
        <NoteContainer
          notes={this.state.notes}
          selectedNoteId={this.state.selectedNoteId}
          onClickNote={this.handleClickNote}
        />
      </div>
    );
  }
}

export default App;

Let’s go over these changes one at a time:

We are adding selectedNoteId to the state to keep track of which note was selected. This is different than Vue.js, where we kept track of the note itself instead of just the id. This works better with the way React handles changes to the state, which we’ll see next.
We are defining a new handleClickNote function which takes an id and updates the state using React’s setState method. This is an important part of React — you must use this setState method to change any state, without it React won’t be able to properly update the DOM when state changes. (Note the weird way I’m defining the handleClickNote method in the class — this syntax helps properly bind the right this to the method in an efficient way. You can read more about it and other approaches here).
We are binding a new prop to the child <NoteContainer> component called selectedNoteId, which is set to the current component’s state’s selectedNoteId.
We are binding another new prop to the child <NoteContainer> component called onClickNote, which is set to the current component’s handleClickNote method we defined earlier. This is also different from Vue.js — there is no special notion of event emitters and listeners in React, you simply pass functions as part of the regular props which the child will call when appropriate.

Note the naming convention here — the actual event handler is named handleClickNote, the event handler as passed through in props is named onClickNote. This makes it easier to keep track of where event handlers are coming from, which we can see more clearly as we follow the props into the child components. The code in src/components/NoteContainer.js looks like:

import React, { Component } from "react";
import NoteSelectors from "./NoteSelectors";
import NoteEditor from "./NoteEditor";

class NoteContainer extends Component {
  render() {
    return (
      <div className="note-container">
        <NoteSelectors
          notes={this.props.notes}
          selectedNoteId={this.props.selectedNoteId}
          onClickNote={this.props.onClickNote}
        />
        <NoteEditor />
      </div>
    );
  }
}

export default NoteContainer;

Right now this component is only passing the props further into the <NoteSelectors> component. The code in src/components/NoteSelectors.js looks like:

import React, { Component } from "react";
import NoteSelector from "./NoteSelector";

class NoteSelectors extends Component {
  render() {
    const sortedNotes = this.props.notes.slice().sort((a, b) => b.timestamp - a.timestamp);
    const noteSelectors = sortedNotes.map((note) => (
      <NoteSelector
        key={note.id}
        body={note.body}
        timestamp={note.timestamp}
        id={note.id}
        selectedNoteId={this.props.selectedNoteId}
        onClickNote={this.props.onClickNote}
      />
    ));

    return <div className="note-selectors">{noteSelectors}</div>;
  }
}

export default NoteSelectors;

Again, this component is only passing the props further into the <NoteSelector> component. Note that it’s also adding one more prop for the note id, which will be useful in a moment. Finally, we’ll see how the props get used in src/components/NoteSelector.js:

import React, { Component } from "react";

function formatTitle(body) {
  var maxLength = 20;
  if (body.length > maxLength) {
    return body.substring(0, maxLength - 3) + "...";
  } else if (body.length === 0) {
    return "New note";
  } else {
    return body;
  }
}

function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

class NoteSelector extends Component {
  handleClickNote = () => {
    this.props.onClickNote(this.props.id);
  };

  render() {
    return (
      <div
        className={"note-selector " + (this.props.id === this.props.selectedNoteId ? "active" : "")}
        onClick={this.handleClickNote}
      >
        <p className="note-selector-title">
          {formatTitle(this.props.body)}
        </p>
        <p className="note-selector-timestamp">
          {formatTimestamp(this.props.timestamp)}
        </p>
      </div>
    );
  }
}

export default NoteSelector;

There are three essential things happening here:

The code onClick={this.handleClickNote} is capturing the DOM’s click handler and binding it to the current component’s handleClickNote method.
The handleClickNote method is defined to simply call the function onClickNote that was passed in from the props. Recall that this was defined in the <App> component to update the state of the selectedNoteId. Once the state is updated, React will automatically re-render all the children components.
The code className={"note-selector " + (this.props.id === this.props.selectedNoteId ? 'active' : '')} is using a JavaScript ternary operator to conditionally add the .active class to the div if the note is the selected note. Again, there isn’t any special syntax like Vue.js’ v-bind to apply this class name, you’re just using built in JavaScript tools.

This is React’s way of managing components (props down, events up), which helps keep the architecture of the code clean and avoids jQuery spaghetti that we saw a bit of earlier. It’s a bit different than Vue.js’ component model — in Vue.js, each component can only pass emit and listen to events from its direct child and direct parent. In React, you don’t emit events, instead you pass functions (which can belong to any component) in props, which means the function can be called by a child, grandchild, etc. In this case the <NoteSelector> component is essentially the great-great-grandchild of the <App> component, but it is able to call the onClickNote prop which is directly connected to the <App> component. In Vue.js you would have to bubble up the event one component at a time.

Edit the selected note on editor input #

At this point we can select a note and it highlights accordingly, but the content of the selected note aren’t showing up in the <NoteEditor> component. We also need to be able to update the selected note as the user enters text in the editor. Here’s how the code would change in src/App.js:

import React, { Component } from 'react';
import Toolbar from './components/Toolbar'
import NoteContainer from './components/NoteContainer'
import './App.css';

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      notes: [
        {id: 1, body: "This is a first test", timestamp: Date.now()},
        {id: 2, body: "This is a second test", timestamp: Date.now()},
        {id: 3, body: "This is a third test", timestamp: Date.now()}
      ],
      selectedNoteId: 1
    }
  }

  handleClickNote = (id) => {
    this.setState({selectedNoteId: id});
  }

  handleNoteEditorChange = (text) => {
    const newNotes = this.state.notes.map((note) => {
      if (note.id === this.state.selectedNoteId) {
        return {
          id: note.id,
          body: text,
          timestamp: Date.now()
        };
      } else {
        return note;
      }
    });
    this.setState({notes: newNotes});
  }

  render() {
    return (
      <div id="app">
        <Toolbar />
        <NoteContainer
          notes={this.state.notes}
          selectedNoteId={this.state.selectedNoteId}
          onClickNote={this.handleClickNote}
          onNoteEditorChange={this.handleNoteEditorChange}
        />
      </div>      
    );
  }
}

export default App;

The handleNoteEditorChange is a method that updates the selected note’s body with the given text. The thing that makes it tricky is that React requires you to not directly mutate the state object; instead, you should create a new copy of the part of the state that’s changing and update it using the setState function. Here we’re using the built-in array map function to create a new copy of the notes, where each note remains unchanged except for the current selected note, which gets recreated with the new body and timestamp.

In the render function, we’re passing the handleNoteEditorChange method the <NoteContainer> component as a prop named onNoteEditorChange. To use the method, the code in src/components/NoteContainer.js would change as follows:

import React, { Component } from 'react';
import NoteSelectors from './NoteSelectors';
import NoteEditor from './NoteEditor';

class NoteContainer extends Component {
  render() {
    const selectedNote = this.props.notes.find(note =>
      note.id === this.props.selectedNoteId
    );

    return (
      <div className="note-container">
        <NoteSelectors
          notes={this.props.notes}
          selectedNoteId={this.props.selectedNoteId}
          onClickNote={this.props.onClickNote}
        />
        <NoteEditor
          selectedNote={selectedNote}
          onNoteEditorChange={this.props.onNoteEditorChange}
        />
      </div>
    );
  }
}

export default NoteContainer;

First we’re creating a variable called selectedNote, which we have to find from the given notes and selectedNoteId in props. Then we can bind the selectedNote to the <NoteEditor> props, along with the given onNoteEditorChange function. (Note that we have to find the selectedNote here as opposed to inside the <NoteEditor> component, because this component has access to both the notes and the selectedNoteId, whereas the <NoteEditor> doesn’t have access to the notes data).

Finally, we can see how the <NoteEditor> component will use the props in src/components/NoteEditor.js:

import React, { Component } from 'react';

function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

class NoteEditor extends Component {
  handleChange = (event) => {
    this.props.onNoteEditorChange(event.target.value);
  }

  render() {
    return (
      <div className="note-editor">
        <p className="note-editor-info">
          {formatTimestamp(this.props.selectedNote.timestamp)}
        </p>
        <textarea className="note-editor-input"
          value={this.props.selectedNote.body}
          onChange={this.handleChange}
        />
      </div>
    );
  }
}

export default NoteEditor;

Let’s go over what’s going on here one at a time:

We need to define a formatTimestamp function to format the editor’s timestamp. It’s the same as the function defined in the <NoteSelector> component, so we’ll need to find a way to DRY it up (in the next section).
The handleChange method is going to be triggered from a DOM input event, and it will simply call up the onNoteEditorChange method that was given in the props (first extracting out the user’s text from the event).
The render method displays the selectedNote’s timestamp and body, as well as bind’s the DOM’s <textarea> input event to run the handleChange method defined above.

Again, the flow would be the user enters text in the <NoteEditor> component, which triggers its handleChange method, which runs the onNoteEditorChange method from its props, which all the way in the <App> component updates the notes in its state object, causing all the children to be re-rendered.

Refactor helper functions to separate file #

Right now we have an issue where we defined the same formatTimestamp function in two different components. Again, React doesn’t provide a React-specific way to handle this issue — you can use regular JavaScript to DRY up the code. In this case we’re going to write the helpers in a separate file, then import them as needed (which is not traditional JavaScript per se, but we’ve been using imports repeatedly throughout the code, so it shouldn’t be that hard). Here’s the new helper file in src/helpers.js:

export function formatTitle(body) {
  var maxLength = 20;
  if (body.length > maxLength) {
    return body.substring(0, maxLength - 3) + "...";
  } else if (body.length === 0) {
    return "New note";
  } else {
    return body;
  }
}

export function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

And here’s how you would import the functions in src/components/NoteSelector.js:

import React, { Component } from 'react';
import {formatTitle, formatTimestamp} from '../helpers';

class NoteSelector extends Component {
  handleClickNote = () => {
    this.props.onClickNote(this.props.id);
  }

  render() {
    return (
      <div
        className={"note-selector " + (this.props.id === this.props.selectedNoteId ? 'active' : '')}
        onClick={this.handleClickNote}
      >
        <p className="note-selector-title">
          {formatTitle(this.props.body)}
        </p>
        <p className="note-selector-timestamp">
          {formatTimestamp(this.props.timestamp)}
        </p>
      </div>
    );
  }
}

export default NoteSelector;

You would do the same in src/components/NoteEditor.js to import the formatTimestamp function. This is an easy enough structure to put any helper functions in an organized spot going forward!

Create a new note with a button #

Now let’s implement the ability to create a new note. Clicking on the “New” button should create a new note (new id, no body, current timestamp). The new note should become the currently selected note and appear at the top of the list of note selectors. Let’s start with the child <Toolbar> component in src/components/Toolbar.js:

import React, { Component } from "react";

class Toolbar extends Component {
  render() {
    return (
      <div className="toolbar">
        <button className="toolbar-button" onClick={this.props.onNewNote}>
          New
        </button>
        <button className="toolbar-button">
          Delete
        </button>
        <input className="toolbar-search" type="text" placeholder="Search..." />
      </div>
    );
  }
}

export default Toolbar;

Here the code onClick={this.props.onNewNote} is capturing the native DOM <button> click event with onClick, which will run the onNewNote method from the props when the event fires. This means the parent <App> component must send down the onNewNote method in props appropriately, which would change the code in src/App.js as follows:

import React, { Component } from "react";
import Toolbar from "./components/Toolbar";
import NoteContainer from "./components/NoteContainer";
import "./App.css";

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      notes: [
        { id: 1, body: "This is a first test", timestamp: Date.now() },
        { id: 2, body: "This is a second test", timestamp: Date.now() },
        { id: 3, body: "This is a third test", timestamp: Date.now() },
      ],
      selectedNoteId: 1,
    };
  }

  handleClickNote = (id) => {
    this.setState({ selectedNoteId: id });
  };

  handleNoteEditorChange = (text) => {
    const newNotes = this.state.notes.map((note) => {
      if (note.id === this.state.selectedNoteId) {
        return {
          id: note.id,
          body: text,
          timestamp: Date.now(),
        };
      } else {
        return note;
      }
    });
    this.setState({ notes: newNotes });
  };

  handleNewNote = () => {
    const newNote = {
      id: Date.now(),
      body: "",
      timestamp: Date.now(),
    };
    this.setState({
      notes: this.state.notes.concat([newNote]),
      selectedNoteId: newNote.id,
    });
  };

  render() {
    return (
      <div id="app">
        <Toolbar
          onNewNote={this.handleNewNote}
        />
        <NoteContainer
          notes={this.state.notes}
          selectedNoteId={this.state.selectedNoteId}
          onClickNote={this.handleClickNote}
          onNoteEditorChange={this.handleNoteEditorChange}
        />
      </div>
    );
  }
}

export default App;

Here the <Toolbar> component is sending the handleNewNote method as a prop called onNewNote (which we defined earlier to run whenever the “New” button in the toolbar is clicked). The handleNewNote method has to update the state with a new note as well as a new selected note id, which again requires care to avoid direct mutation. Here we’re creating a new copy of the notes array by using the array concat method. Once the state is updated with setState, React will automatically re-render the child components as needed.

Delete the selected note with a button #

Wiring up this feature starts off pretty similar to the new note feature. Let’s again start with the child <Toolbar> component in src/components/Toolbar.js:

import React, { Component } from "react";

class Toolbar extends Component {
  render() {
    return (
      <div className="toolbar">
        <button className="toolbar-button" onClick={this.props.onNewNote}>
          New
        </button>
        <button className="toolbar-button" onClick={this.props.onDeleteNote}>
          Delete
        </button>
        <input className="toolbar-search" type="text" placeholder="Search..." />
      </div>
    );
  }
}

export default Toolbar;

Here the code onClick={this.props.onDeleteNote} is capturing the native DOM <button> click event and running the onDeleteNote method from the props. This means the parent <App> component must send down the props appropriately, which would change the code in src/App.js as follows:

import React, { Component } from "react";
import Toolbar from "./components/Toolbar";
import NoteContainer from "./components/NoteContainer";
import { transformNotes } from "./helpers";
import "./App.css";

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      notes: [
        { id: 1, body: "This is a first test", timestamp: Date.now() },
        { id: 2, body: "This is a second test", timestamp: Date.now() },
        { id: 3, body: "This is a third test", timestamp: Date.now() },
      ],
      selectedNoteId: 1,
    };
  }

  handleClickNote = (id) => {
    this.setState({ selectedNoteId: id });
  };

  handleNoteEditorChange = (text) => {
    const newNotes = this.state.notes.map((note) => {
      if (note.id === this.state.selectedNoteId) {
        return {
          id: note.id,
          body: text,
          timestamp: Date.now(),
        };
      } else {
        return note;
      }
    });
    this.setState({ notes: newNotes });
  };

  handleNewNote = () => {
    const newNote = {
      id: Date.now(),
      body: "",
      timestamp: Date.now(),
    };
    this.setState({
      notes: this.state.notes.concat([newNote]),
      selectedNoteId: newNote.id,
    });
  };

  handleDeleteNote = () => {
    const newNotes = this.state.notes.filter((note) => note.id !== this.state.selectedNoteId);
    const transformedNotes = transformNotes(newNotes);
    const newSelectedNoteId = transformedNotes.length > 0 ? transformedNotes[0].id : null;
    this.setState({
      notes: newNotes,
      selectedNoteId: newSelectedNoteId,
    });
  };

  render() {
    return (
      <div id="app">
        <Toolbar
          onNewNote={this.handleNewNote}
          onDeleteNote={this.handleDeleteNote}
        />
        <NoteContainer
          notes={this.state.notes}
          selectedNoteId={this.state.selectedNoteId}
          onClickNote={this.handleClickNote}
          onNoteEditorChange={this.handleNoteEditorChange}
        />
      </div>
    );
  }
}

export default App;

Here the <Toolbar> component is sending the handleDeleteNote method as a prop called onDeleteNote, which we defined earlier to run whenever the “Delete” button in the toolbar is clicked. The handleDeleteNote method has to update the state with a deleted note as well as a new selected note id, which again requires care to avoid mutation. Here we’re creating a new copy of the notes array by using the array filter method. Once the state is updated with setState, React will automatically re-render the child components as needed.

However, there’s a problem — the handleDeleteNote method also needs to select a new note in place of the one that’s deleted. The problem is that selecting a new note means we need to know the top of the list of the transformed (sorted) notes, which we defined in the child <NoteSelectors>component. That seemed like the right decision at the time, but now we’ll need to refactor that method to be in the src/helpers.js file as follows:

export function formatTitle(body) {
  var maxLength = 20;
  if (body.length > maxLength) {
    return body.substring(0, maxLength - 3) + "...";
  } else if (body.length === 0) {
    return "New note";
  } else {
    return body;
  }
}

export function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

export function transformNotes(notes) {
  return notes.slice().sort((a, b) => 
    b.timestamp - a.timestamp
  );
}

The <NoteSelectors> component in src/components/NoteSelectors.js can now import the transformNotes helper function as well:

import React, { Component } from "react";
import NoteSelector from "./NoteSelector";
import { transformNotes } from "../helpers";

class NoteSelectors extends Component {
  render() {
    const noteSelectors = transformNotes(this.props.notes).map((note) => (
      <NoteSelector
        key={note.id}
        body={note.body}
        timestamp={note.timestamp}
        id={note.id}
        selectedNoteId={this.props.selectedNoteId}
        onClickNote={this.props.onClickNote}
      />
    ));

    return <div className="note-selectors">{noteSelectors}</div>;
  }
}

export default NoteSelectors;

The last detail is to change the <NoteEditor> component to only render if there is a selectedNote, since it’s now possible to delete all the notes. The template in src/components/NoteEditor.js would change as follows:

import React, { Component } from 'react';
import {formatTimestamp} from '../helpers';

class NoteEditor extends Component {
  handleChange = (event) => {
    this.props.onNoteEditorChange(event.target.value);
  }

  render() {
    if (this.props.selectedNote) {
      return (
        <div className="note-editor">
          <p className="note-editor-info">
            {formatTimestamp(this.props.selectedNote.timestamp)}
          </p>
          <textarea className="note-editor-input"
            value={this.props.selectedNote.body}
            onChange={this.handleChange}
          />
        </div>
      );
    } else {
      return null;
    }
  }
}

export default NoteEditor;

Again, no special React syntax, just a regular JavaScript if condition on the render method (returning null to skip rendering the component).

Filter notes on search input #

The final feature is to be able to search notes immediately as you type in the search input. Let’s again start with the child <Toolbar> component in src/components/Toolbar.js:

import React, { Component } from 'react';

class Toolbar extends Component {
  handleInput = (event) => {
    this.props.onSearchNote(event.target.value);
  }

  render() {
    return (
      <div className="toolbar">
        <button className="toolbar-button" onClick={this.props.onNewNote}>
          New
        </button>
        <button className="toolbar-button" onClick={this.props.onDeleteNote}>
          Delete
        </button>
        <input className="toolbar-search" type="text" placeholder="Search..." 
          onInput={this.handleInput}
        />
      </div>
    );
  }
}

export default Toolbar;

Here the code onInput={this.handleInput} is capturing the native DOM <input> input event and running the handleInput method. The handleInput method simply calls up the onSearchNote method from the props, giving it the value of the user’s text. This means the parent <App> component must send down the props appropriately, which would change the code in src/App.js as follows:

import React, { Component } from 'react';
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';
import {transformNotes} from './helpers';
import './App.css';

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      notes: [
        {id: 1, body: "This is a first test", timestamp: Date.now()},
        {id: 2, body: "This is a second test", timestamp: Date.now()},
        {id: 3, body: "This is a third test", timestamp: Date.now()}
      ],
      selectedNoteId: 1,
      searchText: ""
    }
  }

  handleClickNote = (id) => {
    this.setState({selectedNoteId: id});
  }

  handleNoteEditorChange = (text) => {
    const newNotes = this.state.notes.map((note) => {
      if (note.id === this.state.selectedNoteId) {
        return {
          id: note.id,
          body: text,
          timestamp: Date.now()
        };
      } else {
        return note;
      }
    });
    this.setState({notes: newNotes});
  }

  handleNewNote = () => {
    const newNote = {
      id: Date.now(),
      body: "",
      timestamp: Date.now()
    }
    this.setState({
      notes: this.state.notes.concat([newNote]),
      selectedNoteId: newNote.id
    })
  }

  handleDeleteNote = () => {
    const newNotes = this.state.notes.filter(note =>
      note.id !== this.state.selectedNoteId
    );
    const transformedNotes = transformNotes(newNotes, this.state.searchText);
    const newSelectedNoteId = transformedNotes.length > 0 ? transformedNotes[0].id : null
    this.setState({
      notes: newNotes,
      selectedNoteId: newSelectedNoteId
    });
  }

  handleSearchNote = (newSearchText) => {
    const transformedNotes = transformNotes(this.state.notes, newSearchText);
    let newSelectedNoteId = null;
    if (transformedNotes.length > 0) {
      const selectedNote = transformedNotes.find(note => note.id === this.state.selectedNoteId);
      if (selectedNote) {
        newSelectedNoteId = selectedNote.id;
      } else {
        newSelectedNoteId = transformedNotes[0].id;
      }
    }
    this.setState({
      searchText: newSearchText,
      selectedNoteId: newSelectedNoteId
    })
  }

  render() {
    return (
      <div id="app">
        <Toolbar
          onNewNote={this.handleNewNote}
          onDeleteNote={this.handleDeleteNote}
          onSearchNote={this.handleSearchNote}
        />
        <NoteContainer
          notes={this.state.notes}
          selectedNoteId={this.state.selectedNoteId}
          searchText={this.state.searchText}
          onClickNote={this.handleClickNote}
          onNoteEditorChange={this.handleNoteEditorChange}
        />
      </div>      
    );
  }
}

export default App;

Let’s go through these changes one at a time:

We are keeping track of a new piece of state, searchText — the search text the user enters. This will be used to filter the list of notes.
The transformNotes helper method now takes in two arguments — the array of notes as well as the searchText. The transformation will now consist of both filtering and sorting (see below).
The handleSearchNote method updates the searchText data to the input argument, which automatically triggers React to re-render all the child components. It also has to update the selectedNoteId to be the first of the transformedNotes if possible.
The <Toolbar> component now takes in a new prop onSearchNote={this.handleSearchNote} so it can call up the handleSearchNote function whenever the search input text changes.
The <NoteContainer> component now takes in a new prop searchText={this.state.searchText}, which the children components will need to properly filter the notes as well.

The transformNotes helper function in src/helpers.js now looks like:

export function formatTitle(body) {
  var maxLength = 20;
  if (body.length > maxLength) {
    return body.substring(0, maxLength - 3) + "...";
  } else if (body.length === 0) {
    return "New note";
  } else {
    return body;
  }
}

export function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

export function transformNotes(notes, searchText) {
  return notes
    .filter((note) => note.body.toLowerCase().indexOf(searchText.toLowerCase()) !== -1)
    .sort((a, b) => b.timestamp - a.timestamp);
}

The <NoteContainer> component changes slightly to continue to pass along the searchText prop, which you can see in src/components/NoteContainer.js:

import React, { Component } from 'react';
import NoteSelectors from './NoteSelectors';
import NoteEditor from './NoteEditor';

class NoteContainer extends Component {
  render() {
    const selectedNote = this.props.notes.find(note => note.id === this.props.selectedNoteId);

    return (
      <div className="note-container">
        <NoteSelectors
          notes={this.props.notes}
          selectedNoteId={this.props.selectedNoteId}
          searchText={this.props.searchText}
          onClickNote={this.props.onClickNote}
        />
        <NoteEditor
          selectedNote={selectedNote}
          onNoteEditorChange={this.props.onNoteEditorChange}
        />
      </div>
    );
  }
}

export default NoteContainer;

Finally, the <NoteSelectors> component uses the searchText prop to filter the notes using the transformNotes helper function, which you can see in src/components/NoteSelectors.js:

import React, { Component } from 'react';
import NoteSelector from './NoteSelector';
import {transformNotes} from '../helpers';

class NoteSelectors extends Component {
  render() {
    const transformedNotes = transformNotes(this.props.notes, this.props.searchText);
    const noteSelectors = transformedNotes.map(note =>
      <NoteSelector
        key={note.id}
        body={note.body}
        timestamp={note.timestamp}
        id={note.id}
        selectedNoteId={this.props.selectedNoteId}
        onClickNote={this.props.onClickNote}
      />
    );

    return (
      <div className="note-selectors">
        {noteSelectors}
      </div>
    );
  }
}

export default NoteSelectors;

You can see the final version of the code in all its glory at this GitHub repository.

Conclusion #

In many ways, working with React components is quite similar to working with Vue.js components (Vue.js was definitely heavily inspired by both Angular 1 and React). There’s definitely something nice about React providing a small API surface, without a lot of specialized approaches — it forces you to get better at your raw JavaScript skills. You need a loop to generate HTML from a list? Use the JavaScript array map method. You need conditional rendering? Use a regular JavaScript if condition. You want helper functions? Make functions in a file and import them. Pretty cool stuff.

However, at the same time React leans so heavily on new JavaScript features that it can definitely feel daunting to learn up front. And despite not having to learn React-specific syntax, you do need to accustom yourself to quite a bit of React specific idioms (naming event handlers, properly binding this without triggering extra re-rendering, avoiding mutation, etc.). Also, React can sometimes be unopinionated to the point where it creates confusion — there’s many different ways to define a component (the class keyword, pure functions, etc.), and quite a bit of debate on what’s the “best” way to do it.

React at the time of this writing is a pretty interesting blend of (what at least looks like) object oriented approaches and functional approaches. It’s definitely interesting to contrast with Vue.js, which encourages mutation of data as a key way of providing reactivity. React prefers an immutable approach to state, which can be at times tricky to achieve with JavaScript as a language. In the next part of this series, we’ll be looking at Elm, which is an actual pure functional language with immutable data structures that compiles to JavaScript. Stay tuned!

Comparing Frontend Approaches Part 4: Vue.js with Components

2017-09-22T00:00:00Z

In this part we will be implementing the web based clone of the Mac Notes app using Vue.js, but this time with components. As mentioned last time, Vue.js labels itself as “the progressive JavaScript framework”, which means you learn and implement the advanced functionality only as needed. One such feature is using components, which are a great way to organize code once an app becomes sufficiently complex.

Using components to isolate behavior and increase reusability isn’t a new programming concept, but it is new for frontend programming. Native web components for the browser were first announced in 2011 but never fully landed (as of 2017). JavaScript frameworks picked up the slack, providing an immediate way to build complex apps with a component architecture. However, there are significant tradeoffs to using components — setup, build tools, passing data all becomes harder compared to prior approaches. Let’s see what it looks like in practice to evaluate the tradeoffs ourselves!

Note — the focus of this part is largely on the Vue.js component model itself. If you want a broader look at Vue.js features such as basic directives and options, I would recommend starting with the previous part of this series where I build the same app using Vue.js without components.

Installation #

The installation process for Vue.js with components is pretty different than installing jQuery and Vue.js without components. This is because using components naturally lends itself to writing code in separate files, which means we’ll need a build process to bundle our JavaScript. This would normally be a lot of work, but fortunately Vue.js offers vue-cli, a command line tool to scaffold out projects. If you don’t already have it installed, you can install vue-cli with the command:

$ npm install -g @vue/cli

Once you have it installed, you can navigate to the directory you want to create your project in and run:

$ vue create my-project

You should replace my-project with whatever name you want your particular project to have. This will prompt you with setup options (you can choose the default setup). In the end you will end up a new folder called my-project with the following project structure:

.├── node_modules/
 │   └── ...
 ├── public/
 │   ├── favicon.ico
 │   └── index.html
 ├── src/
 │   ├── assets/
 │   │   └── logo.png
 │   ├── components/
 │   │   └── HelloWorld.vue
 │   ├── App.vue
 │   └── main.js
 ├── .gitignore
 ├── babel.config.js
 ├── package-lock.json
 ├── package.json
 └── README.md

Whew, that’s a lot of files! Fortunately you don’t need to worry about most of them for right now (you can read more about the project structure from the official guide), pretty much all of our work will be in the src directory. At this point you already have a hello world app built for you, which you can see by entering the following commands:

$ cd my-project$ npm run serve

The last command will run a dev server and automatically open up your browser to localhost:8080, where you should see something like this:

This is pretty cool, and what’s cooler is that you have a hot-reloading environment already set up for you. What that means is that if you make changes to your code, the browser at localhost:8080 will automatically refresh. The place to start making changes is src/App.vue, which right now looks like this:

<template>
  <div id="app">
    <img alt="Vue logo" src="./assets/logo.png">
    <HelloWorld msg="Welcome to Your Vue.js App"/>
  </div>
</template>

<script>
import HelloWorld from './components/HelloWorld.vue'

export default {
  name: 'app',
  components: {
    HelloWorld
  }
}
</script>

<style>
#app {
  font-family: 'Avenir', Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
</style>

This is a Vue.js component — a single .vue file which contains the HTML template in a <template> tag, the JavaScript in a <script> tag, and the CSS in a <style> tag. Which means we can take the HTML and CSS from our notes app template and use it instead, which would make the src/App.vue look like this:

<template>
  <div id="app">
    <div class="toolbar">
      <button class="toolbar-button">New</button>
      <button class="toolbar-button">Delete</button>
      <input class="toolbar-search" type="text" placeholder="Search...">
    </div>
    <div class="note-container">
      <div class="note-selectors">
        <div class="note-selector active">
          <p class="note-selector-title">First note...</p>
          <p class="note-selector-timestamp">Timestamp here...</p>
        </div>
        <div class="note-selector">
          <p class="note-selector-title">Second note...</p>
          <p class="note-selector-timestamp">Timestamp here...</p>
        </div>
        <div class="note-selector">
          <p class="note-selector-title">Third note...</p>
          <p class="note-selector-timestamp">Timestamp here...</p>
        </div>
      </div>
      <div class="note-editor">
        <p class="note-editor-info">Timestamp here...</p>
        <textarea class="note-editor-input">
          First note...

          Note text here...
        </textarea>
      </div>
    </div>
  </div>
</template>

<script>
export default {
  name: 'app'
};
</script>

<style>
/* RESET */
* {
  margin: 0;
  padding: 0;
  border: 0;
  outline: none;
  box-sizing: border-box;
}

/* LAYOUT */
#app {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
}
.toolbar {
  padding: 0.5em;
}
.toolbar-button, .toolbar-search {
  padding: inherit;
  border-radius: 0.3em;
}
.toolbar-search {
  float: right;
}
.note-container {
  display: flex;
  flex: 1;
}
.note-selectors {
  flex: 0 0 13em;
}
.note-selector {
  padding: 1em;
}
.note-selector p {
  margin: 0;
}
.note-editor {
  display: flex;
  flex: 1;
  flex-direction: column;
}
.note-editor-info {
  padding: 0.5em;
  text-align: center;
}
.note-editor-input {
  display: flex;
  flex: 1;
  width: 100%;
  padding: 0 2em 0 2em;
}

/* COLORS */
* {
  color: #454545;
  background-color: #FAFAF8;
}
.toolbar {
  background-color: #DCDADC;
}
.toolbar-button {
  background-color: #FFFFFF;
}
.toolbar-button:active {
  background-color: #AAAAAA;
}
.note-selectors {
  border-right: 1px solid #DCDADC;
}
.note-selector {
  border-bottom: 1px solid #DCDADC;
}
.note-selector.active {
  background-color: #FCE18D;
}
.note-selector-title {
  background-color: inherit;
}
.note-selector-timestamp {
  color: #626262;
  background-color: inherit;
}
.note-editor-info {
  color: #DCDADC;
}

/* TYPOGRAPHY */
body {
  font-family: sans-serif;
}
.note-selector-title {
  font-weight: bold;
}
.note-selector-timestamp {
  font-size: 0.7em;
}
.note-editor, .note-editor-input {
  font-size: 0.9em;
}
</style>

If you look at your browser, you should see our familiar notes app starting point!

Refactor into components #

The next step is to break this src/App.vue file into components. Here is a diagram of the different components we can break this app into:

<app>
├── <Toolbar>
└── <NoteContainer>
    ├── <NoteSelectors>
    │   └── <NoteSelector>
    │   └── <NoteSelector>
    │   └── <NoteSelector>
    └── <NoteEditor>

<template>
  <div id="app">
    <Toolbar/>
    <NoteContainer/>
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

<style>
/* RESET */
* {
  margin: 0;
  padding: 0;
  border: 0;
  outline: none;
  box-sizing: border-box;
}

/* LAYOUT */
#app {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
}

/* COLORS */
* {
  color: #454545;
  background-color: #FAFAF8;
}

/* TYPOGRAPHY */
body {
  font-family: sans-serif;
}
</style>

The template essentially only contains the <Toolbar/> and <NoteContainer/> custom component tags, which are defined in the JavaScript. In the script tag, we import the components and register them with the Vue.js app. Finally, the style tag has changed only to include the CSS at the top level — any component specific styles will be defined within the components themselves. Let’s take a look at one of the sub-components, src/components/Toolbar.vue:

<template>
  <div class="toolbar">
    <button class="toolbar-button">New</button>
    <button class="toolbar-button">Delete</button>
    <input class="toolbar-search" type="text" placeholder="Search...">
  </div>
</template>

<script>
export default {
  name: 'toolbar'
};
</script>

<style>
/* LAYOUT */
.toolbar {
  padding: 0.5em;
}
.toolbar-button, .toolbar-search {
  padding: inherit;
  border-radius: 0.3em;
}
.toolbar-search {
  float: right;
}

/* COLORS */
.toolbar {
  background-color: #DCDADC;
}
.toolbar-button {
  background-color: #FFFFFF;
}
.toolbar-button:active {
  background-color: #AAAAAA;
}
</style>

As you can see, it’s the same as before — the template contains the HTML for just the toolbar, the script contains the JavaScript (which isn’t doing much right now), and the style contains the CSS for just the toolbar.

Display note titles from an array of notes #

<template>
  <div id="app">
    <Toolbar/>
    <NoteContainer v-bind:notes="notes"/>
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    return {
    notes: [
        {id: 1, body: "This is a first test", timestamp: Date.now()},
        {id: 2, body: "This is a second test", timestamp: Date.now()},
        {id: 3, body: "This is a third test", timestamp: Date.now()}
      ]
    };
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

(Note — I’m not showing any <style> tags anymore because they won’t change from here on out). In the <script> tag, we define the notes array in the data option as we did in the previous Vue.js app. In the <template> tag, we pass the notes data to the <NoteContainer> component with the line:

<NoteContainer v-bind:notes="notes"/>

Here we’re binding a custom notes attribute to the component, which contains the array of notes defined in the data option. However, the <NoteContainer> component doesn’t directly display the notes, so it has to pass it down using a similar technique. Here’s what the src/components/NoteContainer.vue template and script look like:

<template>
  <div class="note-container">
    <NoteSelectors v-bind:notes="notes"/>
    <NoteEditor/>
  </div>
</template>

<script>
import NoteSelectors from './NoteSelectors';
import NoteEditor from './NoteEditor';

export default {
  name: 'note-container',
  props: ['notes'],
  components: {
    NoteSelectors,
    NoteEditor
  }
};
</script>

In the <script> tag, we’re defining the notes as an element in the array of props. This is an important distinction — the <NoteContainer> component doesn’t have notes defined in the data option, because it doesn’t define its own notes; rather, it’s getting the notes data from its parent. Data received from a parent is stored in the props option.

Again, the <NoteContainer> component doesn’t deal with the notes directly, so it has to pass it down to the <NoteSelectors> component, which you see in the template line:

    <NoteSelectors v-bind:notes="notes"/>

Finally, we get to <NoteSelectors> component, which does actually use the notes. This is what the src/components/NoteSelectors.vue template and script look like:

<template>
  <div class="note-selectors">
      <NoteSelector
        v-for="note in notes"
        v-bind:note="note"
        v-bind:key="note.id"
      />
  </div>
</template>

<script>
import NoteSelector from './NoteSelector';

export default {
  name: 'note-selectors',
  props: ['notes'],
  components: {
    NoteSelector
  }
};
</script>

Now we can use the notes and loop over them with a v-for directive to create as many <NoteSelector> components as we need. We need to bind each note object to the component, as well as a unique key to help Vue.js keep track of each component. This is what the src/components/NoteSelector.vue template and script look like:

<template>
  <div class="note-selector">
    <p class="note-selector-title">{{ note.body }}</p>
    <p class="note-selector-timestamp">{{ note.timestamp }}</p>
  </div>
</template>

<script>
export default {
  name: 'note-selector',
  props: ['note']
};
</script>

In the <script> tag we register the note as a prop (the key is used internally by Vue.js), and the <template> tag looks like a straightforward Vue.js template. For now, I’m using the note’s body and raw timestamp as placeholders, we’ll look at formatting them in the next section.

Whew, that was a lot of work just to loop through an array of notes! There definitely is a price to pay for breaking things into components — maintaining strong boundaries means you must put in more effort to pass information across said boundaries. However, although the concept of passing down data as props from component to component seems foreign at first, it gets to be second nature, since the patterns are fairly straightforward and repeatable.

Use computed properties and filters to sort and format notes #

Right now the <NoteSelector> component needs formatting for the title and timestamp, which we can accomplish with Vue.js filters. This is what the src/components/NoteSelector.vue template and script look like with filters:

<template>
  <div class="note-selector">
    <p class="note-selector-title">
      {{ note.body | formatTitle }}
    </p>
    <p class="note-selector-timestamp">
      {{ note.timestamp | formatTimestamp }}
    </p>
  </div>
</template>

<script>
export default {
  name: 'note-selector',
  filters: {
    formatTitle: function(body) {
      var maxLength = 20;
      if (body.length > maxLength) {
        return body.substring(0, maxLength - 3) + '...';
      } else if (body.length === 0) {
        return "New note";
      } else {
        return body;
      }
    },
    formatTimestamp: function(timestamp) {
      return new Date(timestamp).toUTCString();
    }
  },
  props: ['note']
};
</script>

Also, the parent <NoteSelectors> component needs to sort the child <NoteSelector> components by timestamps. This is what the src/components/NoteSelectors.vue template and script look like:

<template>
  <div class="note-selectors">
      <NoteSelector
        v-for="note in transformedNotes"
        v-bind:note="note"
        v-bind:key="note.id"
      />
  </div>
</template>

<script>
import NoteSelector from './NoteSelector';

export default {
  name: 'note-selectors',
  props: ['notes'],
  computed: {
    transformedNotes: function() {
      return this.notes.slice().sort(function(a, b) {
        return b.timestamp - a.timestamp;
      });
    }
  },
  components: {
    NoteSelector
  }
};
</script>

This is pretty straightforward, and it begins to showcase the nice advantage of working with components — you can determine which component is responsible for which behavior and organize your code accordingly. Right now we have the <NoteSelector> component responsible for title and timestamp formatting, and the <NoteSelectors> parent component responsible for sorting. If there’s ever an issue, it makes it easier to locate and work on the appropriate code.

Select a note on title click #

Now let’s implement the ability to actually select notes. Clicking on a note title should both highlight the selected note on the left as well as display the contents in the editor on the right. First we’ll change the template in src/App.vue as follows:

<template>
  <div id="app">
    <Toolbar/>
      <NoteContainer
        v-bind:notes="notes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
      />
  </div>
</template>

Here we’re sending a new prop and event to the <NoteContainer> component. The names can be confusing, so it’s worth going over in detail.

The code v-bind:selectedNote is essentially creating a new prop called selectedNote which will be available in <NoteContainer>. It is being set equal to "selectedNote", which is referring to a variable that must be defined in the current <App> component’s data option.
The code v-on:selectNote is creating an event listener on the <NoteContainer> component. If the <NoteContainer> component ever emits an event with the name selectNote, it will run whatever code it is being set equal to, which in this case is "selectNote", a method that must be defined in the current <App> component’s methods option.

This means the script in src/App.vue should define selectedNote in the data and selectNote in the methods, as follows:

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    var initialNotes = [
      {id: 1, body: "This is a first test", timestamp: Date.now()},
      {id: 2, body: "This is a second test", timestamp: Date.now()},
      {id: 3, body: "This is a third test", timestamp: Date.now()}
    ];
    return {
      notes: initialNotes,
      selectedNote: initialNotes[0]
    };
  },
  methods: {
    selectNote: function(note) {
      this.selectedNote = note;
    }
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

So far so good. Now we have to make sure the child <NoteContainer> component will emit a selectNote event any time a note selector is clicked. This is what the src/components/NoteContainer.vue template and script look like:

<template>
  <div class="note-container">
      <NoteSelectors
        v-bind:notes="notes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
      />
      <NoteEditor
        v-bind:selectedNote="selectedNote"
      />
  </div>
</template>

<script>
import NoteSelectors from './NoteSelectors';
import NoteEditor from './NoteEditor';

export default {
  name: 'note-container',
  props: ['notes', 'selectedNote'],
  methods: {
    selectNote: function(note) {
      this.$emit('selectNote', note);
    }
  },
  components: {
    NoteSelectors,
    NoteEditor
  }
};
</script>

Similar to the <App> component, the <NoteContainer> component has to pass the selectedNote prop and the selectNote event to the child <NoteSelector> component. Note that if the <NoteSelector> component emits a selectNote event, it will run this function:

methods: {
  selectNote: function(note) {
    this.$emit('selectNote', note);
  }
},

This function emits a selectNote event from the <NoteContainer> component, which we set up an event listener in the parent to respond to. Also note that in the template, we’re sending the selectedNote prop to the <NoteEditor> component, which needs that info as well.

Now let’s take a look at the template and script in the <NoteSelectors> component in app/components/NoteSelectors.vue, which is what is actually process the click event:

<template>
  <div class="note-selectors">
      <NoteSelector
        v-for="note in transformedNotes"
        v-bind:note="note"
        v-bind:selectedNote="selectedNote"
        v-bind:key="note.id"
        v-on:click.native="selectNote(note)"
      />
  </div>
</template>

<script>
import NoteSelector from './NoteSelector';

export default {
  name: 'note-selectors',
  props: ['notes', 'selectedNote'],
  methods: {
    selectNote: function(note) {
      this.$emit('selectNote', note);
    }
  },
  computed: {
    transformedNotes: function() {
      return this.notes.slice().sort(function(a, b) {
        return b.timestamp - a.timestamp;
      });
    }
  },
  components: {
    NoteSelector
  }
};
</script>

The key line in the template is:

v-on:click.native="selectNote(note)"

This is binding the native DOM click event to a method called selectNote, which is defined in the component’s methods option:

methods: {
  selectNote: function(note) {
    this.$emit('selectNote', note);
  }
},

This starts the chain reaction — the user click’s on a <NoteSelector> component, triggering the parent <NoteSelectors> component’s selectNote method, which emits a 'selectNote' event, triggering the parent <NoteContainer> component’s selectNote method, which emits a 'selectNote' event, triggering the parent <App> component’s selectNote method, which changes the actual selectedNote data. Once the parent’s data changes, Vue.js automatically re-renders all the appropriate child components.

This style of programming (props down, events up, made popular by React) seems overly verbose at first, but it’s the key to keeping the architecture of the code clean. Without it, we would be running into jQuery spaghetti territory. The reason we can avoid complexity is because each component is forced to only know about what it needs to know — a child component doesn’t manipulate the parent’s data directly, it simply passes a message to the parent telling it some event occurred.

Two final things to look at —first, the <NoteSelector> component should use the selectedNote prop to properly style the component if the note prop is the same as the selectedNote prop. The template and script in src/components/NoteSelector.vue would look as follows:

<template>
  <div class="note-selector" v-bind:class="{active: note === selectedNote}">
    <p class="note-selector-title">
      {{ note.body | formatTitle }}
    </p>
    <p class="note-selector-timestamp">
      {{ note.timestamp | formatTimestamp }}
    </p>
  </div>
</template>

<script>
export default {
  name: 'note-selector',
  props: ['note', 'selectedNote'],
  filters: {
    formatTitle: function(body) {
      var maxLength = 20;
      if (body.length > maxLength) {
        return body.substring(0, maxLength - 3) + '...';
      } else if (body.length === 0) {
        return "New note";
      } else {
        return body;
      }
    },
    formatTimestamp: function(timestamp) {
      return new Date(timestamp).toUTCString();
    }
  }
};
</script>

Here we’re using the v-bind:class directive to conditionally apply the .active class on the div. The second thing is that the <NoteEditor> component should also receive the selectedNote prop and display it’s info accordingly. Here’s the template and script for src/components/NoteEditor.vue:

<template>
  <div class="note-editor">
    <p class="note-editor-info">
     {{ selectedNote.timestamp | formatTimestamp }}
    </p>
    <textarea class="note-editor-input"
      v-bind:value="selectedNote.body"
    >
    </textarea>
  </div>
</template>

<script>
export default {
  name: 'note-editor',
  props: ['selectedNote']
};
</script>

Here we’re registering 'selectedNote' as a prop and binding selectedNote.body to the <textarea>. We also need to format the selectedNote.timestamp— this is a bit of a problem, since we specifically defined formatTimestamp as a filter in the <NoteSelector> component. Now we’ll need to define the method in a more general place for multiple components to be able to use it. This can be done by registering the filter in src/main.js, right before we define the new Vue instance, as follows:

import Vue from "vue";
import App from "./App.vue";

Vue.config.productionTip = false;

Vue.filter("formatTimestamp", function (timestamp) {
  return new Date(timestamp).toUTCString();
});

new Vue({
  render: (h) => h(App),
}).$mount("#app");

That was a lot of code to make this particular feature work! You can see all the changes outlined above in this commit.

Edit the selected note on editor input #

Now we need to wire up the <NoteEditor> component to send events back up to the parent to edit the selectedNote’s body. Let’s look at it this time from the child going upwards, starting with the <NoteEditor> component in src/components/NoteEditor.vue:

<template>
  <div class="note-editor">
    <p class="note-editor-info">
      {{ selectedNote.timestamp | formatTimestamp }}
    </p>
    <textarea class="note-editor-input"
      v-bind:value="selectedNote.body"
      v-on:input="input($event)"
    >
    </textarea>
  </div>
</template>

<script>
export default {
  name: 'note-editor',
  props: ['selectedNote'],
  methods: {
    input: function($event) {
      this.$emit('inputNoteEditor', $event.target.value);
    }
  }
};
</script>

Here the code v-on:input="input($event)" is capturing the native DOM <textarea> input event and running the input method defined in the component’s methods option. The code this.$emit('inputNoteEditor', $event.target.value); will emit an 'inputNoteEditor' event to the parent component, passing along the text from the <textarea>’s native DOM event. This means the parent <NoteContainer> component must be wired up to listen for the 'inputNoteEditor' event, which would change the code in src/components/NoteContainer.vue as follows:

<template>
  <div class="note-container">
      <NoteSelectors
        v-bind:notes="notes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
      />
      <NoteEditor
        v-bind:selectedNote="selectedNote"
        v-on:inputNoteEditor="inputNoteEditor"
      />
  </div>
</template>

<script>
import NoteSelectors from './NoteSelectors';
import NoteEditor from './NoteEditor';

export default {
  name: 'note-container',
  props: ['notes', 'selectedNote'],
  methods: {
    selectNote: function(note) {
      this.$emit('selectNote', note);
    },
    inputNoteEditor: function(body) {
      this.$emit('inputNoteEditor', body);
    }
  },
  components: {
    NoteSelectors,
    NoteEditor
  }
};
</script>

The code v-on:inputNoteEditor="inputNoteEditor" is listening for inputNoteEditor events from the child <NoteEditor> component, which will run the inputNoteEditor method defined in the methods option. The code this.$emit('inputNoteEditor', body); in the inputNoteEditor method will simply bubble the information further to the parent. Finally, the parent component will receive the data and update the selectedNote, which you can see in src/App.vue:

<template>
  <div id="app">
    <Toolbar/>
      <NoteContainer
        v-bind:notes="notes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
        v-on:inputNoteEditor="updateSelectedNote"
      />
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    var initialNotes = [
      {id: 1, body: "This is a first test", timestamp: Date.now()},
      {id: 2, body: "This is a second test", timestamp: Date.now()},
      {id: 3, body: "This is a third test", timestamp: Date.now()}
    ];
    return {
      notes: initialNotes,
      selectedNote: initialNotes[0]
    };
  },
  methods: {
    selectNote: function(note) {
      this.selectedNote = note;
    },
    updateSelectedNote: function(body) {
      this.selectedNote.body = body;
      this.selectedNote.timestamp = Date.now();
    }
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

The code v-on:inputNoteEditor="updateSelectedNote" is listening for inputNoteEditor events from the <NoteContainer> component, and will run the updateSelectedNote method defined in the methods option accordingly. The updateSelectedNote method simply updates the selectedNote’s body and timestamp, which finally automatically trigger’s Vue.js to re-render all the child components.

Create a new note with a button #

Now let’s implement the ability to create a new note. Clicking on the “New” button should create a new note (new id, no body, current timestamp). The new note should become the currently selected note and appear at the top of the list of note selectors. Let’s start with the child <Toolbar> component in src/components/Toolbar.vue:

<template>
  <div class="toolbar">
    <button class="toolbar-button" v-on:click="clickNew">
      New
    </button>
    <button class="toolbar-button">Delete</button>
    <input class="toolbar-search" type="text" placeholder="Search...">
  </div>
</template>

<script>
export default {
  name: 'toolbar',
  methods: {
    clickNew: function() {
      this.$emit('clickNew');
    }
  }
};
</script>

Here the code v-on:click="clickNew" is capturing the native DOM <button> click event and running the clickNew method defined in the component’s methods option. The code this.$emit('clickNew'); will emit an 'clickNew' event to the parent component. This means the parent <App> component must be wired up to listen for the 'clickNew' event, which would change the code in src/App.vue as follows:

<template>
  <div id="app">
    <Toolbar v-on:clickNew="createNote"/>
      <NoteContainer
        v-bind:notes="notes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
        v-on:inputNoteEditor="updateSelectedNote"
      />
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    var initialNotes = [
      {id: 1, body: "This is a first test", timestamp: Date.now()},
      {id: 2, body: "This is a second test", timestamp: Date.now()},
      {id: 3, body: "This is a third test", timestamp: Date.now()}
    ];
    return {
      notes: initialNotes,
      selectedNote: initialNotes[0]
    };
  },
  methods: {
    selectNote: function(note) {
      this.selectedNote = note;
    },
    updateSelectedNote: function(body) {
      this.selectedNote.body = body;
      this.selectedNote.timestamp = Date.now();
    },
    createNote: function() {
      var newNote = {
        id: Date.now(),
        body: "",
        timestamp: Date.now()
      };
      this.notes.push(newNote);
      this.selectedNote = newNote;
    }
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

The code v-on:clickNew="createNote" is listening for clickNew events from the <Toolbar> component, and will run the createNote method defined in the methods option accordingly. The createNote method pushes a new empty note into the notes data as well as updates the selectedNote data to the new note, which finally automatically trigger’s Vue.js to re-render all the child components.

Delete the selected note with a button #

Wiring up this feature starts off pretty similar to the new note feature. Let’s again start with the child <Toolbar> component in src/components/Toolbar.vue:

<template>
  <div class="toolbar">
    <button class="toolbar-button" v-on:click="clickNew">
      New
    </button>
    <button class="toolbar-button" v-on:click="clickDelete">
      Delete
    </button>
    <input class="toolbar-search" type="text" placeholder="Search...">
  </div>
</template>

<script>
export default {
  name: 'toolbar',
  methods: {
    clickNew: function() {
      this.$emit('clickNew');
    },
    clickDelete: function() {
      this.$emit('clickDelete');
    }
  }
};
</script>

Here the code v-on:click="clickDelete" is capturing the native DOM <button> click event and running the clickDelete method defined in the component’s methods option. The code this.$emit('clickDelete'); will emit an 'clickDelete' event to the parent component. This means the parent <App> component must be wired up to listen for the 'clickDelete' event, which would change the code in src/App.vue as follows:

<template>
  <div id="app">
      <Toolbar
        v-on:clickNew="createNote"
        v-on:clickDelete="deleteNote"
      />
      <NoteContainer
        v-bind:notes="notes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
        v-on:inputNoteEditor="updateSelectedNote"
      />
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    var initialNotes = [
      {id: 1, body: "This is a first test", timestamp: Date.now()},
      {id: 2, body: "This is a second test", timestamp: Date.now()},
      {id: 3, body: "This is a third test", timestamp: Date.now()}
    ];
    return {
      notes: initialNotes,
      selectedNote: initialNotes[0]
    };
  },
  methods: {
    selectNote: function(note) {
      this.selectedNote = note;
    },
    updateSelectedNote: function(body) {
      this.selectedNote.body = body;
      this.selectedNote.timestamp = Date.now();
    },
    createNote: function() {
      var newNote = {
        id: Date.now(),
        body: "",
        timestamp: Date.now()
      };
      this.notes.push(newNote);
      this.selectedNote = newNote;
    },
    deleteNote: function() {
      var index = this.notes.indexOf(this.selectedNote);
      if (index !== -1) {
        this.notes.splice(index, 1);
        if (this.notes.length > 0) {
          this.selectedNote = this.notes[0];
        } else {
          this.selectedNote = {};
        }
      }
    }
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

The code v-on:clickDelete="deleteNote" is listening for clickDelete events from the <Toolbar> component, and will run the deleteNote method defined in the methods option accordingly. The deleteNote method deletes the selected note from the notes data, which finally automatically trigger’s Vue.js to re-render all the child components.

However, there’s a problem — the deleteNote method also needs to select a new note in place of the one that’s deleted. The problem is that selecting a new note means we need to know the top of the list of the transformed (sorted) notes, which we defined in the sub-child <NoteSelectors> component. That seemed like the right decision at the time, but now we’ll need to refactor that method to be in the parent component, then pass the transformed notes as a prop to the appropriate children. This would change the code in src/App.vue as follows:

<template>
  <div id="app">
      <Toolbar
        v-on:clickNew="createNote"
        v-on:clickDelete="deleteNote"
      />
      <NoteContainer
        v-bind:notes="notes"
        v-bind:transformedNotes="transformedNotes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
        v-on:inputNoteEditor="updateSelectedNote"
      />
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    var initialNotes = [
      {id: 1, body: "This is a first test", timestamp: Date.now()},
      {id: 2, body: "This is a second test", timestamp: Date.now()},
      {id: 3, body: "This is a third test", timestamp: Date.now()}
    ];
    return {
      notes: initialNotes,
      selectedNote: initialNotes[0]
    };
  },
  methods: {
    selectNote: function(note) {
      this.selectedNote = note;
    },
    updateSelectedNote: function(body) {
      this.selectedNote.body = body;
      this.selectedNote.timestamp = Date.now();
    },
    createNote: function() {
      var newNote = {
        id: Date.now(),
        body: "",
        timestamp: Date.now()
      };
      this.notes.push(newNote);
      this.selectedNote = newNote;
    },
    deleteNote: function() {
      var index = this.notes.indexOf(this.selectedNote);
      if (index !== -1) {
        this.notes.splice(index, 1);
        if (this.transformedNotes.length > 0) {
          this.selectedNote = this.transformedNotes[0];
        } else {
          this.selectedNote = {};
        }
      }
    }
  },
  computed: {
    transformedNotes: function() {
      return this.notes.slice().sort(function(a, b) {
        return b.timestamp - a.timestamp;
      });
    }
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

The code in src/components/NoteContainer.vue would simply pass the transformedNotes props down as follows:

<template>
  <div class="note-container">
      <NoteSelectors
        v-bind:notes="notes"
        v-bind:transformedNotes="transformedNotes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
      />
      <NoteEditor
        v-bind:selectedNote="selectedNote"
        v-on:inputNoteEditor="inputNoteEditor"
      />
  </div>
</template>

<script>
import NoteSelectors from './NoteSelectors';
import NoteEditor from './NoteEditor';

export default {
  name: 'note-container',
  props: ['notes', 'transformedNotes', 'selectedNote'],
  methods: {
    selectNote: function(note) {
      this.$emit('selectNote', note);
    },
    inputNoteEditor: function(body) {
      this.$emit('inputNoteEditor', body);
    }
  },
  components: {
    NoteSelectors,
    NoteEditor
  }
};
</script>

And finally, the code in src/components/NoteSelectors.vue would no longer compute the transformedNotes but instead would use the transformedNotes props as follows:

<template>
  <div class="note-selectors">
      <NoteSelector
        v-for="note in transformedNotes"
        v-bind:note="note"
        v-bind:selectedNote="selectedNote"
        v-bind:key="note.id"
        v-on:click.native="selectNote(note)"
      />
  </div>
</template>

<script>
import NoteSelector from './NoteSelector';

export default {
  name: 'note-selectors',
  props: ['notes', 'transformedNotes', 'selectedNote'],
  methods: {
    selectNote: function(note) {
      this.$emit('selectNote', note);
    }
  },
  components: {
    NoteSelector
  }
};
</script>

<template>
  <div class="note-editor" v-if="selectedNote.id">
    <p class="note-editor-info">
      {{ selectedNote.timestamp | formatTimestamp }}
    </p>
      <textarea class="note-editor-input"
        v-bind:value="selectedNote.body"
        v-on:input="input($event)"
      >
    </textarea>
  </div>
</template>

Filter notes on search input #

The final feature is to be able to search notes immediately as you type in the search input. This means we’ll need to keep track of a new piece of data — the search text the user enters. This search text will be used to filter the list of notes, which means it must be defined in the <App> component, since that’s the component that stores the notes. The code in src/App.vue would change as follows:

<template>
  <div id="app">
      <Toolbar
        v-on:clickNew="createNote"
        v-on:clickDelete="deleteNote"
        v-bind:searchNoteText="searchNoteText"
        v-on:inputSearchNoteText="updateSearch"
      />
      <NoteContainer
        v-bind:notes="notes"
        v-bind:transformedNotes="transformedNotes"
        v-bind:selectedNote="selectedNote"
        v-on:selectNote="selectNote"
        v-on:inputNoteEditor="updateSelectedNote"
      />
  </div>
</template>

<script>
import Toolbar from './components/Toolbar';
import NoteContainer from './components/NoteContainer';

export default {
  name: 'app',
  data: function() {
    var initialNotes = [
      {id: 1, body: "This is a first test", timestamp: Date.now()},
      {id: 2, body: "This is a second test", timestamp: Date.now()},
      {id: 3, body: "This is a third test", timestamp: Date.now()}
    ];
    return {
      notes: initialNotes,
      selectedNote: initialNotes[0],
      searchNoteText: ""
    };
  },
  methods: {
    selectNote: function(note) {
      this.selectedNote = note;
    },
    updateSelectedNote: function(body) {
      this.selectedNote.body = body;
      this.selectedNote.timestamp = Date.now();
    },
    createNote: function() {
      var newNote = {
        id: Date.now(),
        body: "",
        timestamp: Date.now()
      };
      this.notes.push(newNote);
      this.selectedNote = newNote;
    },
    deleteNote: function() {
      var index = this.notes.indexOf(this.selectedNote);
      if (index !== -1) {
        this.notes.splice(index, 1);
        if (this.transformedNotes.length > 0) {
          this.selectedNote = this.transformedNotes[0];
        } else {
          this.selectedNote = {};
        }
      }
    },
    updateSearch: function(newSearchText) {
      this.searchNoteText = newSearchText;
      if (this.transformedNotes.length === 0) {
        this.selectedNote = {};
      } else if (this.transformedNotes.indexOf(this.selectedNote) === -1) {
        this.selectedNote = this.transformedNotes[0];
      }
    }
  },
  computed: {
    transformedNotes: function() {
      return this.notes
        .filter(function(note) {
          return note.body.toLowerCase().indexOf(this.searchNoteText.toLowerCase()) !== -1;
        }.bind(this))
        .sort(function(a, b) {
          return b.timestamp - a.timestamp;
        });
    }
  },
  components: {
    Toolbar,
    NoteContainer
  }
};
</script>

Let’s go through these changes one at a time.

The code v-bind:searchNoteText="searchNoteText" is sending the searchNoteText data to the <Toolbar> component as a prop named searchNoteText.
The code v-on:inputSearchNoteText="updateSearch" is listening for inputSearchNoteText events from the <Toolbar> component, and will run the updateSearch method defined in the methods option accordingly.
The updateSearch method updates the searchNoteText data to the input argument, which automatically trigger’s Vue.js to re-render all the child components. It also has to update the selectedNote to be the top of the transformedNotes if possible.
The transformedNotes computed property, which used to simply sort the notes, is now responsible for both filtering and sorting the notes. The notes are filtered based on whether or not the body contains the searchNoteText data.

Finally, we need to wire the child <Toolbar> component in src/components/Toolbar.vue to respond to and fire off the right events:

<template>
  <div class="toolbar">
    <button class="toolbar-button" v-on:click="clickNew">
      New
    </button>
    <button class="toolbar-button" v-on:click="clickDelete">
      Delete
    </button>
      <input class="toolbar-search" type="text" placeholder="Search..."
        v-bind:value="searchNoteText"
        v-on:input="inputSearchNoteText($event)"
      />
  </div>
</template>

<script>
export default {
  name: 'toolbar',
  props: ['searchNoteText'],
  methods: {
    clickNew: function() {
      this.$emit('clickNew');
    },
    clickDelete: function() {
      this.$emit('clickDelete');
    },
    inputSearchNoteText: function($event) {
      this.$emit('inputSearchNoteText', $event.target.value);
    }
  }
};
</script>

As seen before, the <Toolbar> component contains no logic — it simply receives props and sends messages to the parent when the user interacts with it in various ways.

You can take a look at the final app in all its glory in this GitHub repository.

Conclusion #

As you can see, working with components is incredibly different than without, even when using the same Vue.js framework! This is truly what Vue.js means when it describes itself as a progressive framework — you don’t need to understand components to get started with it, which simplifies the on boarding learning curve. For larger scale apps, it can be worthwhile to learn this component architecture as a solid way to organize your code.

I would argue that for this particular notes app, a Vue.js component architecture may be overkill. However, this is a debatable point, since every app continues to grow in complexity as more features are added. Still, even though components are daunting at first, you start to get used to the repeating patterns and they become easy enough over time. Only when your app grows so large that it becomes nearly impossible to understand all the code at once will you appreciate the clean separations that a component architecture provides.

In the next part of this series, we’ll take a look at implementing the same notes app using React, a completely different framework with a similar component model. Stay tuned!

Comparing Frontend Approaches Part 3: Vue.js

2017-09-19T00:00:00Z

In this part we will be implementing the web based clone of the Mac Notes app using Vue.js. Vue.js is a JavaScript framework that came out in 2014 and has recently become one of the most popular frameworks in a very crowded market. It currently has over 65,000 stars on GitHub, which makes it the second most popular JavaScript framework (React being the first).

Vue.js uses a template based approach, which was heavily inspired by Angular 1 (which was once the dominant framework). It also uses a virtual DOM under the hood, which was inspired by React. Vue.js labels itself as “the progressive JavaScript framework”, which means you don’t need to learn the entire framework to get started — you start with the basics and add on more advanced features as they become necessary. Let’s see what it’s like to get started with it in practice!

Note — this isn’t meant to be a tutorial for people completely new to Vue.js. If you are in that category, I would recommend reading through at least the beginning of the official guide (which is very well written and beginner friendly) before reading through this post.

Installation #

Starting from our initial template in part 1, installing Vue.js is easy enough (almost as easy as installing jQuery). Here are the two changes in the HTML head tag:

<script src="https://unpkg.com/vue/dist/vue.js"></script>
<script src="js/notes.js" defer></script>

The first line includes Vue.js from a CDN. The second line includes the app’s JavaScript and only has one change from the original template — the defer attribute. This ensures that the notes.js file is loaded only after the DOM is ready. In the notes.js file we need the following initial code:

var app = new Vue({
  el: "#app",
});

This instantiates the Vue instance — pretty much all of our JavaScript will be written and organized within this object. The el option has a value of '#app', which is the id of the HTML div where Vue.js will bind itself to.

Display note titles from an array of notes #

Now that Vue.js is installed, let’s change the starting template to generate the dynamic notes list using JavaScript. In Vue.js, we will store any application state with an object in the data option. Here I’m representing the notes as an array of objects, where each object has an id, a body, and a timestamp. The Date.now() returns the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.

data: {
  notes: [
    { id: 1, body: "This is a first test", timestamp: Date.now() },
    { id: 2, body: "This is a second test", timestamp: Date.now() },
    { id: 3, body: "This is a third test", timestamp: Date.now() },
  ];
}

Once we have the notes in the data, we can bind them to the DOM using Vue’s template syntax directly in the HTML:

<div class="note-selectors">
  <div class="note-selector" v-for="note in notes">
    <p class="note-selector-title">{{ note.body }}</p>
    <p class="note-selector-timestamp">{{ note.timestamp }}</p>
  </div>
</div>

It looks like there’s only a single .note-selector div here, but the v-for directive is Vue specific syntax that will repeat the div for each note in the notes array that was defined in the Vue instance. Within any element content you can write JavaScript within double curly brackets, which is capable of referencing data defined in the Vue instance data option.

You can check out a live demo here.

Use computed properties and filters to sort and format notes #

Similar to the jQuery example, we’ll make helper methods to make sure the notes are sorted (newest first) and formatted properly (titles should be computed from the body, timestamps should be converted from milliseconds into a human readable string). Unlike jQuery, Vue.js gives a structure to organize where such methods can go — in the methods option:

var app = new Vue({
  el: "#app",
  data: {
    notes: [
      { id: 1, body: "This is a first test", timestamp: Date.now() },
      { id: 2, body: "This is a second test", timestamp: Date.now() },
      { id: 3, body: "This is a third test", timestamp: Date.now() },
    ],
  },
  methods: {
    transformNotes: function (notes) {
      return notes.slice().sort(function (a, b) {
        return b.timestamp - a.timestamp;
      });
    },
    formatTitle: function (body) {
      var maxLength = 20;
      if (body.length > maxLength) {
        return body.substring(0, maxLength - 3) + "...";
      } else if (body.length === 0) {
        return "New note";
      } else {
        return body;
      }
    },
    formatTimestamp: function (timestamp) {
      return new Date(timestamp).toUTCString();
    },
  },
});

To use these methods, you would change the HTML template as follows:

<div class="note-selectors">
  <div class="note-selector" v-for="note in transformNotes(notes)">
    <p class="note-selector-title">{{ formatTitle(note.body) }}</p>
    <p class="note-selector-timestamp">{{ formatTimestamp(note.timestamp) }}</p>
  </div>
</div>

This works great, but Vue.js actually provides other options besides methods to work with data to make it both more readable and performant. One option is defining computed properties, which essentially creates new data available in the template that is computed based on existing data. In this case we can refactor the transformNotes function in the methods option into a transformedNotes function in the computed option:

var app = new Vue({
  el: "#app",
  data: {
    notes: [
      { id: 1, body: "This is a first test", timestamp: Date.now() },
      { id: 2, body: "This is a second test", timestamp: Date.now() },
      { id: 3, body: "This is a third test", timestamp: Date.now() },
    ],
  },
  computed: {
    transformedNotes: function () {
      return this.notes.slice().sort(function (a, b) {
        return b.timestamp - a.timestamp;
      });
    },
  },
  methods: {
    formatTitle: function (body) {
      var maxLength = 20;
      if (body.length > maxLength) {
        return body.substring(0, maxLength - 3) + "...";
      } else if (body.length === 0) {
        return "New note";
      } else {
        return body;
      }
    },
    formatTimestamp: function (timestamp) {
      return new Date(timestamp).toUTCString();
    },
  },
});

Note the use of this.notes in the transformNotes function — any function within the Vue.js instance can refer to any value from the data object using this. The HTML template would refer to the computed property transformedNotes instead of the method transformNotes(notes) as follows:

<div class="note-selector" v-for="note in transformedNotes"></div>

At a glance, using computed properties aren’t too different from using methods. The reason they’re valuable is that methods will be called whenever a re-render occurs, whereas a computed property can be cached and will only be recomputed when the underlying data changes (which Vue manages for you).

Vue.js also provides a mechanism called filters, which can be used for simple text formatting. That’s exactly what we’re doing with the formatTitle and formatTimestamp methods, so let’s see what they would look like using filters instead:

var app = new Vue({
  el: "#app",
  data: {
    notes: [
      { id: 1, body: "This is a first test", timestamp: Date.now() },
      { id: 2, body: "This is a second test", timestamp: Date.now() },
      { id: 3, body: "This is a third test", timestamp: Date.now() },
    ],
  },
  computed: {
    transformedNotes: function () {
      return this.notes.slice().sort(function (a, b) {
        return b.timestamp - a.timestamp;
      });
    },
  },
  filters: {
    formatTitle: function (body) {
      var maxLength = 20;
      if (body.length > maxLength) {
        return body.substring(0, maxLength - 3) + "...";
      } else if (body.length === 0) {
        return "New note";
      } else {
        return body;
      }
    },
    formatTimestamp: function (timestamp) {
      return new Date(timestamp).toUTCString();
    },
  },
  methods: {},
});

And the HTML template would change as follows:

<div class="note-selectors">
  <div class="note-selector" v-for="note in transformedNotes">
    <p class="note-selector-title">{{ note.body | formatTitle }}</p>
    <p class="note-selector-timestamp">{{ note.timestamp | formatTimestamp }}</p>
  </div>
</div>

I would say that when you’re first starting out with Vue.js, it may be helpful just to stick with methods instead of worrying about computed properties and filters, since you can pull off the same functionality. It’s nice to be aware of them as potential tools if you find yourself in need of better code organization or performance!

Select a note on title click #

Now let’s implement the ability to actually select notes. Clicking on a note title should both highlight the selected note on the left as well as display the contents in the editor on the right. Here’s a complete working example, which we’ll go over in detail:

First we need to keep track of a new variable selectedNote (which we’ll default to the first note). To do so, we’ll move the initialization of the data into a new mounted option, which is one of several lifecycle hooks available. The mounted function runs once when everything is ready in the DOM:

data: {
  notes: [],
  selectedNote: {}
},
mounted: function() {
  this.notes = [
    {id: 1, body: "This is a first test", timestamp: Date.now()},
    {id: 2, body: "This is a second test", timestamp: Date.now()},
    {id: 3, body: "This is a third test", timestamp: Date.now()}
  ];
  this.selectedNote = this.notes[0];
},

Note that Vue.js requires all data that will be referred to an HTML template to be defined in the data object — this is why I’m defining notes as an empty array and selectedNote as an empty object. In the mounted function, I’m putting in the actual data. This is good organization for later, where we can replace the hard coded data with a web request from a backend for real notes data.

Now let’s take a look at the changes in the HTML template:

<div class="note-selectors">
  <div
    class="note-selector"
    v-for="note in transformedNotes"
    v-on:click="selectNote(note)"
    v-bind:class="{active: note === selectedNote}"
  >
    <p class="note-selector-title">{{ note.body | formatTitle }}</p>
    <p class="note-selector-timestamp">{{ note.timestamp | formatTimestamp }}</p>
  </div>
</div>

We have two new lines — first is v-on:click="selectNote(note)", which essentially works as a DOM event handler and will run the selectNote method when the div is clicked. We haven’t defined this method yet, we’ll look at that in a bit. The second new line is v-bind:class="{active: note === selectedNote}", which will conditionally add the active class to the div (depending on whether or not the particular note equals the selected note from Vue’s data). It’s important to note that with Vue.js, you must use v-bind with any HTML attributes that you need to be dynamic.

Side note — Vue.js provides shortcuts for v-on and v-bind — v-on:click becomes @click and v-bind:class becomes :class. I’ll avoid using the shortcuts for the sake of being explicit, but it’s good to know about them when writing and reading other Vue.js code.

The selectNote method is easy enough to define:

methods: {
  selectNote: function(note) {
    this.selectedNote = note;
  }
}

At this point everything works automagically — clicking on a note will run the selectNote function, which updates this.selectedNote, which will trigger a re-render, which will bind the active class to the appropriate div. This is the promise of modern JavaScript frameworks — your job as a programmer is to define data and the ways it gets transformed. The framework’s job is to manage and manipulate the DOM under the hood.

The last bit here is to update the note editor on the right to display the selected note dynamically. Here’s the HTML template needed to do so:

<div class="note-editor">
  <p class="note-editor-info">{{ selectedNote.timestamp | formatTimestamp }}</p>
  <textarea class="note-editor-input">
    {{ selectedNote.body }}
  </textarea>
</div>

Since the template is referring to selectedNote, which is defined and managed in the Vue instance, no other work is necessary!

You can check out a live demo here.

Edit the selected note on editor input #

Next we’ll bind the <textarea> to the note data. Vue.js has this functionality built in with the v-model directive:

<div class="note-editor">
  <p class="note-editor-info">{{ selectedNote.timestamp | formatTimestamp }}</p>
  <textarea class="note-editor-input" v-model="selectedNote.body"></textarea>
</div>

(Note that we’re no longer putting content between the <textarea></textarea> tags, the Vue.js v-model directive is handling it now.) Now whenever the user enters text, the selectedNote’s body automatically gets updated! Now the only thing missing is the selectedNote’s timestamp — it should get updated to the current time whenever the text changes. We can accomplish this using the watch option:

var app = new Vue({
  el: "#app",
  data: {
    // ...
  },
  mounted: function () {
    // ...
  },
  computed: {
    // ...
  },
  filters: {
    // ...
  },
  methods: {
    // ...
  },
  watch: {
    notes: {
      handler: function () {
        this.selectedNote.timestamp = Date.now();
      },
      deep: true,
    },
  },
});

This is telling Vue.js to watch the notes data for any changes and run the code to update the selectedNote’s timestamp whenever something does change. (It seems a bit strange to watch notes instead of selectedNote, but see what happens if you change it to selectedNote — each time the user selects a new note, its timestamp gets updated, which is not the desired behavior!)

Create a new note with a button #

Now let’s implement the ability to create a new note. Clicking on the “New” button should create a new note (new id, no body, current timestamp). The new note should become the currently selected note and appear at the top of the list of note selectors. Here’s a complete working example, which we’ll go over in detail:

There’s actually very little that’s changed here to make this feature work! In the HTML template, we need to make a v-on:click on the “New” button:

<button class="toolbar-button" v-on:click="createNote()">New</button>

And in the JavaScript, we need to define the createNote method:

methods: {
  selectNote: function(note) {
    this.selectedNote = note;
  },
  createNote: function() {
    var newNote = {
      id: Date.now(),
      body: "",
      timestamp: Date.now()
    };
    this.notes.push(newNote);
    this.selectedNote = newNote;
  }
},

(Here I’m using Date.now() as a quick and dirty way of generating a id, it should be replaced with a more robust approach for a guaranteed unique id.) Creating a new note is as simple as updating the notes and selectedNote data — Vue.js handles all the DOM updates necessary!

You can check out a live demo here.

Delete the selected note with a button #

Again, it’s pretty easy to get the delete feature to work. In the HTML template, we need to make a v-on:click on the “Delete” button:

<button class="toolbar-button" v-on:click="deleteNote()">Delete</button>

And in the JavaScript, we need to define the deleteNote method:

methods: {
  selectNote: function(note) {
  this.selectedNote = note;
  },
  createNote: function() {
    var newNote = {
      id: Date.now(),
      body: "",
      timestamp: Date.now()
    };
    this.notes.push(newNote);
    this.selectedNote = newNote;
  },
  deleteNote: function(note) {
    var index = this.notes.indexOf(this.selectedNote);
    if (index !== -1) {
      this.notes.splice(index, 1);
      if (this.transformedNotes.length > 0) {
        this.selectedNote = this.transformedNotes[0];
      } else {
        this.selectedNote = {};
      }
    }
  }
},

Note that when you delete the selected note, you have to determine which note to select in its place. Finally, we need to make sure the editor itself is hidden when there are no notes. This can be done with one easy change using the v-if directive in the HTML template:

<div class="note-editor" v-if="selectedNote.id">
  <p class="note-editor-info">{{ selectedNote.timestamp | formatTimestamp }}</p>
  <textarea class="note-editor-input" v-model="selectedNote.body"></textarea>
</div>

Filter notes on search input #

The final feature I’m going to implement is to be able to search notes immediately as you type in the search input. The first step is to add a v-model in the HTML template on the search input:

<input class="toolbar-search" type="text" placeholder="Search..." v-model="searchNoteText" />

Don’t forget to initialize the searchNoteText data:

data: {
  notes: [],
  selectedNote: {},
  searchNoteText: ""
},

Now in order to get the filtering effect, we simply need to change the already existing computed property transformedNotes to both filter and sort (instead of just sort):

computed: {
  transformedNotes: function() {
    return this.notes
      .filter(function(note) {
        return note.body.toLowerCase().indexOf(this.searchNoteText.toLowerCase()) !== -1;
      }.bind(this))
      .sort(function(a, b) {
        return b.timestamp - a.timestamp;
      });
  }
},

Perfect! The only thing missing is that filtering the list should also select the appropriate note, which means the selectedNote data should update whenever the searchNoteText data changes. We can use a watch function on searchNoteText for that:

watch: {
  notes: {
    handler: function() {
      this.selectedNote.timestamp = Date.now();
    },
    deep: true
  },
  searchNoteText: function() {
    if (this.transformedNotes.length === 0) {
      this.selectedNote = {};
    } else if (this.transformedNotes.indexOf(this.selectedNote) === -1) {
      this.selectedNote = this.transformedNotes[0];
    }
  }
}

Note that I’m referring to this.transformedNotes in the function, since I’m trying to select the first note in the list of filtered and sorted notes.

You can check out the final working example in all its glory here.

Conclusion #

If you compare working with Vue.js to jQuery, you can see that the things you’re concerned about as a programmer are very different! In some sense I would consider jQuery to be easier to get started with, particularly if you have a good understanding of the DOM. But as we got deeper into the features, it was a lot simpler to write the Vue.js code, since we can keep our focus on data manipulation as opposed to both data manipulation plus DOM manipulation.

Learning Vue.js might seem a bit daunting to an absolute beginner — we covered the v-for, v-on, v-bind, v-model, and v-if HTML template directives, as well as the data, mounted, computed, filters, methods, and watch Vue instance options. However, getting started with Vue.js is a lot easier than this — you can get pretty far with with just the v-for, v-model, and v-click directives with the data and methods Vue instance options! Basically you should learn new directives and options as the need arises — this is what Vue.js means when it says it’s a progressive framework. And compared to the other frameworks we’ll be looking at in this series, it’s definitely the easiest to get up and running!

So the promise of Vue.js (or any modern JavaScript framework really) is that it’s a bit harder to get started, but once you learn the framework it becomes simpler to add new features. In the next part of this series, we’ll take that concept to the next step by rebuilding the same app using Vue.js, this time with components. Stay tuned!

Comparing Frontend Approaches Part 2: jQuery

2017-09-18T00:00:00Z

In this part we will be implementing the web based clone of the Mac Notes app using jQuery. jQuery is a JavaScript library that came out in 2006, and within several years became the most popular JavaScript library in use on the web (used by 70% of the top 100,000 sites online).

jQuery provides an intuitive API to directly manipulate the DOM to create interactive websites. In 2017, jQuery’s DOM manipulation approach is far less dominant, with templating and virtual DOM based approaches taking over. Nevertheless, jQuery remains an excellent library that’s reasonably lightweight, easy to get started with, and still used by many apps in production today. Let’s see what it’s like to use in practice!

Note — one could argue that it would make more sense to start with vanilla JavaScript instead of jQuery, which is completely reasonable. jQuery provides some concise helper functions that makes it easier to demonstrate certain features, but you should feel free to mentally substitute any jQuery specific approaches I’m taking with the corresponding vanilla JavaScript — the general approach should be the same.

Installation #

Starting from our initial template in part 1, installing jQuery requires only 2 lines in the HTML head tag:

<script
  src="https://code.jquery.com/jquery-3.2.1.js"
  integrity="sha256-DZAnKJ/6XZ9si04Hgrsxu/8s717jcIzLy3oi35EouyE="
  crossorigin="anonymous"
></script>

<script src="js/notes.js" defer></script>

The first line includes the jQuery library from a CDN (the integrity and crossorigin attributes are for security when using outside resources). The second line includes the app’s JavaScript and only has one change from the original template — the defer attribute. This ensures that the notes.js file is loaded only after the DOM is ready (before this attribute existed, you had to resort to tactics such as putting the script tag at the end of the body tag or using a DOMContentLoaded event listener wrapping your entire code).

Display note titles from an array of notes #

Now that jQuery’s installed, let’s change the starting template to generate the dynamic notes list using JavaScript. First we'll representing the notes as an array of objects, where each object has an id, a body, and a timestamp. The Date.now() returns the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.

var notes = [
  { id: 1, body: "This is a first test", timestamp: Date.now() },
  { id: 2, body: "This is a second test", timestamp: Date.now() },
  { id: 3, body: "This is a third test", timestamp: Date.now() },
];

Once we have the notes data, we can delete the placeholder HTML content and generate the note selectors ourselves:

notes.forEach(function(note) {
  $('.note-selectors').append(
    '<div class="note-selector">' +
      '<p class="note-selector-title">' + note.body + '</p>' +
      '<p class="note-selector-timestamp">' + note.timestamp + '</p>' +
    '</div>'
  );
});

Here I’m using jQuery to both create new DOM elements and append them directly into the DOM. Right now I’m temporarily using the body and integer timestamp directly as the title and timestamp — they’ll need to be formatted appropriately to look pretty.

You can check out a live demo here.

Note that there is an additional concern that’s more subtle — adding the note.body directly into the DOM here can open up an XSS vulnerability, where a malicious user can enter a <script> tag in the HTML input and run unwanted JavaScript. You would need to sanitize the input yourself (oddly enough jQuery’s .text() method won’t be enough here), which is one disadvantage of using a library over a framework (which generally have such security features built in).

Use methods to sort and format notes #

Now let’s make helper methods to make sure the notes are sorted (newest first) and formatted properly (titles should be computed from the body, timestamps should be converted from milliseconds into a human readable string).

function transformNotes(notes) {
  return notes.slice().sort(function (a, b) {
    return b.timestamp - a.timestamp;
  });
}

function formatTitle(body) {
  var maxLength = 20;
  if (body.length > maxLength) {
    return body.substring(0, maxLength - 3) + "...";
  } else if (body.length === 0) {
    return "New note";
  } else {
    return body;
  }
}

function formatTimestamp(timestamp) {
  return new Date(timestamp).toUTCString();
}

The logic here is somewhat simplified — the title should account for line breaks, the string output from the native toUTCString isn’t the prettiest, etc. However, since they are separate pure functions, it will be simple to make them more robust later. The loop would be modified to use the functions as follows:

transformNotes(notes).forEach(function(note) {
  $('.note-selectors').append(
    '<div class="note-selector">' +
      '<p class="note-selector-title">' + formatTitle(note.body) + '</p>' +
      '<p class="note-selector-timestamp">' + formatTimestamp(note.timestamp) + '</p>' +
    '</div>'
  );
});

Select a note on title click #

Now let’s implement the ability to actually select notes. Clicking on a note title should both highlight the selected note on the left as well as display the contents in the editor on the right. First we need to keep track of a new variable selectedNote (which we’ll default to the first note).

var notes = [
  {id: 1, body: "This is a first test", timestamp: Date.now()},
  {id: 2, body: "This is a second test", timestamp: Date.now()},
  {id: 3, body: "This is a third test", timestamp: Date.now()}
];
var selectedNote = notes[0];

Now comes the tricky part — in order to be able to click on a note title and display its corresponding information, we need to create a binding between the DOM and the data in JavaScript. One way to pull this off is by embedding the relevant data into the DOM using HTML data-* attributes. In this case, each time I’m creating a new note selector DOM element with jQuery, I want to add the relevant note data into the DOM element itself using data-id, data-body, and data-timestamp attributes. For the sake of code organization, I extracted the code that creates the note selector DOM elements to a function called domCreateNoteSelectors:

function domCreateNoteSelectors(notes, selectedNote) {
  transformNotes(notes).forEach(function(note) {
    var $noteSelector = $(
      '<div class="note-selector' + (note === selectedNote ? ' active' : '') + '">' +
        '<p class="note-selector-title">' + formatTitle(note.body) + '</p>' +
        '<p class="note-selector-timestamp">' + formatTimestamp(note.timestamp) + '</p>' +
      '</div>'
    );
    $noteSelector.data(note);
    $('.note-selectors').append($noteSelector);
  });
}

Note the variable name $noteSelector is using the convention of putting a $ in front of any variable which represents a DOM element. The key line which binds the data in JavaScript to the DOM is:

$noteSelector.data(note);

This handy jQuery method takes all the keys in the note object (in this case id, body, and timestamp) and creates corresponding data-* attributes in the DOM element (in this case data-id, data-body, and data-timestamp).

Now that we have data binding, we’ll need to make an event listener to trigger whenever the user clicks on a note title:

$(".note-selectors").on("click", ".note-selector", function () {
  $(".note-selector").removeClass("active");
  $(this).addClass("active");
  domUpdateNoteEditor($(this).data());
});

(Note that I’m putting a delegated event listener on the .note-selectors DOM element and not on the .note-selector directly— this is because the .note-selector elements don’t exist until later!) The event listener has two responsibilities — one is to update the style such that the selector appears highlighted, which is achieved by removing the .active class from all note selectors, then adding it back to the note selector that was just clicked. The other responsibility is to update the note editor on the right to display the appropriate note data. The note data is extracted from the DOM using $(this).data(), and is passed to a separate domUpdateNoteEditor function:

function domUpdateNoteEditor(selectedNote) {
  $(".note-editor-info").html(formatTimestamp(selectedNote.timestamp));
  $(".note-editor-input").val(selectedNote.body);
}

You can check out a live demo here.

Edit the selected note on editor input #

Next we’ll bind the <textarea> to the note data. Each time the user changes the text, there’s quite a few things that need to be updated:

The underlying note data (body and timestamp)
The displayed timestamp in the note editor
The displayed title and timestamp in the current note selector
The sort order of the note selectors (the current one should be on top)

Here’s the code to make all these changes happen:

$(".note-editor-input").on("input propertychange", function (event) {
  // Update the note data
  var body = $(this).val();
  var timestamp = Date.now();
  $(".note-selector.active").data("body", body);
  $(".note-selector.active").data("timestamp", timestamp);

  // Update the DOM note editor timestamp
  $(".note-editor-info").html(formatTimestamp(timestamp));

  // Update the DOM currently selected note selector
  $(".note-selector.active .note-selector-title").html(formatTitle(body));
  $(".note-selector.active .note-selector-timestamp").html(formatTimestamp(timestamp));

  // Update the DOM note selectors sorting order
  var $active = $(".note-selector.active").detach();
  $(".note-selectors").prepend($active);
});

This is where we start to see some difficulties with jQuery — while the DOM manipulation code itself is fairly straightforward, it becomes more and more complicated to remember the different parts of the DOM that need to be updated with each change.

Create a new note with a button #

Originally we made the domCreateNoteSelectors function to create note selectors in a loop. We’ll need to extract the code to make a single note selector into a separate domCreateNoteSelector function (so we can reuse it with the new note button):

function domCreateNoteSelector(note, selectedNote) {
  var $noteSelector = $(
    '<div class="note-selector' + (note === selectedNote ? ' active' : '') + '">' +
      '<p class="note-selector-title">' + formatTitle(note.body) + '</p>' +
      '<p class="note-selector-timestamp">' + formatTimestamp(note.timestamp) + '</p>' +
    '</div>'
  );
  $noteSelector.data(note);
  return $noteSelector;
}

// ...

function domCreateNoteSelectors(notes, selectedNote) {
  transformNotes(notes).forEach(function (note) {
    var $noteSelector = domCreateNoteSelector(note, selectedNote);
    $noteSelector.data(note);
    $(".note-selectors").append($noteSelector);
  });
}

Here’s the code that runs when the user clicks the “New” button (note that I added the .toolbar-button-new class in the HTML to make it easier to target the new button element):

$(".toolbar-button-new").on("click", function () {
  $(".note-selector").removeClass("active");
  var note = {
    id: Date.now(),
    body: "",
    timestamp: Date.now(),
  };
  var $noteSelector = domCreateNoteSelector(note, note);
  $(".note-selectors").prepend($noteSelector);
  domUpdateNoteEditor(note);
});

Here I’m using Date.now() as a quick and dirty way of generating a id, it should be replaced with a more robust approach for a guaranteed unique id. In order to make sure the new note is highlighted, I first removed the .active class from all note selectors, then created the new note selector with the domCreateNoteSelector function, which takes in the note to create along with the currently selected note (which in this case is itself). This works fine, but again it’s getting a little harder to follow exactly how the DOM is being updated.

You can check out a live demo here.

Delete the selected note with a button #

The delete button is in theory easy enough to implement — add an event listener to the “Delete” button which removes the currently selected note selector (which is marked with the class .active) from the DOM.

$(".toolbar-button-delete").on("click", function () {
  $(".note-selector.active").remove();
});

Unfortunately, this doesn’t address what note should be marked as the currently selected note after the current one is deleted. Here’s a second attempt:

$('.toolbar-button-delete').on('click', function() {
  $('.note-selector.active').remove();
  var children = $('.note-selectors').children();
  var $noteSelector = $(children[0]);
  $noteSelector.addClass('active');
  domUpdateNoteEditor($noteSelector.data());
});

This code will grab all the note selectors from the DOM and select the first one. Unfortunately, this doesn’t address what should happen when you delete the LAST note. Let’s say we want the app to hide the note editor completely if there are no notes:

$('.toolbar-button-delete').on('click', function() {
  $('.note-selector.active').remove();
  var children = $('.note-selectors').children();
  if (children.length > 0) {
    var $noteSelector = $(children[0]);
    $noteSelector.addClass('active');
    domUpdateNoteEditor($noteSelector.data());
  } else {
    $('.note-editor').hide();
  }
});

This works, but once the note editor is hidden, it will never unhide! So now we have to make sure the note editor is shown when you create a new note:

$(".toolbar-button-new").on("click", function () {
  $(".note-editor").show();
  //...
});

This completely works now, but we’re getting into the territory of what is known as “jQuery spaghetti” — the delete note feature requires writing code in both the delete button event listener as well as the new button event listener, which is highly unintuitive. As more features get added to the app, these types of unrelated dependencies start cropping up in more and more places, making it harder to reason about the code.

Filter notes on search input #

The final feature I’m going to implement is to be able to search notes immediately as you type in the search input. Before we implement it, I’m first going to extract out the code from the delete event listener that selects the appropriate note when the list changes into a function called domSelectDefaultChild, since we’ll need similar functionality when dynamically searching.

function domSelectDefaultChild() {
  var children = $('.note-selector:visible');
  if (children.length > 0) {
    var $noteSelector = $(children[0]);
    if ($('.note-selector.active').length === 0) {
      $noteSelector.addClass('active');
      domUpdateNoteEditor($noteSelector.data());
    }
  } else {
    $('.note-editor').hide();
  }
}

// ...

$('.toolbar-button-delete').on('click', function() {
  $('.note-selector.active').remove();
  domSelectDefaultChild();
});

Now let’s add an event listener on the search input. This code will need to do the following things:

Show the note editor in case it’s hidden
Get the search text the user entered
Loop through each note selector and show or hide it based on whether or not the note’s body (in the DOM data-body attribute) matches the user’s search text
Select a new note if necessary

The code to accomplish this is as follows:

$(".toolbar-search").on("input propertychange", function () {
  $(".note-editor").show();
  var searchNoteText = $(this).val();
  $(".note-selector").each(function () {
    var $note = $(this);
    if ($note.data().body.toLowerCase().indexOf(searchNoteText.toLowerCase()) === -1) {
      $note.hide();
      if ($note.hasClass("active")) {
        $note.removeClass("active");
      }
    } else {
      $note.show();
    }
  });
  domSelectDefaultChild();
});

You can see the final working example in all its glory here.

Conclusion #

I’ve noted in a couple of places where the jQuery code is starting to get hard to manage. Still, I would consider this app to be reasonably simple, so jQuery works well enough here, especially if you’re diligent about extracting reusable functions. There’s a certain beauty to jQuery where the code closely matches what you’re trying to accomplish in terms of DOM manipulation. However, it does get harder and harder to keep track of how the code is working as you add more features.

The approaches I’ve taken here certainly don’t represent the best or only way to implement these features. You may be able to better organize the code using advanced features like mutation observers, modules, etc. jQuery is unopinionated and allows you to come up with your own patterns to organize your code. But at that point, you may want to look at frameworks which have already established a set of patterns to make it easier to create new apps. In the next part of this series, we’ll take a look at building the same set of features from scratch using the Vue.js framework. Stay tuned!

Comparing Frontend Approaches Part 1: Introduction

2017-09-15T00:00:00Z

In the book The Pragmatic Programmer, David Thomas and Andrew Hunt make the following recommendation:

Learn at least one new language every year. Different languages solve the same problems in different ways. By learning several different approaches, you can help broaden your thinking and avoid getting struck in a rut.

While I don’t think that advice applies directly to learning a new frontend framework each year, it’s still worthwhile to try to understand the fundamental approaches different frameworks are taking to solve the same problem. We’ve recently seen tremendous progress in the frontend space due to frameworks influencing each other, from React’s virtual DOM, Ember’s CLI, and The Elm Architecture, just to name a few.

So to understand the ways different frontend approaches solve the same problem, I’m going to be walking through building the same app with 5 different libraries and frameworks. The application I will be making is a simple web-based clone of the default Mac Notes app, which is a nice target for a couple of reasons:

The app already exists, so the features are fully specified
The app is pretty simple in scope, so it’s not too time consuming to build
The app has some nice reactive features, which requires non-trivial JavaScript

(This is similar to the TodoMVC project, which implements a basic todo app with different frameworks. The notes app is a bit more dynamic, but still pretty similar in scope. The key difference is that I’m going to be explaining every step as I build each app from scratch in the same order, so you can understand each approach without having to learn the entire framework up front).

Here is a quick look at what the desktop Mac Notes app looks like to give you a sense of some of the reactive features. Note how the app is reacting immediately in various places as you type:

I generally implement the following features in my web-based clone of the Mac Notes app in this order:

Store notes as an array of objects (a note has an id, body, & timestamp)
Display note titles on the left, sorted with newest on top (note titles are computed based on the note body)
Select a note on title click, which highlights the selected note on the left and displays the selected note body on the right
Edit the selected note on input, which automatically updates the title and timestamp on the left
Create a new note with a button, with an empty body and current timestamp
Delete the selected note with a button, which updates the left notes list
Filter notes on search input, which automatically updates the list of notes as you type each character

The clone app starts off with the same HTML and CSS template (no JavaScript yet), which you can see below (click on the Result tab):

Some notes about this starting template:

There is some placeholder HTML content which will be replaced with dynamically generated JavaScript content.
I added a lot of classes to the HTML to make it easier to style and manipulate the DOM. Most JavaScript frameworks don’t utilize direct DOM manipulation, but it’s there just in case.
I’m using CSS flexbox for the application layout. I’m not a flexbox guru (pretty much learned what I needed from Flexbox Froggy and Solved by Flexbox), so there may be a more graceful way to handle the CSS layout!

In this series I will be building the same notes app with the following frontend approaches — jQuery, Vue.js, Vue.js with components, React, and Elm. This was chosen roughly in order of easier to learn but complex to maintain (jQuery) to simple to maintain but harder to learn (Elm). Stay tuned!

Sending POST requests in Rails 5.1 without jQuery

2017-08-15T00:00:00Z

Since the jQuery library was removed as a hard dependency in Rails 5.1, it’s a little harder to send AJAX requests from JavaScript. jQuery made it easy for a couple of reasons. One, it provided helper functions like $.get, $.post, and the more general$.ajax. Two, it automatically included the CSRF token in the header of the request. Without the CSRF token that Rails generates, Rails will by default reject any non-GET requests, even for same-origin requests.

Despite not having jQuery, Rails 5.1 actually does provide a way to send AJAX requests! Rails was able to drop the jQuery dependency simply by writing their own helper functions in vanilla JavaScript. These helpers are included in every new Rails app as rails-ujs (you can see the source here). This gives your JavaScript access to an object called Rails (as opposed to $). One of the helpers is Rails.ajax, which is very similar to jQuery’s $.ajax. Here is an example of a GET request:

Rails.ajax({
  url: "/api/v1/people.json",
  type: "GET",
  success: function (data) {
    console.log(data);
  },
});

Easy enough, especially if you’re familiar with jQuery. (Note that this isn’t a 100% compatible drop in replacement for $.ajax, it was simply written to resemble the API of $.ajax). Here is an example of a POST request:

Rails.ajax({
  url: "/api/v1/people.json",
  type: "POST",
  data: "first_name=Ricky&last_name=Bobby",
  success: function (data) {
    console.log(data);
  },
});

Two things to note about this POST request. One, it’s automatically sending the CSRF token, which means the request will go through without any additional configuration (nice!). Two, the data must be formatted as string form parameters, you can’t give it a JavaScript object, at least at the time of this writing with Rails 5.1.3 (not so nice!). Note that it should be trivial to set the "Content-Type" of the request to "application/json", which would allow you to send a stringified JavaScript object, but it doesn’t seem to be possible with the way rails-ujs is written as of now.

If not being able to send POST data as JSON is a deal breaker, you can instead use other approaches like the new fetch API. In that case, you would be responsible for finding the CSRF token in the DOM and sending it with the request headers. There’s actually a helper function in rails-ujs that can grab the CSRF token — Rails.csrfToken(). Here’s the same POST request using the fetch API instead:

fetch("/api/v1/people.json", {
  method: "post",
  body: JSON.stringify({
    first_name: "Ricky",
    last_name: "Bobby",
  }),
  headers: {
    "Content-Type": "application/json",
    "X-CSRF-Token": Rails.csrfToken(),
  },
  credentials: "same-origin",
})
  .then(function (response) {
    return response.json();
  })
  .then(function (data) {
    console.log(data);
  });

The advantage to this approach is that you can send POST data using any format you want, whether it’s JSON or string form parameters. The disadvantage is that fetch isn’t 100% compatible with every browser yet, and it’s a little harder for beginners to understand. In either case, be sure to take advantage of the rails-ujs helper functions in your JavaScript to send AJAX requests with ease!

A Functional Canvas Approach With Redux: Part 2

2017-07-27T00:00:00Z

Using the three fundamental principles of Redux #

Translating With The Low Level Canvas API #

In part 1, we examined a low level, object oriented, and functional approach to drawing using HTML Canvas. Now let’s add some more interactivity to our drawing by responding to mouse events. To start with something basic, let’s translate the whole canvas by 5px each time the user clicks down on the mouse. Let’s see what this looks like using the low level Canvas API (live demo here):

var canvas = document.querySelector("canvas");
var ctx = canvas.getContext("2d");
ctx.fillStyle = "red";
ctx.fillRect(10, 10, 50, 50);
ctx.fillStyle = "blue";
ctx.fillRect(30, 30, 50, 50);

var canvasX = 0;
canvas.addEventListener('mousedown', function(event) {
  canvasX += 5;
  ctx.setTransform(1, 0, 0, 1, 0, 0);
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setTransform(1, 0, 0, 1, canvasX, 0);
  ctx.fillStyle = "red";
  ctx.fillRect(10, 10, 50, 50);
  ctx.fillStyle = "blue";
  ctx.fillRect(30, 30, 50, 50);
}, false);

In this example, we first draw a red and blue rectangle. Then we’re using the canvasX variable to keep track of the horizontal position of the canvas, and we’re adding an event listener to run some code any time the user clicks on the canvas. Each time the mouse is clicked, we add 5 to the canvasX variable.

There is no actual way to translate the objects on the canvas, since they aren’t objects, but simply pixels on the screen. To create the translate effect, we have to erase the canvas, then translate the canvas before drawing the items:

ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.setTransform(1, 0, 0, 1, canvasX, 0);

The setTransform function defines a mathematical matrix transformation with 6 arguments — scale x, skew x, skew y, scale y, translate x, and translate y. This may sound confusing, but it simply means you can control the scale, skew, and translation of the canvas using this function. The first line resets the canvas to the default (an x and y scale of 1, a skew of 0, and a translation to 0, 0). The second line clears the canvas. The third line moves the canvas over to the x position defined by canvasX. Any subsequent drawing commands will now be translated accordingly!

Note that the example code is not DRY, since we’re duplicating the drawing code each time we’re updating the canvas. Let’s move the drawing code into its own method called draw. Let’s also implement a more fully featured draggable canvas, where the canvas drags with the mouse while holding it down (live demo here):

var canvas = document.querySelector("canvas");
var ctx = canvas.getContext("2d");
var canvasX = 0, canvasY = 0;
var xDragging = null, yDragging = null;

var draw = function() {
  ctx.setTransform(1, 0, 0, 1, 0, 0);
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setTransform(1, 0, 0, 1, canvasX, canvasY);
  ctx.fillStyle = "red";
  ctx.fillRect(10, 10, 50, 50);
  ctx.fillStyle = "blue";
  ctx.fillRect(30, 30, 50, 50);
};

canvas.addEventListener('mousedown', function(event) {
  xDragging = event.offsetX;
  yDragging = event.offsetY;
}, false);

canvas.addEventListener('mousemove', function(event) {
  if (xDragging !== null && yDragging !== null) {
    canvasX += event.offsetX - xDragging;
    canvasY += event.offsetY - yDragging;
    draw();
    xDragging = event.offsetX;
    yDragging = event.offsetY;
  }
}, false);

canvas.addEventListener('mouseup', function(event) {
  xDragging = null;
  yDragging = null;
}, false);

draw();

The result looks like:

Here we’re using three event listeners. On mousedown, we store the user’s mouse position. On mousemove, we update the canvasX and canvasY variables based on the change in mouse position, redraw the canvas based on those updated values, and update the stored mouse position. On mouseup, we clear the stored mouse position (so we can determine whether or not the mouse is down).

At this point, the code isn’t too bad, but it’s easy to see that it can get out of hand — we are introducing more stray variables that can be mutated anywhere in the code. As we mentioned in the introduction, one way to organize the application state is to use an object oriented approach, which is what many Canvas libraries do. In our case, we’re going to look at a functional approach using Redux.

Translating With A Functional Redux Approach #

Instead of using object oriented principles, we can instead use functional principles with the Redux library. Instead of separating state into multiple instances of objects, we can keep the state in a single state object. We then can use pure functions to modify the state object. The Redux documentation refers to this design as the three fundamental principles of Redux, which we will implement in our canvas example one step at a time.

The first principle is Single source of truth, which in our case we can accomplish by defining all our application state in a single object. This is a pure data representation of what we will render to the screen. The goal here is to completely decouple this state data from the rest of the code.

var initialState = {
  canvas: { x: 0, y: 0 },
  items: [
    { x: 10, y: 10, width: 50, height: 50, color: "red" },
    { x: 30, y: 30, width: 50, height: 50, color: "blue" },
  ],
  xDragging: null,
  yDragging: null,
};

The second principle is State is read-only, which we can accomplish by dispatching actions in the canvas mousedown, mousemove, and mouseup events. Any time the state needs to change, instead of mutating it directly, we send an action describing what happened. The action is simply a plain data object with a type to identify the action and any other data pertinent to that action. (Note we haven't defined the store variable yet - it's the part of Redux that enables you to dispatch actions, which we will define momentarily).

canvas.addEventListener('mousedown', function(event) {
  store.dispatch({
    type: 'TRANSLATE_CANVAS_START',
    xDragging: event.offsetX,
    yDragging: event.offsetY
  });
}, false);

canvas.addEventListener('mousemove', function(event) {
  var state = store.getState();
  if (state.xDragging !== null && state.yDragging !== null) {
    store.dispatch({
      type: 'TRANSLATE_CANVAS',
      xDragging: event.offsetX,
      yDragging: event.offsetY
    });
  }
}, false);

canvas.addEventListener('mouseup', function(event) {
  store.dispatch({
    type: 'TRANSLATE_CANVAS_END'
  });
}, false);

The third principle is Changes are made with pure functions, which you can see in the reducer function. The reducer function gets called each time an action is dispatched. It is considered a “pure” function because it does not mutate any variables — instead of making changes directly to the given state, it returns a new copy of the state with appropriate modifications. The reducer function takes in the current state object and the action object, and outputs a new state object based on the action. Note that it returns the initialState defined earlier if no state is provided, which happens when it is first called up.

var reducer = function (state, action) {
  if (typeof state === "undefined") {
    return initialState;
  }
  switch (action.type) {
    case "TRANSLATE_CANVAS_START":
      return {
        canvas: state.canvas,
        items: state.items,
        xDragging: action.xDragging,
        yDragging: action.yDragging,
      };
    case "TRANSLATE_CANVAS":
      return {
        canvas: {
          x: state.canvas.x + action.xDragging - state.xDragging,
          y: state.canvas.y + action.yDragging - state.yDragging,
        },
        items: state.items,
        xDragging: action.xDragging,
        yDragging: action.yDragging,
      };
    case "TRANSLATE_CANVAS_END":
      return {
        canvas: state.canvas,
        items: state.items,
        xDragging: null,
        yDragging: null,
      };
    default:
      return state;
  }
};

All that’s left is to wire everything up together, which is done with the code below. The createStore function creates the Redux store using the reducer function we defined. The subscribe function tells Redux to call up the given draw function each time the store changes due to some action.

var store = Redux.createStore(reducer);
store.subscribe(draw);

The draw function is similar to the one we had before. The draw function gets the current Redux state and renders the desired output to the screen. Note that this is the only part of our code which refers to the ctx canvas rendering context. The rendering code has been completely isolated into this draw function. Every other line of code is only responsible for managing the state data and how it transforms. This separation of concerns is the key to making the code easier to maintain.

var canvas = document.querySelector("canvas");
var ctx = canvas.getContext("2d");

var draw = function () {
  var state = store.getState();
  ctx.setTransform(1, 0, 0, 1, 0, 0);
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setTransform(1, 0, 0, 1, state.canvas.x, state.canvas.y);
  state.items.forEach(function (item) {
    ctx.fillStyle = item.color;
    ctx.fillRect(item.x, item.y, item.width, item.height);
  });
};

You can check out the complete Redux implementation with a live demo here.

Let’s walk through an example of how Redux responds to an action. Say the app first starts up, so the state is equal to the initialState variable. If the user clicks on the canvas at the position (10, 30), the following code gets triggered:

canvas.addEventListener('mousedown', function(event) {
  store.dispatch({
    type: 'TRANSLATE_CANVAS_START',
    xDragging: event.offsetX,
    yDragging: event.offsetY
  });
}, false);

The store.dispatch function triggers the reducer function to be called up with the following arguments:

var reducer = function (state, action) {
  // state => initialState
  // action => { type: 'TRANSLATE_CANVAS_START', xDragging: 10, yDragging: 30 }
};

Walking through the reducer function code, you’ll hit the 'TRANSLATE_CANVAS_START' case and return the following state:

return {
  canvas: state.canvas,
  items: state.items,
  xDragging: action.xDragging,
  yDragging: action.yDragging,
};

This is a copy of the original state with updated xDragging and yDragging values using the values given by the action object. Once the reducer returns this state, the Redux state is updated, which in turn triggers the draw function and updates the view. As the user drags the mouse, additional actions will be dispatched, triggering the reducer and draw functions accordingly.

Adding Features With Redux #

Redux may be more difficult to wire together and understand initially, but this clear separation of data and rendering code makes it easier to add new features over time. Note that the code no longer has stray variables that can be mutated anywhere — all the relevant data is stored in the Redux state, and the only way it can be changed is by dispatching a Redux action. Let’s add another feature to our Redux example — translating individual items. The final result will look like:

Let’s take a look at the changes needed to make this feature work. First, the shape of the state changed to include ids for each item, which we use to keep track of which item is being dragged with draggingItemId. Initially no item is being dragged, so draggingItemId is set to null.

var initialState = {
  canvas: { x: 0, y: 0 },
  items: [
    { id: 1, x: 10, y: 10, width: 50, height: 50, color: "red" },
    { id: 2, x: 30, y: 30, width: 50, height: 50, color: "blue" },
  ],
  xDragging: null,
  yDragging: null,
  draggingItemId: null,
};

Now in our reducer function, we have 3 new actions — TRANSLATE_ITEM_START, TRANSLATE_ITEM, and TRANSLATE_ITEM_END. For TRANSLATE_ITEM_START, we are returning a copy of the state with the updated mouse position as well as which item was selected. Note that the reducer isn’t responsible for determining which item was selected — that code is defined elsewhere. The reducer is only responsible for creating a copy of the state with updated values.

    case 'TRANSLATE_ITEM_START':
      return {
        canvas: state.canvas,
        items: state.items,
        xDragging: action.xDragging,
        yDragging: action.yDragging,
        draggingItemId: action.id
      };

For TRANSLATE_ITEM, we are updating the x and y values of the item currently being dragged. Note that we’re taking great care not to mutate the state, but rather to return a brand new copy of every part of the state. There are ways to simplify this code, but for now we’ll leave it as explicit as possible. To update the item’s x and y values without mutation, we create a new copy of the items called newItems using JavaScript’s map array function. Once we create the newItems, we return the copy of the state, which has updated items, xDragging, and yDragging values.

    case 'TRANSLATE_ITEM':
      var newItems = state.items.map(function(item) {
        if (item.id === state.draggingItemId) {
          return {
            id: item.id,
            x: item.x + action.xDragging - state.xDragging,
            y: item.y + action.yDragging - state.yDragging,
            width: item.width,
            height: item.height,
            color: item.color
          };
        } else {
          return item;
        }
      });

For TRANSLATE_ITEM_END, we are returning a copy of the state with the mouse position and the selected item id set to null.

    case 'TRANSLATE_ITEM_END':
      return {
        canvas: state.canvas,
        items: state.items,
        xDragging: null,
        yDragging: null,
        draggingItemId: null
      };

Finally, we have our modified event listener code which determines whether the canvas or an individual item is being dragged. On mousedown, we loop through the items in reverse order to see if an item is clicked on. To do this we can use the isPointInPath function that is part of the Canvas context. This function works by first drawing a virtual path (with the beginPath and rect functions). Once a path is drawn, the isPointInPath function can be called with an x and y coordinate, and will return true if the point is in the path. If it is, we dispatch a TRANSLATE_ITEM_START action. If not, we dispatch a TRANSLATE_CANVAS_START action.

canvas.addEventListener('mousedown', function(event) {
  var state = store.getState();
  for (var i = state.items.length - 1; i >= 0; i--) {
    var item = state.items[i];
    ctx.beginPath();
    ctx.rect(item.x, item.y, item.width, item.height);
    if (ctx.isPointInPath(event.offsetX, event.offsetY)) {
      store.dispatch({
        type: 'TRANSLATE_ITEM_START',
        id: item.id,
        xDragging: event.offsetX,
        yDragging: event.offsetY
      });
      return;
    }
  }
  store.dispatch({
    type: 'TRANSLATE_CANVAS_START',
    xDragging: event.offsetX,
    yDragging: event.offsetY
  });
}, false);

On mousemove, we can examine the state to see if an item is currently being dragged (using the draggingItemId value) or if the canvas is currently being dragged (using the xDragging and yDragging values). If something is being dragged, we dispatch the TRANSLATE_ITEM or TRANSLATE_CANVAS action accordingly.

canvas.addEventListener('mousemove', function(event) {
  var state = store.getState();
  if (state.draggingItemId !== null) {
    store.dispatch({
      type: 'TRANSLATE_ITEM',
      xDragging: event.offsetX,
      yDragging: event.offsetY
    });
  } else if (state.xDragging !== null && state.yDragging !== null) {
    store.dispatch({
      type: 'TRANSLATE_CANVAS',
      xDragging: event.offsetX,
      yDragging: event.offsetY
    });
  }
}, false);

On mouseup, we dispatch a TRANSLATE_ITEM_END or TRANSLATE_CANVAS_END action depending on which was being dragged. Note that these could be combined into a single TRANSLATE_END action since they’re so similar, but we’ll keep them separate for the sake of clarity for now.

canvas.addEventListener('mouseup', function(event) {
  var state = store.getState();
  if (state.draggingItemId !== null) {
    store.dispatch({
      type: 'TRANSLATE_ITEM_END'
    });
  } else {
    store.dispatch({
      type: 'TRANSLATE_CANVAS_END'
    });
  }
}, false);

You can check out the complete live demo here.

Although adding new features with Redux may seem awkward at first, it is very worthwhile because forces you to maintain a separation of concerns. Once you get used to it, it becomes easy to add new features — since everything has an appropriate place, there’s fewer decisions that need to be made from a code design perspective. Although JavaScript is not a purely functional language, we can use functional approaches with Redux to avoiding mutation, which makes the code easier to maintain.

A Functional Canvas Approach With Redux: Part 1

2017-07-27T00:00:00Z

Examining low level, object oriented, and functional drawing techniques #

peterxjang.com

The Low Level HTML Canvas API #

HTML Canvas provides a built in way to create 2D drawings and animations on a web page using JavaScript. The API (introduced in 2005) is a fairly low level drawing API — you can draw a rectangle, but as soon as it’s painted on the screen, it’s forgotten. Canvas doesn’t keep track of the concept of a “rectangle object” — if you want to move the rectangle, you have to erase the entire screen and draw a new one. Here’s an example of how to draw a rectangle:

<!DOCTYPE html>
<head>
  <meta charset="UTF-8">
  <title>Canvas example</title>
</head>
<body>
  <canvas></canvas>
  <script>
    // Get the canvas element
    var canvas = document.querySelector('canvas');

    // Get the drawing context
    var ctx = canvas.getContext('2d');

    // Set the drawing color
    ctx.fillStyle = 'red';

    // Draw a rectangle
    ctx.fillRect(10, 10, 50, 50);

  </script>
</body>
</html>

In this basic example, the <canvas> tag defines the drawing area, and the actual drawing is done by JavaScript in the <script> tag underneath. Here’s the additional code necessary to “move” the rectangle by 20px to the right after 1 second passes:

setTimeout(function () {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.fillRect(10 + 20, 10, 50, 50);
}, 1000);

To move the rectangle, Canvas requires you to first clear the whole drawing area with ctx.clearRect , then redraw the rectangle with ctx.fillRect . It’s your job to keep track of all of the variables, such as the rectangle’s x, y, width, height, and color. This gets very hard to manage when you have many objects on the screen that need to be drawn.

A High Level Object Oriented Approach #

Many people developed libraries to make it easier to use Canvas over the years — EaselJS, Fabric.js, Paper.js, to name a few. All of these libraries take an object oriented approach to managing state — instead of drawing a rectangle, you create a rectangle object, which remembers its own properties. This is a completely intuitive approach, and an example where the object oriented paradigm fits well. Here’s an example of drawing and moving the same rectangle using an object oriented approach with Fabric.js:

<!DOCTYPE html>
<head>
  <meta charset="UTF-8">
  <title>Canvas example</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/1.7.17/fabric.min.js"></script>
</head>
<body>
  <canvas id="c"></canvas>
  <script>
    // create a canvas wrapper
    var canvas = new fabric.Canvas('c');

    // create a rectangle object
    var rect = new fabric.Rect({
      left: 10,
      top: 10,
      width: 50,
      height: 50,
      fill: 'red'
    });

    // "add" rectangle onto canvas
    canvas.add(rect);

    // "Move" the rectangle
    setTimeout(function() {
      rect.set({ left: rect.left + 20 });
      canvas.renderAll();
    }, 1000);

  </script>
</body>
</html>

This is pretty similar to Canvas’ low level approach, but having state managed by objects is helpful, particularly when there’s lots of drawing going on. If you look at the line of code required to move the rectangle…

rect.set({ left: rect.left + 20 });

…you can see that the rect remembers all its own properties — the only thing you need to modify is the left position property. Each object is responsible for keeping track of its own state, which is more organized than the low level approach.

However, there are potential downsides to an object oriented approach. Because state is encapsulated in each object, it can be difficult to see where values are coming from and how they are changing when there are multiple objects that interact with each other. This may be less of an issue when using Canvas for decorative drawings and more of an issue when using Canvas for user interfaces with complex interactions.

A High Level Functional Approach #

Instead of using an object oriented approach, we can create a higher level drawing abstraction using functional techniques. I’ll be using an approach very similar to React with Redux — in a nutshell, you keep all your state in a single object, and any time the state object changes, you redraw your entire screen. Redux manages the state, React manages the view. Note that React has a “diffing” algorithm to make the redraw step as efficient as possible. I’ll be replacing React with Canvas as the view layer, which works perfectly since Canvas is designed to efficiently redraw the entire screen at each step.

So for this approach, the dependencies are Canvas (built into the browser) and Redux. In a nutshell, Redux keeps all state in a single object which contains all the necessary information to render a view. To change the state, you must dispatch an action, which is an object that describes what happened. When an action is dispatched, the state is updated using a reducer function, and the view layer (in our case Canvas) will be redrawn.

Note that this won’t be a beginner focused tutorial on Redux — if you aren’t familiar with Redux, there are many fantastic tutorials to get you started. (I highly, highly recommend the egghead.io videos by Dan Abramov, the author of Redux. He demonstrates piece by piece how to create the entire Redux library from scratch, and has a true gift for explaining things with simplicity).

Here’s how the same example of drawing and moving a rectangle looks using Canvas with Redux:

<!DOCTYPE html>
<head>
  <meta charset="UTF-8">
  <title>Canvas example</title>
  <script src="https://unpkg.com/redux@latest/dist/redux.min.js"></script>
</head>
<body>
  <canvas></canvas>
  <script>
    // Get the canvas element
    var canvas = document.querySelector('canvas');

    // Get the drawing context
    var ctx = canvas.getContext('2d');

    // Define the initial state
    var initialState = {
      rectangles: [
        {
          x: 10,
          y: 10,
          width: 50,
          height: 50,
          color: 'red'
        }
      ]
    };

    // Define how state changes
    function reducer(state, action) {
      switch (action.type) {
      case 'TRANSLATE':
        return {
          rectangles: state.rectangles.map(function(rect) {
            return {
              x: rect.x + action.x,
              y: rect.y + action.y,
              width: rect.width,
              height: rect.height,
              color: rect.color
            };
          })
        };
      default:
        return state;
      }
    }

    // Define how state is viewed
    function render() {
      ctx.clearRect(0, 0, canvas.width, canvas.height);
      var state = store.getState();
      state.rectangles.forEach(function(rect) {
        ctx.fillStyle = rect.color;
        ctx.fillRect(rect.x, rect.y, rect.width, rect.height);
      });
    }

    // Create the Redux store
    // (to manage state changes)
    var store = Redux.createStore(reducer, initialState);
    store.subscribe(function() {
      render();
    });

    // Draw the initial view
    render();

    // "Move" the rectangle
    setTimeout(function() {
      store.dispatch({type: 'TRANSLATE', x: 20, y: 0});
    }, 1000);

</script>
</body>
</html>

This functional approach is a lot more code than the low level and object oriented approaches! But this is the up-front cost — it’s harder to set up in the beginning because we’re creating a rigid structure for every new piece of code to live. As we add more features, there ends up being considerably less code compared to the low level and object oriented approaches.

I used this approach to make my personal homepage (peterxjang.com), where the entire interface is a Canvas surface with panning/zooming interactions (using either a mouse or touch interface). The only external dependency used is Redux (2kB). I was able to get the entire HTML/CSS/JS to fit under 14 kB, which means it renders the initial paint blazingly fast (a single round trip), even on slower mobile connections.

Some secret features on my homepage — you can double click the background or parent items to zoom-to-fit. You can long press any item, which allows you to move and resize each item. You can also long press the background, which gives you options to save your layout changes (in local storage). Again, all these interactions were coded with a total initial page size under 14kB (I implemented image and content lazy loading to keep the first paint as fast as possible).

Not only is the code light weight, but it’s easy to reason about. All the application state is contained in a single state object, which means anyone can look at that single object to understand the data that affects the view. The only way for the state to change is by dispatching actions, which forces you to define all interactions in terms of action objects. Anyone can look at all the actions defined to understand the complete set of ways you can interact with the application. Instead of encapsulating state and behavior in an object oriented approach, everything is laid bare in a functional approach.

In the next part of the series, we’ll continue using using this functional approach to implement user interactions (panning and zooming).

Part 2: Using the 3 fundamental principles of Redux

Web Development On An iPad

2017-05-03T00:00:00Z

iPad Pro with Smart Keyboard — good enough for web development?

Apple has always tried to market the iPad Pro as a laptop replacement. This might work out for college students or people in certain professions where the available iOS apps cover their daily needs. However, as a web developer, there are too many command line tools that are necessary on a day-to-day basis that makes it infeasible for an iPad by itself to be a complete laptop replacement.

However, you can combine an iPad with a VPS (Virtual Private Server) to have access to the best of both worlds. In essence, a VPS is a remote computer where you have full access to an Linux system. You can install all the web development tools you normally use on your laptop or desktop. Then you use your iPad to SSH into your VPS, giving you full access to your remote system through the terminal.

Think about what this means — an iPad can never be a fully fledged laptop replacement, but with a VPS it doesn’t have to be! Let the iPad be the iPad, and your VPS will be the remote computer that handles everything else. Services like DigitalOcean and Linode offer a VPS for $5/month, so it’s very affordable to get started!

This isn’t a unique idea — some people have been using this setup for years, and there are several good write-ups about it. This post will cover the tools and tips that I have found useful for my specific workflow.

What you’ll need #

An iPad (I use a 12.9" iPad Pro)
A compatible keyboard (I use the iPad Pro Smart Keyboard)
A Virtual Private Server (I use DigitalOcean’s $5/month plan)
An iOS terminal app (I use Blink)
An iOS text editor (I don’t use one, I use Vim instead)

Step 1: Get your VPS up and running #

Your VPS is your remote system where you’ll install all your familiar web development tools — your programming language (ruby, node, etc.), your database (postgres, mysql, etc.), your version control (git, mecurial, etc.). Generally you’ll set up a VPS using Ubuntu without a graphical operating system — everything is installed using a command line. This may seem a bit daunting if you’re only familiar with Mac or Windows computers. However, if you’ve been doing web development for a while, you are already more than familiar with installing applications through a command line.

I use DigitalOcean, which has fantastic tutorials that walk you through every step of the process. To get started with DigitalOcean, sign up for a plan, then follow the steps in this tutorial: Initial Server Setup with Ubuntu 16.04. Again, it can be a bit daunting for first time Linux users, but the instructions are clear and the content is definitely worth learning. By the time you’re done, you’ll have your very own remote box which you can log into from any computer connected to the internet!

TIP: DigitalOcean provides a web-based terminal to log into your remote server. I found it to be painfully slow — it’s useful to first get started, but switch to your terminal of choice to ssh into your remote box as soon as you get a chance!

Step 2: Install software on your VPS #

Once you have a basic VPS set up, you’ll need to install your web development tools. Here are some helpful guides from DigitalOcean to get you started:

There are many more well-written tutorials from DigitalOcean to help you install pretty much anything you can think of. Note that at this point you have a fully functional Ubuntu Linux machine, so any installation instructions that work with Ubuntu will work for your VPS, there’s nothing really specific to DigitalOcean at this point.

Step 3: Set up your iPad terminal #

To access your VPS using an iPad, you’ll need an iOS app that has SSH capabilities. My app of choice is Blink — it costs $20, but it’s completely open source and provides instructions so you can build it yourself using XCode! Blink uses Mosh, an SSH replacement that is built to work with unstable and intermittent connectivity (Blink works with regular SSH as well). Perhaps the most important feature to me — Blink let’s you remap the Caps Lock key on your iPad keyboard to Control (or whatever you want). A small detail but hugely important to my workflow!

Once you have an iOS terminal app installed, you can SSH into your VPS as you would on any computer. For example, if you set up a username of bob on your VPS, and your VPS IP address was 192.168.10.1, then you can run in your iPad terminal:

ssh bob@192.168.10.1

If you’re using Blink, you can use mosh instead:

mosh bob@192.168.10.1

Now you have full terminal access to your remote computer on your iPad!

TIP: If you own a domain, you can configure your VPS IP address to point to that domain or a subdomain (the instructions depends on your domain provider). So if you own the domain mycoolsite.com, you can point your 192.168.10.1 IP address to a subdomain like dev.mycoolsite.com. This allows you do ssh or mosh into your VPS using ssh bob@dev.mycoolsite.com.

Step 4: Set up your iPad text editor #

At this point you’ll need a text editor to do any actual programming. But it can’t be any iOS text editor — it must be able to edit remote files on your VPS. The most feature rich editor I found was Coda for iOS — syntax highlighting, tabs, built-in terminal, you name it. Other interesting alternatives are apps that connect to GitHub, like Working Copy or Git2Go. These apps work as GitHub clients, but also come with text editors to edit files directly as well.

However, I don’t use any of these apps — instead, I use Vim installed on my VPS. If you’re not familiar with Vim, this may seem like a strange choice, and you can definitely go with one of the above options instead. But if you are already comfortable with Vim or willing to learn it, then you get the benefit of having a world-class editing experience on your iPad instead of one that will inevitably be limited compared to your regular text editor of choice.

Step 5: Handle miscellaneous issues #

At this point you have a complete iPad development machine, with full terminal access to a remote Linux computer and a full programming text editor! Anything you could do on your laptop you can now do on your iPad! Well, almost — there are a couple of gotchas that we have to take care of…

Use multiple terminal tabs #

Usually as a web developer you will have multiple terminal tabs open. However, when you use your iOS terminal to ssh into your remote server, opening a new tab doesn’t open a new ssh connection. There are different workarounds for this — the one I recommend using is tmux. If you aren’t familiar with tmux, it basically allows you to have multiple terminal sessions within a single terminal window. It also has the benefit of saving a session even when you log off, which means you can sleep or turn off your iPad and still maintain the terminal processes on your remote server.

Run a development web server #

You can easily run a development server on your VPS localhost, but it won’t be accessible on your iPad. The solution is to bind your development web server to your VPS IP address instead of localhost.

If you’re using rails, you can bind the dev server to your VPS IP address (here we’re using 192.168.10.1 as an example) on port 3000 like this:

rails server -b 192.168.10.1 -p 3000

If you’re using Node, you can set the HOST to the VPS IP address to accomplish the same thing. For example, if you were running webpack-dev-server, you can run the command:

HOST=192.168.10.1 PORT=3000 webpack-dev-server --hot --inline

Now on your iPad, you can see your development site by opening up any browser and going to http://192.168.10.1:3000. Sweet!

Access a JavaScript console #

Now that you can see your development application in the browser, the only thing that’s missing is a JavaScript console. Sadly iOS browsers don’t provide the same dev tools as their desktop counterparts, making it very difficult to debug JavaScript issues.

The solution is to use a bookmarklet for Firebug Lite! For those unfamiliar with bookmarklets, they are basically bookmarks with embedded JavaScript — they were what people used before browser extensions came about. Browser extensions don’t exist on iOS, but bookmarklets still work just fine. Follow these instructions to install the Firebug Lite bookmarklet in your iOS browser, and you have access to debugging tools on any website you visit! Not as extensive as Chrome dev tools, but you do get a JavaScript console, which is critical to web development.

Edit: After many years, it looks like Firebug Lite is no longer running as a service! If you’re looking for an alternative, there are iOS apps that provide similar functionality, such as Inspect Browser, Webtools & MIH Tools.

Conclusion #

By following this guide, you can definitely use your iPad as a laptop replacement for web development. There are some weird gotchas, but it honestly covers 95% of your development needs without a hiccup. I still own a Macbook Pro, and I find the iPad Pro to be a great complement to it. When I carry both around, I can use the iPad Pro as a great second monitor (using Duet or Astropad), or do development work on either machine. If I’m going on a trip, I’ll just take the iPad Pro.

If you’re a web developer and already own an iPad with keyboard, this is a no-brainer. Combining an iPad with a VPN will more than double the usefulness of your tablet as a professional (and you’ll learn more about Linux and running remote servers to boot). To me, it’s less about making the iPad replace my laptop and more about maximizing the iPad’s value. Hope you find these tips to be useful!