<![CDATA[Actualize - Medium]]> https://medium.com/actualize-network?source=rss----bac00d3a330d---4 https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png Actualize - Medium https://medium.com/actualize-network?source=rss----bac00d3a330d---4 Medium Wed, 27 May 2026 23:55:06 GMT <![CDATA[Modern HTML Explained For Dinosaurs]]> https://medium.com/actualize-network/modern-html-explained-for-dinosaurs-65e56af2981?source=rss----bac00d3a330d---4 https://medium.com/p/65e56af2981 Wed, 14 Nov 2018 21:35:17 GMT 2018-11-14T21:33:01.054Z

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 (with changes in bold):

<!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 <!-- [if lt IE 9]>...--> 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 the code would look like using Bootstrap (changes in bold):

<!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">
      <section class="jumbotron">
        <h1 class="display-4">Hello there!</h1>
        <p class="lead">General info about the page goes here</p>
        <p><a class="btn btn-primary btn-lg" href="#">Learn more</a></p>
      </section>
      <section class="container">
        <div class="row">
          <article class="col-4">
            <h2>First Heading</h2>
            <p>Article content goes here</p>
            <p><a href="#">View details</a></p>
          </article>
          <article class="col-4">
            <h2>Second Heading</h2>
            <p>Article content goes here</p>
            <p><a href="#">View details</a></p>
          </article>
          <article class="col-4">
            <h2>Third Heading</h2>
            <p>Article content goes here</p>
            <ul class="nav nav-tabs" role="tablist">
              <li class="nav-item">
                <a class="nav-link active" data-toggle="tab" id="windows-tab" href="#windows" role="tab" aria-controls="windows" aria-selected="true">Windows</a>
              </li>
              <li class="nav-item">
                <a class="nav-link" data-toggle="tab" id="mac-tab" href="#mac" role="tab" aria-controls="mac" aria-selected="false">Mac</a>
              </li>
              <li class="nav-item">
                <a class="nav-link" data-toggle="tab" id="linux-tab" href="#linux" role="tab" aria-controls="linux" aria-selected="false">Linux</a>
              </li>
            </ul>
            <div class="tab-content">
              <div class="tab-pane fade show active" id="windows" role="tabpanel" aria-labelledby="windows-tab">
                <img class="img-fluid" src="http://1000logos.net/wp-content/uploads/2017/04/Microsoft-Logo.png" alt="microsoft logo">
                ...
              </div>
              <div class="tab-pane fade" id="mac" role="tabpanel" aria-labelledby="mac-tab">
                <img class="img-fluid" src="https://i.ytimg.com/vi/ipOzBWuYZvg/maxresdefault.jpg" alt="apple logo">
                ...
              </div>
              <div class="tab-pane fade" id="linux" role="tabpanel" aria-labelledby="linux-tab">
                <img class="img-fluid" src="https://noware.tech/wp-content/uploads/sites/140/2018/04/linux-1024x565.jpg" alt="linux logo">
                ...
              </div>
            </div>
            <p><a href="#">View details</a></p>
          </article>
        </div>
      </section>
    </main>
    <footer class="navbar navbar-dark bg-secondary" role="contentinfo">
      <p>Copyright info goes here</p>
    </footer>
  </body>
</html>

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 from our previous Bootstrap example would look like after being analyzed by the critical tool (changes in bold):

<!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 (min-width:576px){.container{max-width:540px}}@media (min-width:768px){.container{max-width:720px}}@media (min-width:992px){.container{max-width:960px}}@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 (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 (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 (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 (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 (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" 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" 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" 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>
    <!--[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">
      <section class="jumbotron">
        <h1 class="display-4">Hello there!</h1>
        <p class="lead">General info about the page goes here</p>
        <p><a class="btn btn-primary btn-lg" href="#">Learn more</a></p>
      </section>
      <section class="container">
        <div class="row">
          <article class="col-4">
            <h2>First Heading</h2>
            <p>Article content goes here</p>
            <p><a href="#">View details</a></p>
          </article>
          <article class="col-4">
            <h2>Second Heading</h2>
            <p>Article content goes here</p>
            <p><a href="#">View details</a></p>
          </article>
          <article class="col-4">
            <h2>Third Heading</h2>
            <p>Article content goes here</p>
            <ul class="nav nav-tabs" role="tablist">
              <li class="nav-item">
                <a class="nav-link active" data-toggle="tab" id="windows-tab" href="#windows" role="tab" aria-controls="windows" aria-selected="true">Windows</a>
              </li>
              <li class="nav-item">
                <a class="nav-link" data-toggle="tab" id="mac-tab" href="#mac" role="tab" aria-controls="mac" aria-selected="false">Mac</a>
              </li>
              <li class="nav-item">
                <a class="nav-link" data-toggle="tab" id="linux-tab" href="#linux" role="tab" aria-controls="linux" aria-selected="false">Linux</a>
              </li>
            </ul>
            <div class="tab-content">
              <div class="tab-pane fade show active" id="windows" role="tabpanel" aria-labelledby="windows-tab">
                <img class="img-fluid" src="http://1000logos.net/wp-content/uploads/2017/04/Microsoft-Logo.png" alt="microsoft logo">
                ...
              </div>
              <div class="tab-pane fade" id="mac" role="tabpanel" aria-labelledby="mac-tab">
                <img class="img-fluid" src="https://i.ytimg.com/vi/ipOzBWuYZvg/maxresdefault.jpg" alt="apple logo">
                ...
              </div>
              <div class="tab-pane fade" id="linux" role="tabpanel" aria-labelledby="linux-tab">
                <img class="img-fluid" src="https://noware.tech/wp-content/uploads/sites/140/2018/04/linux-1024x565.jpg" alt="linux logo">
                ...
              </div>
            </div>
            <p><a href="#">View details</a></p>
          </article>
        </div>
      </section>
    </main>
    <footer class="navbar navbar-dark bg-secondary" role="contentinfo">
      <p>Copyright info goes here</p>
    </footer>
  </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" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
    <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>
    <!--[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">
      <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 in bold. 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!

Modern HTML Explained For Dinosaurs was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Modern CSS Explained For Dinosaurs]]> https://medium.com/actualize-network/modern-css-explained-for-dinosaurs-5226febe3525?source=rss----bac00d3a330d---4 https://medium.com/p/5226febe3525 Sun, 04 Feb 2018 19:03:36 GMT 2020-09-27T01:24:31.437Z
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).

Modern CSS Explained For Dinosaurs was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Comparing Frontend Approaches Part 7: Final Thoughts]]> https://medium.com/actualize-network/comparing-frontend-approaches-part-7-final-thoughts-69cdba516f86?source=rss----bac00d3a330d---4 https://medium.com/p/69cdba516f86 Sat, 13 Jan 2018 23:14:46 GMT 2018-08-29T12:51:26.208Z A look at jQuery, Vue.js, React, and Elm

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 7: Final Thoughts was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Comparing Frontend Approaches Part 6: Elm]]> https://medium.com/actualize-network/comparing-frontend-frameworks-part-6-elm-578714526164?source=rss----bac00d3a330d---4 https://medium.com/p/578714526164 Sat, 13 Jan 2018 23:14:29 GMT 2018-08-29T17:09:48.863Z A look at jQuery, Vue.js, React, and Elm

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 (main)

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. Here’s what the code in Notes.elm looks like, which we will break down in more detail:

module Notes exposing (main)
import Browser
import Html exposing (..)
import Html.Attributes exposing (..)
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 }
            ]
      }
    , Cmd.none
    )
-- UPDATE
type Msg
    = NoOp
update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    ( model, 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
            , 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) ]
        ]

This definitely can be confusing the first time looking at it — let’s break it down in sections. First let’s look at the main function itself:

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

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.

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):

-- MODEL


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


type alias Model =
    { notes : List Note }

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.).

Now let’s take a look at the init function, which initializes the model:

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 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…

The next function is the update function, which defines how the model gets updated:

-- UPDATE


type Msg
    = NoOp


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

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.

The next function is the subscriptions function, which are used to listen to events:

-- SUBSCRIPTIONS


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

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.

The final function is the view function, which defines the HTML output:

-- 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) ]
        ]

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.

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 (main)
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 view function):

module Notes exposing (main)
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
-- ...

-- UPDATE
-- ...

-- SUBSCRIPTIONS
-- ...

-- 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 (main)

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


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 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 (main)

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 6: Elm was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Comparing Frontend Approaches Part 5: React]]> https://medium.com/actualize-network/comparing-frontend-frameworks-part-5-react-b51fd7d075fe?source=rss----bac00d3a330d---4 https://medium.com/p/b51fd7d075fe Sat, 13 Jan 2018 23:14:20 GMT 2019-02-24T19:10:36.071Z A look at jQuery, Vue.js, React, and Elm

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..."></input>
        </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..."></input>
      </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 { } (as opposed to {{ }} 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..."></input>
      </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..."></input>
      </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}></input>
      </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 5: React was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Comparing Frontend Approaches Part 4: Vue.js with Components]]> https://medium.com/actualize-network/comparing-frontend-frameworks-part-4-vue-js-with-components-675c880d4585?source=rss----bac00d3a330d---4 https://medium.com/p/675c880d4585 Sat, 13 Jan 2018 23:14:08 GMT 2019-04-14T13:28:52.011Z A look at jQuery, Vue.js, React, and Elm

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>
└── <note-container>
    ├── <note-selectors>
    │   └── <note-selector>
    │   └── <note-selector>
    │   └── <note-selector>
    └── <note-editor>

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.vue file would now look like:

<template>
  <div id="app">
    <toolbar></toolbar>
    <note-container></note-container>
  </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 <note-container> 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.

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 src/App.vue template and script look like:

<template>
  <div id="app">
    <toolbar></toolbar>
    <note-container v-bind:notes="notes"></note-container>
  </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 <note-container> component with the line:

    <note-container v-bind:notes="notes"></note-container>

Here we’re binding a custom notes attribute to the component, which contains the array of notes defined in the data option. However, the <note-container> 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">
    <note-selectors v-bind:notes="notes"></note-selectors>
    <note-editor></note-editor>
  </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 <note-container> 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 <note-container> component doesn’t deal with the notes directly, so it has to pass it down to the <note-selectors> component, which you see in the template line:

    <note-selectors v-bind:notes="notes"></note-selectors>

Finally, we get to <note-selectors> 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">
    <note-selector
      v-for="note in notes"
      v-bind:note="note"
      v-bind:key="note.id"
    >
    </note-selector>
  </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 <note-selector> 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 <note-selector> 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 <note-selectors> component needs to sort the child<note-selector> components by timestamps. This is what the src/components/NoteSelectors.vue template and script look like:

<template>
  <div class="note-selectors">
    <note-selector
      v-for="note in transformedNotes"
      v-bind:note="note"
      v-bind:key="note.id"
    >
    </note-selector>
  </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 <note-selector> component responsible for title and timestamp formatting, and the <note-selectors> 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></toolbar>
    <note-container
      v-bind:notes="notes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote"
    >
    </note-container>
  </div>
</template>

Here we’re sending a new prop and event to the <note-container> 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 <note-container>. 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 <note-container> component. If the <note-container> 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 <note-container> 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">
    <note-selectors
      v-bind:notes="notes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote">
    </note-selectors>
    <note-editor
      v-bind:selectedNote="selectedNote">
    </note-editor>
  </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 <note-container> component has to pass the selectedNote prop and the selectNote event to the child <note-selector> component. Note that if the <note-selector> 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 <note-container> 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 <note-editor> component, which needs that info as well.

Now let’s take a look at the template and script in the <note-selectors> component in app/components/NoteSelectors.vue, which is what is actually process the click event:

<template>
  <div class="note-selectors">
    <note-selector
      v-for="note in transformedNotes"
      v-bind:note="note"
      v-bind:selectedNote="selectedNote"
      v-bind:key="note.id"
      v-on:click.native="selectNote(note)"
    >
    </note-selector>
  </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 <note-selector> component, triggering the parent <note-selectors> component’s selectNote method, which emits a 'selectNote' event, triggering the parent <note-container> 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 <note-selector> 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 <note-editor> 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 <note-selector> 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 <note-editor> 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 <note-editor> 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 <note-container> 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">
    <note-selectors
      v-bind:notes="notes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote">
    </note-selectors>
    <note-editor
      v-bind:selectedNote="selectedNote"
      v-on:inputNoteEditor="inputNoteEditor">
    </note-editor>
  </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 <note-editor> 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></toolbar>
    <note-container
      v-bind:notes="notes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote"
      v-on:inputNoteEditor="updateSelectedNote"
    >
    </note-container>
  </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 <note-container> 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"></toolbar>
    <note-container
      v-bind:notes="notes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote"
      v-on:inputNoteEditor="updateSelectedNote"
    >
    </note-container>
  </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">
    </toolbar>
    <note-container
      v-bind:notes="notes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote"
      v-on:inputNoteEditor="updateSelectedNote"
    >
    </note-container>
  </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 <note-selectors> 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">
    </toolbar>
    <note-container
      v-bind:notes="notes"
      v-bind:transformedNotes="transformedNotes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote"
      v-on:inputNoteEditor="updateSelectedNote"
    >
    </note-container>
  </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">
    <note-selectors
      v-bind:notes="notes"
      v-bind:transformedNotes="transformedNotes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote">
    </note-selectors>
    <note-editor
      v-bind:selectedNote="selectedNote"
      v-on:inputNoteEditor="inputNoteEditor">
    </note-editor>
  </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">
    <note-selector
      v-for="note in transformedNotes"
      v-bind:note="note"
      v-bind:selectedNote="selectedNote"
      v-bind:key="note.id"
      v-on:click.native="selectNote(note)"
    >
    </note-selector>
  </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>

The last detail is to change the <note-editor> 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.vue would change as follows:

<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"
    >
    </toolbar>
    <note-container
      v-bind:notes="notes"
      v-bind:transformedNotes="transformedNotes"
      v-bind:selectedNote="selectedNote"
      v-on:selectNote="selectNote"
      v-on:inputNoteEditor="updateSelectedNote"
    >
    </note-container>
  </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 4: Vue.js with Components was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Comparing Frontend Approaches Part 3: Vue.js]]> https://medium.com/actualize-network/comparing-frontend-frameworks-part-3-vue-js-8b8614e4f324?source=rss----bac00d3a330d---4 https://medium.com/p/8b8614e4f324 Sat, 13 Jan 2018 23:13:58 GMT 2019-04-09T02:23:58.769Z A look at jQuery, Vue.js, React, and Elm

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 {{ }}, which is capable of referencing data defined in the Vue instance data option.

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">

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!

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!

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.

Here is the final working example in all its glory:

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 3: Vue.js was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Comparing Frontend Approaches Part 2: jQuery]]> https://medium.com/actualize-network/comparing-frontend-frameworks-part-2-jquery-d92abe80ef25?source=rss----bac00d3a330d---4 https://medium.com/p/d92abe80ef25 Sat, 13 Jan 2018 23:13:42 GMT 2018-01-16T05:57:33.423Z A look at jQuery, Vue.js, React, and Elm

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.

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.

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.

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. 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).

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);
}

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

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:

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.

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();
});

Here is the final working example in all its glory:

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 2: jQuery was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[Prototyping with Vue.js and Bootstrap]]> https://medium.com/actualize-network/prototyping-with-vue-js-and-bootstrap-2404efe93d6?source=rss----bac00d3a330d---4 https://medium.com/p/2404efe93d6 Sat, 13 Jan 2018 22:33:16 GMT 2017-12-29T06:17:06.594Z

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">
            {{ currentItem.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">
          {{ currentItem.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!

Prototyping with Vue.js and Bootstrap was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]> <![CDATA[A minimalist guide to tmux]]> https://medium.com/actualize-network/a-minimalist-guide-to-tmux-13675fb160fa?source=rss----bac00d3a330d---4 https://medium.com/p/13675fb160fa Sat, 13 Jan 2018 22:33:02 GMT 2017-12-17T21:01:38.662Z 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!

A minimalist guide to tmux was originally published in Actualize on Medium, where people are continuing the conversation by highlighting and responding to this story.

]]>