{ "version": "https://jsonfeed.org/version/1.1", "title": "falldowngoboone", "language": "en", "home_page_url": "https://www.falldowngoboone.com/", "feed_url": "https://www.falldowngoboone.com/feed/feed.json", "description": "The ramblings of Ryan Boone, a web developer and designer from Texas with a passion for open, accessible front end development.", "author": { "name": "Ryan Boone", "url": "https://www.falldowngoboone.com/" }, "items": [{ "id": "https://www.falldowngoboone.com/blog/year-end-review-2025/", "url": "https://www.falldowngoboone.com/blog/year-end-review-2025/", "title": "Year-end review 2025", "content_html": "

Another year, another review.

\n

It’s the time of the year again where I actually contribute to my blog. 2025 was a roller coaster for me, and I honestly don’t know where to begin.

\n

So I’ll begin with a story.

\n

Joy and Grief

\n

After a lengthy process, my wife and I were delighted to adopt a sweet little chocolate, toy-obsessed bulldog named Kodiak.

\n

It was a bit stressful for the first couple of weeks, but around week three Kodi started to feel like family.

\n

He loved being cradled like a baby and snuggled. He would often lay on his back next to my wife in our recliner, and he would always let us know when he thought we weren’t giving him enough attention with his adorable grunts of discontent.

\n

He filled our home with laughter.

\n

A few weeks after adopting Kodi, on what we thought was a routine teeth cleaning at the vet, we learned that he had an aggressive, terminal illness.

\n

We were devastated.

\n

The vet said he had maybe a week left. Kodi held on for two.

\n

We tried to fit as much as we could into his last days. We celebrated his birthday, we celebrated Christmas in June, and we made sure he was always surrounded by his favorite toys.

\n

The end came all too soon, after his final check up at the vet.

\n

We made sure he was comfortable, then, with tears in our eyes, we held him one last time as he went to sleep on his bed.

\n

We didn’t want to let go.

\n

We only knew Kodi for two months, but in that short time, he made an enormous impact on our family.

\n

We miss him dearly, and will never forget the joy and laughter he gave us. He was such a sweet boy, and we’re glad we were able to give him the best life we possibly could in his final days.

\n

Meanwhile, a much more welcome changes were happening at work.

\n

A New Role

\n

Earlier this year I moved into a new role as a Yum! Staff Engineer.

\n

My primary focus is frontend architecture, which means a lot more drawing diagrams and writing documentation. I’m also continuing my work to improve frontend developer experience, something I’ve become quite passionate about.

\n

My work this year has been all about transitioning a monolithic React application to micro frontends. We’ve been building up to this for a while now by splitting up the existing legacy code into several domain-based vertical slices.

\n

Now, with the help of module federation, we’re stitching those slices together inside a shell application.

\n

The micro frontend implementation was completed earlier this year, and now we’re working on the infrastructure bit. It’s exciting, and a bit stressful, to be building something our company has never built before.

\n

We’ll probably spend the next couple months working out the bugs, but we’re almost to the finish line!

\n

2025 Wrapped

\n

To round out my personal updates, here’s a quick look at what else happened throughout the year.

\n\n

2026 Goals

\n

In 2026, I want to focus personally on continuing what’s working and experimenting with creating new creative habits. Professionally, I am looking at one of my most ambitious years ever.

\n\n

Something I’m doing different this year is setting a calendar reminder to review all of my goals monthly. Hopefully this will keep me focused on what my priorities are, and, if anything changes, I can easily update my goals and note the reason for the change.

\n

Signing Off for Now

\n

2025 was exhausting for me on many levels, but I’m proud of the work I accomplished and thankful for my family, especially my wife, for their love and support. I’m also grateful that I was able to meet the sweetest dog I’ve ever known, even if it was for such a brief time.

\n

I’m taking the last two weeks of this year to rest, reflect and regroup. I hope you are able to do the same. Until next time!

\n", "date_published": "2025-12-26T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/year-end-review-2024/", "url": "https://www.falldowngoboone.com/blog/year-end-review-2024/", "title": "Year-end review 2024", "content_html": "

2024 is wrapping up, and it’s time for me to post my annual year-end review. This year brought its share of challenges and uncertainties globally. Personally, though, I am grateful for what I was able to experience and accomplish.

\n

2024 Goals

\n

Spoiler alert: three out of five were completed successfully. I swear I’ll review these throughout the year one day. Honestly, I think the biggest barrier to accomplishing the goals I set is actually remembering them. As always, I continue to struggle with writing my blog, but I have a plan for that.

\n\n

One thing that continues to roll around in the back of my head is the idea of recording music again. I didn’t make it a goal this year because I knew I wouldn’t have (or make) time for it. I remain hopeful I’ll return to making music but accept that it’s not a priority in my life right now.

\n

Additional highlights

\n

In addition to my personal goals, 2024 presented me with some unique opportunities, as well as things I just want to celebrate.

\n

Starting with the most recent event: My wife recently underwent what we hope will be her last major cancer-related surgery. I know she’s exhausted at this point, but she has met every challenge on this journey head-on. I’m so proud of her and grateful to have her in my life.

\n

Last month, I completed a massive project I began planning in late 2023: I produced and presented an 8-week course on React. The course was a project for work, intended to attract more interest in React development. It was well-received, and I’m excited to share what I learned from the experience.

\n

I continued to work on my personal health as well. I’ve been lifting weights regularly and hit a personal goal of 13% body fat. I’m quite happy with that, especially considering I started the year off with physical therapy due to back and neck pain.

\n

Finally, I mentioned that my wife and I made two trips this year, and the second trip had been years in the making. This year, we finally made our way across the pond to the United Kingdom. We spent a week and a half exploring London, Canterbury, Edinburgh, and Glasgow by train. It was definitely the high point of the year, and we can’t wait to go back.

\n

2025 Goals

\n

For 2025, I want to focus on creating systems around what I want to accomplish, using the principles of Atomic Habits by James Clear. And for fun, I’m using ChatGPT to generate possible strategies for each goal.

\n\n

See you in the New Year

\n

So that was my 2024: a UK trip, a React course, and my wife one more year cancer-free. It was one of the best years I’ve had in a while. Even though there’s a lot of uncertainty about what’s happening in the world, I’m looking forward to 2025. This year, I aim to focus more on the present, and I hope others find the balance that works for them.

\n

Until next time (hopefully not too long from now)!

\n", "date_published": "2024-12-29T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/cracking-the-books/", "url": "https://www.falldowngoboone.com/blog/cracking-the-books/", "title": "Cracking the books", "content_html": "

If you’re like me, you’re 6’2”, have terrible eyesight, and a weird affinity for guitar repair videos. You probably also like to read.

\n

One of my goals this year is to read at least 24 books, and I’m off to a pretty good start. While I’m trying to work more fiction into my reading, I still love a good software engineering book.

\n

So you can imagine how excited I was to come across this gem of a video from Engineering with Utsav. Utsav has put together a small but mighty collection of software engineering books that would make any nerd happy.

\n

I’ve added all of these books to my Notion bookshelf, and I’m looking forward to checking them out!

\n

Video: Books every software engineer should read in 2024 (Youtube)

\n", "date_published": "2024-03-09T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/year-end-review-2023/", "url": "https://www.falldowngoboone.com/blog/year-end-review-2023/", "title": "Year-end review 2023", "content_html": "

The last three years have been…interesting, but I finally feel like my life is getting back to some sense of normal. 2023 was my first full year as a tech lead, and I have noticed a definite change in my day-to-day activities. My wife and I also celebrated an important milestone that I’m grateful to share. With that in mind, here’s the obligatory look back on my year, as well as a look forward to what I want to accomplish in 2024.

\n

2023 Goals

\n

First, let’s tackle by 2023 goals from last year. I feel like I fared rather well, all things considered.

\n\n

The highlight of my year

\n

If you read my year-end review for 2022, you’ll know my wife was diagnosed with breast cancer in September of that year. She underwent an experimental treatment in December 2022, then surgery in November of this year.

\n

It’s been a long, scary, sometimes extremely stressful road, but I am more than pleased to report she has been classified cancer free! After the experimental treatment, her tumor has completely disappeared, and there was no sign of microscopic cancer cells in her lymph nodes. This has been a huge relief to us both, and we’re taking some time to celebrate.

\n

2024 Goals

\n\n

See you in the New Year

\n

That’s all I have for now. I hope you had a great year and I hope your 2024 is even better. You’ll hopefully see more of me in the near future now that I finally feel like I have my bearings. Until next time!

\n", "date_published": "2024-01-01T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/year-end-review-2022/", "url": "https://www.falldowngoboone.com/blog/year-end-review-2022/", "title": "Year-end review 2022", "content_html": "

What. Just. Happened?

\n

And I thought 2021 was crazy.

\n

2022 was a roller coaster of emotion for many people. We saw historical weather events, political events, everything. I would like to, for once, have a year that is not historic.

\n

My year was wild, filled with terrific ups and terrifying downs. What follows is a quick overview of my 2022.

\n

2022 opportunities reviewed

\n\n

Other 2022 accomplishments

\n\n

2022 challenges

\n\n

2023 goals

\n\n

Till next year

\n

Well, I’m done for 2022. It’s been real, and it’s been fun, but I’m ready for a boring year. Seriously.

\n

What are you excited about in 2023? Let me know on Twitter (assuming it continues to work), and I’ll see you again next year!

\n", "date_published": "2022-12-28T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/from-notion-to-eleventy-part-2-building-markdown-from-json/", "url": "https://www.falldowngoboone.com/blog/from-notion-to-eleventy-part-2-building-markdown-from-json/", "title": "From Notion to Eleventy part 2: Building Markdown from JSON", "content_html": "

This is the second article in an ongoing series where I explore using Notion’s API to directly build a blog post for Eleventy. In the first post of this series, I used the Notion API to write a local JSON file representing all the data that I need to stitch together a blog post. In this blog post, I’m going to turn that ball of JSON into a Markdown file.

\n\n

You might ask, Ryan, doesn’t Notion already have a Markdown export feature? Yes, Notion does have a Markdown export feature, but there are a couple reasons why I want something more custom.

\n

First, every time I export an article, the first thing I have to do (aside from unpacking the zip package, renaming the file, and moving it to the appropriate directory) is format the front matter. This work is trivial but tedious, and surprisingly open to error.

\n
title: \"This is an example of my front matter\"
date: 2022-02-22
excerpt: \"Sometimes I include an excerpt here.\"
tags:
  - example
  - front matter
\n

Second, I would like more control over how to interpret the content I get from Notion. For example, Notion exports callout blocks as <aside>s with emoji icons. I would like to write those callout blocks as custom Eleventy paired shortcodes or even React components.

\n
<aside class=\"c-post__aside c-post__aside--info\"><p>This is an example of my <code>aside</code> shortcode. It renders as an <code>aside</code>
with a special class.</p>
</aside>
\n

The plan

\n

I’ve never written a Markdown formatter before, but I know I need to start with breaking the problem down into manageable steps. The plan will most likely change throughout the process as I surface unknown or unanticipated challenges, but it serves as a good starting place. After a little bit of thought, my plan is as follows:

\n
    \n
  1. \n

    Combine page properties and the main content into a single JSON structure. To write the entire file, I’ll at least need the page properties and child blocks. I can combine both pieces into a single object like this:

    \n
    {
      \"frontMatter\": {/* page properties */},
      \"content\": {/* child blocks */}
    }
    \n
    2. \n
  2. \n

    Format the front matter. On my blog, front matter is formatted in YAML, which is whitespace sensitive. I think I can utilize a simple template literal to properly format this, but I may need something to format rich text objects, which is a trickier problem than it may initially seem.

    \n
    3. \n
  3. \n

    Format the content. My blog posts are formatted in Markdown which, like YAML, is whitespace sensitive. Unlike the front matter, though, I can’t use template literals due to the dynamic nesting of child blocks. I’ll need to figure out how to properly write line padding and line returns to the page. And just like the previous step, I’ll need a solution for formatting rich text objects.

    \n
    4. \n
  4. \n

    Create the file structure for the post and write the file. This is work I’m very familiar with, at least at a level that’s needed for the initial solution.

    \n
    5. \n
\n\n

I will start with step three, formatting the content, which I believe demands the most effort. I already have code that fetches page properties and content, so step one seems like it’s simply writing a third function that combines the first two calls. Step four, as I’ve noted, is something I’ve done multiple times in the past. And I’m guessing that if I can solve step three, I’ll be in a much better position to finish step two quite easily.

\n

Let’s print a page

\n

My approach to writing the page content is to imagine I’m writing the page myself in a text editor. When writing Markdown, I start a new line, indent, write my content, rinse and repeat. This metaphor will help me define methods and variable names.

\n

I’ll also need a way to format content before I write it to the page. When I’m writing Markdown, I just know that two hashes and a space before content (## Content) denotes a second-level heading. Since each block object in the Notion API has a type and configuration specific to that type, I can build methods for each block type that just know how to format that type with the given configuration.

\n

With this context in mind, this is what I came up with:

\n
class Printer {
  #writers;
  #opts;
  #indentLevel = 0;
  #page = [];

  constructor(writers, opts) {
    this.#writers = writers;
    this.#opts = opts;
  }

  #writeProperties(properties) {
    const { frontMatter } = this.#opts;
    this.#writeLine(frontMatter(properties));
  }

  #writeContent(block, parent = null, index = 0, blocks = []) {
    if (!block) return;

    if (Array.isArray(block)) {
      return block.forEach((child, i) =>
        this.#writeContent(child, parent, i, block)
      );
    }

    const writer = this.#writers[block.type];

    writer?.({
      block,
      parent,
      index,
      blocks,
      writeLine: this.#writeLine.bind(this),

      // convenience fields
      isFirst: index === 0,
      isLast: index === blocks.length - 1,
      prev: blocks[index - 1] || null,
      next: blocks[index + 1] || null,
      getConfig({ type, [type]: config }) {
        return config;
      },
    });

    if (block.has_children) {
      this.#indent();
      this.#writeContent(block.children, block, index, blocks);
      this.#dedent();
    }
  }

  #writeLine(content = '') {
    this.#page.push(''.padStart(this.#indentLevel * SPACES));
    this.#page.push(content);
    this.#page.push(NEW_LINE);
  }

  #indent() {
    this.#indentLevel++;
  }

  #dedent() {
    this.#indentLevel--;
  }

  #printPage() {
    return this.#page.join('');
  }

  print({ frontMatter, content }) {
    this.#writeProperties(frontMatter);
    this.#writeContent(content);
    return this.#printPage();
  }
}
\n

My writing metaphor’s “page” is represented as a plain array. Pushing content to the array “writes” to the page, then joining the array and returning the result “prints” the page. A single, public method (print) takes our content data structure as an argument, writes it to the page, and returns the results as one continuous string. The writers parameter of the constructor contains the methods that “know” how to format block types.

\n

Perhaps the most interesting block of code in this class is the #writeContent method:

\n
#writeContent(block, parent = null, index = 0, blocks = []) {
  if (!block) return;

  if (Array.isArray(block)) {
    return block.forEach((child, i) =>
      this.#writeContent(child, parent, i, block)
    );
  }

  const writer = this.#writers[block.type];

  writer?.({
    block,
    parent,
    index,
    blocks,
    writeLine: this.#writeLine.bind(this),

    // convenience fields
    isFirst: index === 0,
    isLast: index === blocks.length - 1,
    prev: blocks[index - 1] || null,
    next: blocks[index + 1] || null,
    getConfig({ type, [type]: config }) {
      return config;
    },
  });

  if (block.has_children) {
    this.#indent();
    this.#writeContent(block.children, block, index, blocks);
    this.#dedent();
  }
}
\n\n

This method recurses through the content blocks, pulls off the correct writer method, and passes in a whole slew of data. This data includes a writeLine method, which writes a single line to the private #page array, including new lines and proper indentation. Here’s a look at what my Markdown writers look like:

\n
const formatters = {
  paragraph({ block, writeLine, isLast, getConfig }) {
    const { rich_text } = getConfig(block);

    writeLine('');
    writeLine(formatRichText(rich_text));
    isLast && writeLine('');
  },

  heading_2({ block, writeLine, isLast, getConfig }) {
    const { rich_text } = getConfig(block);

    writeLine('');
    writeLine(`## ${formatRichText(rich_text)}`);
    isLast && writeLine('');
  },

  bulleted_list_item({ block, prev, writeLine, getConfig }) {
    const { rich_text } = getConfig(block);

    if (prev && !prev.type.includes('list_item')) {
      writeLine('');
    }

    writeLine(`- ${formatRichText(rich_text)}`);
  },
  // ...more
};

function formatRichText(richTextObjects = []) {
  // more on this later...
}
\n

The writer methods have complete control over how they are written based on their siblings. For example, a paragraph type can add an extra line after itself if it is the last block in the array and list items can add an extra line before themselves if they follow a block that is not a list item.

\n

This architecture allows me the flexibility of changing the output format via different writers while leaving the main compositional logic untouched. The only thing I might later change in the Printer class is making indentation and newlines optional since some formats aren’t whitespace dependent.

\n

I’m limiting direct interaction with the Printer class by only exporting a function (getPrinter) that instantiates the class:

\n
// in printer.js
function getPrinter(writers, opts = {}) {
  return new Printer(writers, opts);
}

export { getPrinter };

// elsewhere...
import {getPrinter} from 'printer'
import {formatters} from 'formatter-markdown'

const myPrinter = getPrinter(formatters, {...opts})

myPrinter.print(dataFromNotion)
\n

This allows me the freedom to rewrite the Printer however I want (e.g. with closures instead of a class) without having to update everywhere the class is accessed. It also removes any ambiguity about how to instantiate a Printer (though I don’t think I’ve ever had that problem, it’s something I’ve constantly read about in articles and books).

\n

At this point, we have all the code needed to transform the blocks we get back from Notion into block-level content. Formatting inline content, however, is a bit trickier.

\n

Rich text formatting

\n

In the Notion API, inline content is split into arrays of rich text objects. Like block objects, each rich text object contains a type ("text", "mention" and "equation") and corresponding configuration. Additionally, each contains an annotations object, which includes all the local styling information:

\n
[
  {
    \"type\": \"text\",
    \"text\": {
      \"content\": \"This is an example \"
    },
    \"annotations\": {
      \"bold\": false,
      \"italic\": true,
      \"strikethrough\": false,
      \"underline\": false,
      \"code\": false,
      \"color\": \"default\"
    },
    ...
  },
  {
    \"type\": \"text\",
    \"text\": {
      \"content\": \"of rich text objects.\"
    },
    \"annotations\": {
      \"bold\": true,
      \"italic\": true,
      \"strikethrough\": false,
      \"underline\": false,
      \"code\": false,
      \"color\": \"default\"
    },
    ...
  }
]
\n

There are two main approaches to applying the annotations to the content fragments. One method is to treat each fragment individually, applying the start and end token for each annotation object. This works great for HTML but breaks Markdown interpretation. Here’s an example of this technique for both HTML (em and strong) and Markdown (* and **) using the previous rich text objects:

\n
<!-- this works with HTML -->
<em>This is an example </em><strong><em>of rich text objects.</em></strong>

<!-- whitespace and adjacent duplicate tokens break Markdown interpretation -->
*This is an example ****of rich text objects.***
\n

The first fragment ends with whitespace, so the first group of italic tokens (*) isn’t properly interpreted in Markdown. We could check for whitespace at the end of each fragment, pop it off, add the token, then reapply the whitespace, but that would break continuous styles like strikethrough. The best fix is to span tokens of adjacent fragments with duplicate styles.

\n
<!-- now works with italics tokens spanning the entire line -->
*This is an example **of nested styling.***
\n

This method involves analyzing rich text objects in possible groups of three: the current object we are formatting, as well as the previous and following objects (if they exist). For each true annotation for the current object, if the previous object doesn’t have the current annotation, we add the beginning token. If the next object doesn’t have the current annotation, we add the ending token.

\n
richTextObjects.map(({ type, [type]: config, annotations }, i) => {
  let formatted = '';
  const prev = richTextObjects[i - 1];
  const next = richTextObjects[i + 1];

  if (annotations.italic) {
    const startToken = !prev?.annotations.italic ? '*' : '';
    const endToken = !next?.annotations.italic ? '*' : '';
    
    formatted = `${startToken}${config.content}${endToken}`;
  }
  if (annotations.bold) {
    const startToken = !prev?.annotations.bold ? '**' : '';
    const endToken = !next?.annotations.bold ? '**' : '';
    
    formatted = `${startToken}${config.content}${endToken}`;
  }
  // ...link, striketrhough, etc.
}
\n

This logic is not only used to apply the annotation tokens but the link tokens as well. To DRY up this code, I’ve abstracted out the token creation into a factory:

\n
function createFormatFactory(current, prev, next) {
  return (key, startToken, endToken = startToken) => {
    const pre = current[key] && !prev?.[key] ? startToken : '';
    const post = current[key] && !next?.[key] ? endToken : '';

    return (content) => `${pre}${content}${post}`;
  };
}
\n

This factory is basically three functions that gradually apply formatting arguments in separate layers. Each formatting function needs a current, previous, and next source object (for the styles, it’s the annotations object, and for the link, it’s the rich text object’s type configuration), so that layer is captured first.

\n

The next layer defines the source object’s key and what tokens to apply. Note that the endToken defaults to the startToken so I don’t have to pass in two * tokens for italic, two ** tokens for bold, etc.

\n

Finally, the last layer applies the derived tokens to some content. Here’s an example of using this factory to create and apply an italic style:

\n

const content = 'This is some content';
const annotations = { italic: true };
const previousAnnotations = { italic: false };
const nextAnnotations = { italic: false };
const formatFromAnnotations = createFormatFactory(
  annotations,
  previousAnnotations,
  nextAnnotations
);

const italic = formatFromAnnotations('italic', '*')

italic(content) // '*This is some content*\"
\n

We will eventually end up with a group of formatter functions that will be applied in a fixed order. We start with code since nesting any tokens inside of a code style will not be interpreted by Markdown. Application with a fixed order along with spanning styles creates certain edge cases that will break (e.g. a code spanning over a link). In practice, these edge cases have been few and far between, so I am choosing to ignore them right now.

\n

When applying multiple functions to a single source, I immediately reach for a compose function, which simply composes multiple functions together. Using some more recent JavaScript, creating a compose function is trivial:

\n
function compose(...fns) {
  return (x) => fns.reduceRight((acc, fn) => fn(acc), x);
}
\n

Here is a comparison of applying several functions inline versus using compose:

\n
const fn1 = (arg) => {...}
const fn2 = (arg) => {...}
const fn3 = (arg) => {...}
const fn4 = (arg) => {...}

const result = fn4(fn3(fn2(fn1(someArg))))

const composedResult = compose(fn4, fn3, fn2, fn1)(someArg)
\n

Notice that we apply the functions from right to left, mimicking the order they appear when composing them inline. That is why we use Array.prototype.reduceRight in the definition of compose. This convenience method allows us to reduce an array in reverse order.

\n\n

Now that we have the basis for our inline formatting logic, we can put the pieces together in our formatRichText function:

\n

function formatRichText(richTextObjects = []) {
  return richTextObjects
    .map(({ type, [type]: config, annotations }, i) => {
      if (type !== 'text') return ''; // TODO: support `mention` and `equation`

      const prev = richTextObjects[i - 1];
      const next = richTextObjects[i + 1];

      const formatFromConfig = createFormatFactory(
        config,
        prev?.[prev?.type],
        next?.[next?.type]
      );
      const formatFromAnnotations = createFormatFactory(
        annotations,
        prev?.annotations,
        next?.annotations
      );

      const link = formatFromConfig('link', '[', `](${config.link?.url})`);
      const bold = formatFromAnnotations('bold', '**');
      const italic = formatFromAnnotations('italic', '*');
      const strikethrough = formatFromAnnotations('strikethrough', '~~');
      const underline = formatFromAnnotations('underline', ''); // no-op for Markdown
      const code = formatFromAnnotations('code', '`');

      const formatter = compose(
        link,
        bold,
        italic,
        strikethrough,
        underline,
        code
      );

      return formatter(config.content);
    })
    .join('');
}
\n

At this point, we are officially done with step three of our plan. We now have a flexible system for styling block-level content, and an efficient way to format rich text objects. We should have more than enough tooling to take on step two, building the page’s front matter.

\n

The front matter

\n

Front matter is truly a separate concern from the page content, but for the time being, I am choosing to tie front matter generation directly to my Markdown formatting. I’ll explain why in a minute. First, let’s examine what needs to be built.

\n

The front matter of my page is represented in Notion as page properties. Currently, my front matter consists of:

\n\n

When assembled, my typical page front matter looks like this:

\n
title: \"Here it is: An example article\"
date: 2022-01-01
excerpt: \"This is an example of [front matter](https://www.11ty.dev/docs/data-frontmatter/). It supports *rich* text formatting.\"
tags:
  - example
  - fake
\n

My front matter is structured to support rich text in my excerpt field, and since I already have a Markdown rich text formatter, I’m going to default to formatting my front matter with Markdown. This is the biggest reason I’m tying front matter generation to the formatter.

\n

With that in mind, let’s look at the front matter generator:

\n
function frontMatter({ title, date, excerpt, tags }) {
  return `
title: \"${title.title.map(({ plain_text }) => plain_text).join('')}\"
date: ${date.date?.start || today()}
excerpt: \"${formatRichText(excerpt.rich_text)}\"
tags:
${tags.multi_select.map(({ name }) => `  - ${name}`).join('\\n')}
---`;
}
\n

The frontMatter function takes our custom properties object (page.frontMatter) and combines the data with a string template literal. I kept this function simple on purpose because I may at some point decide to use a different format for my front matter altogether.

\n

As previously mentioned, this function lives with the Markdown content formatter because it relies on formatRichText, but front matter generation is a concern separate from content generation. I’m contemplating pulling the main logic of that function into the Printer class, but that’s a problem for Future Ryan.

\n

Revisiting our Notion client

\n

Now that I have most of the formatting out of the way, I want to pull my client code from the previous article in this series into a new module. I’m going to take this time to tweak the code a bit as well. Here’s the entirety of the new client module:

\n
import { Client } from '@notionhq/client';
import slugify from 'slugify';

async function readBlocks(client, blockId) {
  blockId = blockId.replaceAll('-', '');

  try {
    const { results } = await client.blocks.children.list({
      block_id: blockId,
    });

    const childRequests = results.map(async (block) => {
      if (block.has_children) {
        const children = await readBlocks(client, block.id);
        return { ...block, children };
      }
      return block;
    });

    const expandedResults = await Promise.all(childRequests);

    return expandedResults;
  } catch (error) {
    handleClientError(error);
  }
}

async function readPageInfo(client, pageId) {
  try {
    const { properties } = await client.pages.retrieve({
      page_id: pageId,
    });

    return properties;
  } catch (error) {
    handleClientError(error);
  }
}

async function readPage(client, pageId) {
  const pageInfo = readPageInfo(client, pageId);
  const pageContent = readBlocks(client, pageId);

  try {
    const [properties, content] = await Promise.all([pageInfo, pageContent]);

    const {
      Name: title,
      ['Publish Date']: date,
      Excerpt: excerpt,
      Tags: tags,
    } = properties;

    return {
      slug: getSlug(title),
      frontMatter: { title, date, excerpt, tags },
      content,
    };
  } catch (error) {
    handleClientError(error);
  }
}

// TODO: better error handling
function handleClientError(error) {
  console.error(error.body || error);
}

function getClient(options) {
  const client = new Client(options);

  return {
    pages: {
      fetch(pageId) {
        return readPage(client, pageId);
      },
    },
  };
}

function getSlug({ title }) {
  return slugify(
    title
      .map(({ plain_text }) => plain_text)
      .join('')
      .toLowerCase()
  );
}

export { getClient };
\n

I’m combining the page info and page content methods to return the data structure our Printer.print method expects. I’m also including a slug since it’s a concern closely related to the page’s properties, and it’s much easier to encapsulate two related concerns than it is to expose a method that leaks module details to another module.

\n

I’m exporting a single method, getClient, that returns a simple namespaced object. This gives me the freedom to add new methods in the future if necessary, or completely reimplement existing methods without having to touch other code.

\n

Putting it all together

\n

We now have all the major pieces to pull down page data, create the front matter from page properties, and output the page content as Markdown. The final step is to combine these pieces and write the result to a local file. To do that, I’ve written a main function that imports the client and formatting methods and uses Node’s file system module to write the file:

\n
import { writeFile, mkdir } from 'fs/promises';

import { getClient } from './client.mjs';
import { getPrinter } from './printer.mjs';
import { formatters, frontMatter } from './formatter-markdown.mjs';

const CLIENT_TOKEN = process.env.CLIENT_TOKEN;

async function main() {
  if (process.argv.length < 3) {
    console.log('Usage: npm run publish:page [pageId]\\n');
    return 1;
  }

  const pageId = process.argv[2];
  const client = getClient({
    auth: CLIENT_TOKEN,
  });

  const printer = getPrinter(formatters, { frontMatter });

  try {
    const data = await client.pages.fetch(pageId);
    const dir = `./src/blog/${data.slug}`;

    await mkdir(dir, { recursive: true });
    return await writeFile(`${dir}/index.md`, printer.print(data));
  } catch (error) {
    console.error(error);
  }

  return 1;
}

main();
\n

This function is tied to an npm script, publish:page, and takes a page ID as an argument:

\n
npm run publish:page -- [pageId]
\n

The script fetches the page data using our client, creates the blog post’s directory using the slug from the page data, then writes the file using our printer class.

\n

Conclusion

\n

This article focused on pulling Notion page content down, formatting block and rich text objects to Markdown, and writing that content locally to a new file. I have effectively replaced the Markdown export feature of Notion with something much more custom. I have also highlighted a hand full of techniques aimed at making the code more flexible.

\n

This feels like a good stopping point, but this is by no means the end of this project. I’ve begun using this script to build my post pages, and I’ve already identified several areas for improvement. I’ll continue to post updates as I come across any bugs or improvements, but you can always get the latest and greatest code from my website’s repo.

\n

Well, that wraps things up for this post. Thank you for sticking with it all the way through. If you liked this article or found it useful, please share it with a friend, and once you do, let me know. It’s free to you and it helps me out tremendously.

\n

Thanks for stopping by. Until next time!

\n

Resources

\n\n", "date_published": "2022-05-05T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/quick-tip-non-standard-npm-module-resolution/", "url": "https://www.falldowngoboone.com/blog/quick-tip-non-standard-npm-module-resolution/", "title": "Quick tip: Non-standard npm module resolution", "content_html": "

I’m putting the finishing touches on a publishing script for my blog and ran across an interesting situation. The scripts use native ES modules, but Eleventy, the JavaScript framework my blog uses, currently does not support them. I have to specify that my scripts use ES modules with the .mjs extension.

\n
scripts/
└── my-publishing-script/
\t\t└── index.mjs
\n

I like to abstract the internals of a script as much as possible, so I like to utilize Node.js module resolution, which allows you to do stuff like this:

\n
const library = require('library');
\n

The assumption is that you’ve already run npm install library and library now lives in your node_modules directory.

\n

If you’ve ever cracked open one of those libraries and looked at their package.json file, chances are they’re making use of the main field, which instructs Node.js as to where the entry file lives relative to the package.json. By default, Node.js looks for index.js, but it can literally be named anything.

\n

Going back to my script, since it now has to use the .mjs extension, Node.js no longer automatically resolves it, but I can fix that by adding a package.json to my script’s directory with a single main field:

\n
scripts/
└── my-publishing-script/
\t\t├── index.mjs
\t\t└── package.json
\n
{
\t\"main\": \"index.mjs\"
}
\n

Now I don’t have to specify the entry file when calling the script:

\n
node scripts/my-publishing-script
\n", "date_published": "2022-03-19T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-i-solve-complex-problems/", "url": "https://www.falldowngoboone.com/blog/how-i-solve-complex-problems/", "title": "How I solve complex problems", "content_html": "

Developers are professional problem solvers. It’s the number one reason I became a developer. I am addicted to the feeling I get from solving problems, and there’s rarely a problem that I shy away from, much to my detriment.

\n

Early on in my professional career, I took on stories that I thought were interesting problems to solve. Unfortunately, I lacked a strong framework to help me deal with the complexity many of these stories presented. The result was missed deadlines and overcomplicated solutions.

\n

This is something I see in many developers starting out. They want to solve big, interesting problems, but they haven’t developed the tools and the intuition necessary to do so in a timely, well-organized manner. If you’re just starting out, I would encourage you to develop a problem-solving framework that works for you.

\n

After my first performance review highlighted my issue with complex problems, I decided to be more intentional with how I approached problems. I developed a personal problem solving framework with the help of my manager, and have continued to refine it with the help of books and articles I’ve read, along with experience I’ve gained working with other developers.

\n

My framework in summary is as follows:

\n
    \n
  1. Break the problem down
    2. \n
  2. Hardest problem first
    3. \n
  3. Work in intervals
    4. \n
  4. If you get stuck, talk to a duck
    5. \n
\n

Let’s examine these steps in more detail.

\n

Break the problem down

\n

Complex problems can seem impossible to solve, but they’re really a string of simple problems tangled up in a knot. The first step to solving these complex problems is to loosen the knot. We can do that by attempting to pick out the simple problems we already know how to solve.

\n

Given a customer’s cart, which consists of items with a quantity and a price, how would you determine the total cart price? One way of breaking this problem down would be:

\n
    \n
  1. Iterate through each cart item
    2. \n
  2. For each item, multiply the quantity and price
    3. \n
  3. Combine the item total of each result
    4. \n
\n

A side effect of breaking problems down is you have effectively written psuedo-code that can translate directly to your solution:

\n
// iterate through each cart item
function iterate(items, callback) {
\tfor (let i = 0, l = items.length; i < l; i++) {
\t\tcallback(items[i])
\t}
}

// for each item, multiply the quantity and price
function itemTotal({quantity, price}) {
\treturn quantity * price;
};

// combine the item total of each result
function combineTotals(totals) {
\treturn totals.reduce((a, b) => a + b);
}

// let's put it all together...
function cartTotal(items) {
\tconst totals = [];

\titerate(items, (item) => totals.push(itemTotal(item));

\treturn combineTotals(totals);
}
\n

Granted, this may not be the most efficient to get a cart total, but it works. You can always work on optimizations once you have a working solution (but that’s for another article).

\n

Maybe calculating a customer’s cart total isn’t a complex problem to you, but this same approach works for anything from sorting search results by relevance to utilizing an API to build blog posts (shameless plug).

\n

When breaking a problem down, I don’t stop at my initial steps. I evaluate my proposed solution with a series of questions:

\n\n

If I’m unsure about anything in the plan, I bring in another team member and walk them through the context. My current team is even experimenting with doing this as a team for stories of significant complexity. Many times different team members will have insight into areas of hidden complexity others may not be aware of.

\n

Hardest problem first

\n

Once I have a plan together, I can start executing it, but not necessarily in the order it’s written. I prefer a testing technique I adapted from the excellent online course Learning How to Learn that may seem counterintuitive.

\n

I start with what I believe is the most difficult problem, get as far as I can as quickly as possible, and when I can go no further, I tackle the easiest problem. When that problem is done, I switch back to the difficult problem, get a bit further, then tackle the next-easiest problem if I hit another dead end. I repeat this process until all of the problems are solved.

\n

The first reason to start with a hard problem then move to an easy one is it optimizes the total solution time. Switching to other problems and quickly knocking them out ensures every step of the overall solution will have at least some work done, even if I end up getting really stuck (more on that later).

\n

This technique also optimizes brain power. According to Learning How to Learn, our brains have two basic modes of activity: a focus mode, where the brain focuses its raw power on a single thought, and a diffuse mode, where thoughts bounce all over the brain, connecting seemingly unrelated chunks of thought. Research has shown that the brain works best when switching between these two modes constantly.

\n

Why is that? If you flex a muscle group as hard as you can for an extended period of time, it will fatigue, no matter how well-developed that muscle is. Your brain’s focus mode is like flexing a muscle. Switching to the diffuse mode is like resting that muscle. In addition to rest, the diffuse mode is also responsible for finding novel solutions to problems, which may help you solve your problem faster.

\n

Work in intervals

\n

Switching to easier problems helps create space for the brain to rest, but we also need actual rest. I have ADHD, so my work habits swing wildly from completely unfocused to obsessive hyper-focus. Before I know it, five hours have blown by and I’m exhausted. The Pomodoro Technique has been effective in lessening these wild swings and helping me focus on work in a healthy, balanced way.

\n

Developed in the 1980s by Francesco Cirillo, the Pomodoro Technique calls for 25 minute blocks of focused, uninterrupted work followed by a short break. After completing four cycles of uninterrupted work, take a longer break. There’s a bit more to the technique itself, but at its core, it’s about splitting deep work up into manageable blocks, giving your mind the time to rest and maybe even explore alternative solutions.

\n

What should you do during your break? I personally like to grab a coffee, a snack or work on a Sudoku. I’ve even taken up Quordle, which I find quite fascinating. Really anything I can do in a short amount of time that distracts me from work.

\n

If I feel like I’m losing momentum or discover a new issue that further complicates the problem, I will take some time before a new pomodoro to reevaluate my strategy (see the previous questions in Break the problem down). Sometimes, however, I find myself completely stuck. That leads me to my last problem-solving strategy.

\n

If you get stuck, talk to a duck

\n

You may have heard of rubber ducking before. It comes from a story in the fantastic book The Pragmatic Programmer (highly recommend) where a developer would carry around a rubber duck and explain their code to it line-by-line. I don’t have a rubber duck, but the concept has stuck with me ever since I first read that.

\n

Many times I will reiterate the problem to myself or, much to her chagrin, my wife. Sometimes reiterating the problem at this stage can uncover things you missed in your initial definition of the problem itself, or you can get confirmation that you need someone else to check your work.

\n

If I’m still stuck, I pull another developer into the conversation (if I paired with a developer on my initial strategy, I talk to that person). I explain the context of the problem and lead them line-by-line in what I’ve done so far. I can’t tell you how many times a fellow developer’s question has unlocked a path to a solution.

\n

It’s important to note that the quicker you get help, the quicker you’ll get to a solution. I tend to want to solve all the problems by myself, but sometimes that’s not possible. The lesson to learn here is don’t let your ego stand between you and a solution. Knowing when to ask for help is a mark of a mature developer (not that I’m consistent in this area).

\n

Conclusion

\n

Solving complex problems is something every developer will do. A solid problem-solving framework can help you create better solutions within the tightest of deadlines. Be intentional and leave your ego at the door. The more you develop your framework, the more effective you’ll become.

\n

Do you have a problem-solving framework? If so, I’d love to know what’s worked for you. I’m always interested in new approaches that could help me grow as a problem solver.

\n

Until next time!

\n", "date_published": "2022-03-12T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/preserve-intent-with-architecture-decision-records/", "url": "https://www.falldowngoboone.com/blog/preserve-intent-with-architecture-decision-records/", "title": "Preserve intent with architecture decision records", "content_html": "

The first thing I want to do when I dig into a new codebase is learn everything about it. The second thing I want to do is rewrite it. Whether you’re trying to do the former or the latter, architecture decision records (ADRs) can help.

\n

I was first introduced to ADRs at The Container Store, where the technology department adopted them as a way to record large tech decisions, mostly around microservices architecture. My team adopted ADRs as a way to record front-end architecture decisions for the e-commerce site as well.

\n

As I write this, I’m working on my current team’s first ADR. As part of that exercise, I wanted to write out what I understand about ADRs and how they’ve been helpful to me in the past.

\n

What is an architecture decision record?

\n

An architecture decision record is a document that records a decision. More than that, ADRs capture context such as the problems a decision is meant to address, alternative solutions, and why this decision was chosen.

\n

In addition to decisions and context, ADRs typically contain decision consequences, both good and bad. Every decision has trade offs, and listing them alongside benefits sheds light on possible concerns to watch for.

\n

As far as ADR structure, there are several examples of templates freely available. The first article I ever read on documenting architecture decisions, written by Michael Nygard, is even written as an ADR.

\n

Benefits

\n

For small decisions, informative code comments are great. But when you are adopting a practice throughout a project or department, decision records are the best way to communicate publicly what decision is being made and why.

\n

ADRs make the decision process transparent. Many times writing an ADR involves the entire team or department, so everyone has an opportunity to explore the decision and understand why it’s being made. This inclusion can increase decision buy-in and alignment as well, since everyone is signing off on it.

\n

Decision records can be a great onboarding tool as well. Seeing a complete record of decisions can help developers quickly come up to speed on a project. Reading ADRs is much more productive than digging through years of commit history (your team writes informative commit messages, right?).

\n

Changing code is risky, and not knowing why the code exists makes any change even riskier. Why spend time to rewrite a layer of architecture only to realize after the work is complete that there are holes in the implementation?

\n

Finally, a side benefit of writing an ADR is it’s an opportunity for the author to work on their communication skills. I’ve written before about why I believe communication is one of the most important skills for a developer to…develop. ADRs give developers a chance to communicate complex issues in an easy-to-read manner, as well as develop their ability to argue for a solution.

\n

Decision record tips

\n

If you want to get started with ADRs, the easiest way is to find something undocumented that everyone’s already doing and try writing an ADR for that. You’ll be surprised what you’ll learn when exploring the context and consequences of any decision. You may even stumble upon a better solution.

\n

Whatever the solution is, involve the entire team. Open up a request for comments (RFC) on the decision and make sure everyone is on board. If you can, try to involve every interested engineer in your department. Different engineers bring different perspectives and experience to the table. The more diverse perspectives, the better the decision.

\n

My final tip is to make your ADRs visible and easy to search. You may want to save your ADRs directly to a repo, or maybe add them to a company wiki. Whatever you do, get a consensus on how to create ADRs (maybe write an ADR on that?). At The Container Store, one of my colleagues built a Ruby on Rails CRUD app that streamlined drafting ADRs directly to a PR in a decision record repo, which kinda made it fun to write ADRs.

\n

What are you waiting for?

\n

Architecture decision records capture decisions, but they also capture the context and consequences of those decisions. ADRs can make the decision process more transparent, increase developer alignment and help onboard new developers. They can even help develop your communication skills. What’s not to love?

\n

If you’ve read this far, my guess is you’re considering adopting ADRs as a practice on your team. My opinion is you should try them. At the very least you’ll start a conversation with your teammates. There’s a good chance, however, that you’ll introduce a productive practice that will endure long after you’ve left.

\n", "date_published": "2022-03-05T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/from-notion-to-eleventy-part-1-the-notion-api/", "url": "https://www.falldowngoboone.com/blog/from-notion-to-eleventy-part-1-the-notion-api/", "title": "From Notion to Eleventy part 1: The Notion API", "content_html": "

Notion allows me to collect, organize, and flesh out blog post ideas in a single place, but my painfully manual process of moving from Notion into Eleventy needs work. In this post, the first of a series, I’m going to crack open Notion’s API and see if there’s a way I can use it to streamline my blog workflow.

\n

Since I’ve never used the Notion API before, I need to come up with a plan. After reading Notion’s excellent API Getting Started guide, I have an initial strategy.

\n
    \n
  1. Create an integration.
    2. \n
  2. Connect the integration with my Articles database.
    3. \n
  3. Install the Notion JavaScript client in my Eleventy project.
    4. \n
  4. Test the API.
    5. \n
  5. Explore work flow ideas.
    6. \n
\n

After I’ve established how to use the API, I’ll have a better idea how to build out a full publishing workflow, which I will implement in the next article. Let’s get started!

\n\n

The set up

\n

In order to use the Notion API, I need to first create an integration. Integrations are the way Notion authorizes API usage for a particular workspace. The instructions to create an integration are fairly straightforward, but you will need to know the permissions you want your integration to have.

\n

Since my test only involves reading data, I’m only giving my integration the ability to read data. I’m also excluding user information since I’m the only user. In general, you only want to grant the bare minimum permissions (Notion calls them capabilities) you need to accomplish your goal.

\n

\"A

\n

After creating my integration, I’ll copy and paste the generated token to my local environment for later. If you’re following along, make sure you don’t paste that token into your codebase and commit it to git. Secrets should never be committed to your git history (I’ve learned this lesson the hard way).

\n\n

Now that I’ve created an integration, I still can’t use it because Notion will only allow access to pages and databases you have explicitly shared with the integration. You can share any page or database within the assigned workspace by navigating to the thing you want to share and clicking the Share button, then Invite. You should see your new integration in the resulting dialog.

\n

I’ve invited my integration to a parent page of my Articles database. When you connect a page and/or database to an integration, all child entities come along for the ride. Now I have access to all of my articles. Very exciting!

\n

Testing the API locally

\n

By now I have hopefully integrated Notion’s API with my Articles database. To test out the connection, I’ll first install the convenient Notion JavaScript client in my blog’s codebase:

\n
npm install @notionhq/client
\n

I’ll also create a little sandbox script that will eventually become my publishing script.

\n
// notion.js

import { Client } from '@notionhq/client';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

function doStuff() {
\tconsole.log('Notion!');
}

doStuff();
\n

Whenever I’m creating a script for automation or app integration, I like to start out with a simple script like this. I create a function, then I call that function. I also import whatever dependencies I think I’ll need and set up environment variables. I’ll then run this with node:

\n
$ NOTION_TOKEN=you_super_secret_token node notion.js
Notion!
\n

First I want to read my articles database, and for that, I’ll need a database ID. To get a database ID, navigate to the desired database in Notion (make sure to open it as a page if you haven’t already), open the kebab menu in the top righthand corner, and click Copy link. Paste that link somewhere. The portion between the last / and the ? is the ID (if you’re looking at a page link, the ID is the bit after the slug).

\n
# for databases
https://www.notion.so/<workspace>/<datbase_id>?v=...

# for pages
https://www.notion.so/<workspace>/<page_slug>-<page_id>
\n

After I get the ID for my articles database, I can modify the dummy script to read the contents using the Notion API client:

\n
// notion.js

import { Client } from '@notionhq/client';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

const notion = new Client({
  auth: NOTION_TOKEN,
});

async function readDatabase() {
  try {
    const response = await notion.databases.query({
      database_id: '6ae47178...', // Articles database ID
      filter: {
        and: [
          {
            property: 'Status',
            select: {
              equals: 'Published',
            },
          },
        ],
      },
    });
    console.log(JSON.stringify(response, null, 2));
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

readDatabase();
\n

Notice I’m only querying for articles with a Status of Published. You can filter for a long list of properties. When I run that script, I can see a successful response (edited for brevity):

\n
{
\t\"object\": \"list\",
\t\"results\": [
\t\t...
    {
      \"object\": \"page\",
      \"id\": \"5b8889e9...\",
      ...
    }
  ],
  \"next_cursor\": null,
  \"has_more\": false
}
\n

Notion databases contain pages, and database queries return a response with a list of page objects. This is nice, but what I really want to do is read a page. After selecting a random page ID, I adjust my database script to read a page instead:

\n
// notion.js

import { Client } from '@notionhq/client';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

const notion = new Client({
  auth: NOTION_TOKEN,
});

async function readPageInfo() {
  try {
    const page = await notion.pages.retrieve({
      page_id: '7b9c0c66ee...', // An random article
    });
    console.log(JSON.stringify(page, null, 2));
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

readPageInfo();
\n

Running this script returns a single page object. Looking at the page object, I can see that all my page properties are here:

\n
{
  \"object\": \"page\",
\t...
  \"properties\": {
    \"Publish Date\": {
      \"id\": \"%3BkvS\",
      \"type\": \"date\",
      \"date\": {...}
    },
    \"Tags\": {
      \"id\": \"%40GyO\",
      \"type\": \"multi_select\",
      \"multi_select\": [...]
    },
    \"Name\": {
      \"id\": \"title\",
      \"type\": \"title\",
      \"title\": [...]
    },
    \"Status\": {
      \"id\": \"prop_2\",
      \"type\": \"select\",
      \"select\": {...}
    }
  },
\t...
}
\n

This is probably what I’ll need to build my post front matter. The page content, however, isn’t included in this response.

\n

When I first saw this, I was a bit confused (mostly because I wasn’t reading the reference docs), but this makes sense. Page content is relatively unbounded, so you could have thousands upon thousands of pieces of data objects associated with a page object. Returning all of that data in a single response would be disastrous for the API’s network.

\n

So how do I get to a page’s content? For that, I’ll need to read the page’s child blocks.

\n\n

Reading page content

\n

In Notion, all content, including pages, are modeled as blocks. Blocks can contain child blocks, which is the case with pages. We can use the Notion API to query a block’s children like this:

\n
// notion.js

import { Client } from '@notionhq/client';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

const notion = new Client({
  auth: NOTION_TOKEN,
});

async function readBlocks() {
  try {
    const blocks = await notion.blocks.children.list({
      block_id: '7b9c0c66ee...',
    });

    console.log(JSON.stringify(blocks, null, 2));
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

readBlocks();
\n

The response includes some of the page’s blocks, but not all of them. By design, blocks with children don’t return with their child blocks resolved (again, for data size concerns). They do, however, include a has_children property of true. We can use that property, as well as the block’s block_id, to recursively fetch child blocks.

\n
// notion.js

import { Client } from '@notionhq/client';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

const notion = new Client({
  auth: NOTION_TOKEN,
});

// block ID is now a param
async function readBlocks(blockId) {
\tblockId = blockId.replaceAll('-', '') // strip all dashes

  try {
    const { results, ...blocks } = await notion.blocks.children.list({
      block_id: blockId,
    });
    const expandedResults = [];

    for (let block of results) {
      if (block.has_children) {
        block.children = await readBlocks(block.id); // recursion FTW!
      }

      expandedResults.push(block);
    }

    return { ...blocks, results: expandedResults }; // we need to return something
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

readBlocks('7b9c0c66ee...')
\t.then((data) => JSON.stringify(data, null, 2))
  .then(console.log);
\n

This successfully returns a block’s children and assigns them to a children property (hooray!). There is a slight problem with this script, however. In the for...of loop, we await the results of the child readBlocks call. The current script execution pauses until the awaited Promise settles, which slows the script down considerably when dealing with a large number of nested blocks.

\n

\"An

\n

We can improve this with Promise.all.

\n
// notion.js

import { Client } from '@notionhq/client';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

const notion = new Client({
  auth: NOTION_TOKEN,
});

async function readBlocks(blockId) {
  blockId = blockId.replaceAll('-', '');

  try {
    const { results, ...blockResponse } = await notion.blocks.children.list({
      block_id: blockId,
    });

    const childRequests = results.map(async (block) => {
      if (block.has_children) {
        const children = await readBlocks(block.id);
        return { ...block, children };
      }
      return block;
    });

    const expandedResults = await Promise.all(childRequests);

    return { ...blockResponse, results: expandedResults };
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

readBlocks('7b9c0c66ee...')
\t.then((data) => JSON.stringify(data, null, 2))
  .then(console.log);
\n

Notice the results are now mapped to promises (async functions automatically wrap their return values in a promise even if they’re a synchronous value). Each read process is immediately kicked off, and we simply wait for all of them to be resolved before moving on. This is much faster than reading child blocks one request at a time.

\n

\"An

\n

Now that we have a way to read page properties and page content, we’ll finish up this exercise by writing this information to a local file. For that, we can use node’s fs module:

\n
import { Client } from '@notionhq/client';
import { writeFile } from 'fs/promises';

const NOTION_TOKEN = process.env.NOTION_TOKEN;

const notion = new Client({
  auth: NOTION_TOKEN,
});

async function readBlocks(blockId) {
  blockId = blockId.replaceAll('-', '');

  try {
    const { results, ...blockResponse } = await notion.blocks.children.list({
      block_id: blockId,
    });

    const childRequests = results.map(async (block) => {
      if (block.has_children) {
        const children = await readBlocks(block.id);
        return { ...block, children };
      }
      return block;
    });

    const expandedResults = await Promise.all(childRequests);

    return { ...blockResponse, results: expandedResults };
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

async function readPage(pageId) {
  const pageInfo = notion.pages.retrieve({
    page_id: pageId,
  });
  const pageContents = readBlocks(pageId);

  try {
    const [info, contents] = await Promise.all([pageInfo, pageContents]);

    return { ...info, contents };
  } catch (error) {
    console.log('error!');
    console.error(error.body);
  }
}

readPage('7b9c0c66ee...')
  .then((data) => JSON.stringify(data, null, 2))
  .then((data) => writeFile('test.json', data));
\n

Wrapping up

\n

This is a great place to stop for now. To review, I started out by creating an initial plan, then I tackled the plan step-by-step. When I ran into issues (e.g. discovering page objects don’t include content), I amended the plan.

\n

Now I have a data structure written to a local file that includes everything I need to write a post. The main challenge left, then, is transforming that data into something I can consume in Eleventy. I’ll cover that in my next article.

\n

I should note I purposely chose a page that was very small and contained simple content. I didn’t want to get bogged down troubleshooting edge cases when all I wanted to do was explore the API. Keep in mind there are API limits, and if your content is relatively large and complex, you will encounter them at some point.

\n

Dealing with these limits is outside the scope of this post, but I may in the future write a dedicated post on how to work with API limits (e.g. rate limits, pagination, etc.). If that’s something you’d like to read, let me know!

\n

If you’ve enjoyed this post, please consider sharing it with others that might like it. And if you have any comments, please reach out to me on Twitter. I love to discuss all things front end, and it quite frankly gives me the warm fuzzies to know other people are reading these posts.

\n

Until next time!

\n", "date_published": "2022-02-26T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/brad-frost-on-how-to-use-storybook/", "url": "https://www.falldowngoboone.com/blog/brad-frost-on-how-to-use-storybook/", "title": "Brad Frost on how to use Storybook", "content_html": "

Brad Frost recently appeared on the new Storytime podcast with Chantastic to talk about how he uses Storybook to build design systems. The show features a great discussion regarding how Frost’s Atomic Design philosophy has been applied to the popular UI development tool. If you haven’t already, I highly recommend checking the episode out.

\n

As a follow up to the discussion, Brad wrote a companion article that details how he utilizes Storybook in design systems. This article was timely for me, as the team I work on is dealing with a crisis of faith regarding our Storybook implementation.

\n

Long story short, building stories for our components has been somewhat complicated due to the complexities of our form system. Coupled with the lightning-fast rate we’ve been adding features to existing components, and our Storybook is lacking in-depth and up-to-date information.

\n

Brad says in his article the he uses Storybook as the official design system, building components exclusively in Storybook, then packaging up the results in a bundle that’s then used as a project dependency. I think this approach would be a great solution to our team’s current lack of interest.

\n

Of course, this approach slows UI development down, but I would argue that’s a good thing. I personally like to take it slow when creating shared components. Context is key to creating a health component API, and you need to use a component pattern several times before you understand everything that’s required.

\n

I hope to have a follow up article about this in the future. I’m also planning a series on how I approach component API design and development, so give me a follow on Twitter and DEV Community if that sounds like something you’re interested in.

\n

In the meantime, be sure to watch the interview and read Brad’s article.

\n", "date_published": "2022-02-18T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/the-one-where-this-is-undefined/", "url": "https://www.falldowngoboone.com/blog/the-one-where-this-is-undefined/", "title": "The one where 'this' is undefined", "content_html": "

I have been writing JavaScript since…well, let’s just say I was still watching new episodes of Friends on my un-flat CRT television. As long as I’ve worked with JavaScript, I still seem to forget the gotchas around the this keyword.

\n

Recently I ran into a series of problems involving the this keyword while exploring the Notion API. I thought it’d be Fun™ to take a look at why those problems occurred and how I ultimately resolved them.

\n

The code

\n

Notion’s API has a notion (see what I did there?) of content as blocks. To write a page out, you have to stitch together these blocks in a specific way.

\n

Each block has a different type, and each type is associated with a different handler. I built a class that takes an object of handlers keyed by these types and got this masterpiece:

\n
class Writer {
\t#writers;

\tconstructor(writers) {
\t\tthis.#writers = writers;
  }

\twrite(block) {
\t\tif (!block) return '';

\t\tif (Array.isArray(block)) {
\t\t\treturn block.map(this.write).join('');
\t\t}

\t\tconst { type } = block;
\t\tconst writer = this.#writers[type];

\t\treturn writer(block);
\t}
}

const writer = new Writer({
\tparagraph({ paragraph }) {
\t\tconst { text } = paragraph; // text here is actually an array of blocks

\t\treturn `<p>${this.write(text)}</p>`;
\t},
\t// ...more handlers...
\ttext({ text }) {
    const { link, content } = text;
    return link ? `<a href=\"${link.url}\">${content}</a>` : content;
  }
})
\n

Note that the block handlers passed into the Writer class can reference the write function directly. This is a convenience that allows handlers to forward nested block types to the writer for further processing. Neat!

\n

Here’s my Writer class in action:

\n
readBlockChildren('7b9c0c66eebd47c6911ecd7f2defad6b') // A Notion API wrapper
  .then(writer.write)
  .then(console.log);
\n

Looks harmless enough, except we get a nasty error when we run this code:

\n
\t\t\treturn block.map(this.write).join('');
                            ^

TypeError: Cannot read properties of undefined (reading 'write')
\n

Well that’s rude! Apparently this is undefined inside of the Writer#write method.

\n

After some investigation, I determined that the error happens right after the first .then call after reading the article blocks:

\n
readBlockChildren('7b9c0c66eebd47c6911ecd7f2defad6b')
  .then(writer.write) // I'm the problem. Hello!
  .then(console.log);
\n

Notice I’m using a point-free style to pass my write method to then. I like it because it feels more terse. Don’t judge me.

\n

We reference this inside of writer.write(). Normally, this wouldn’t be a problem, but passing writer.write point free removes the writer context, leaving this bound to the global context (which is undefined in strict-mode).

\n

Here’s an illustration of the problem:

\n
class MyClass {
  getContext() {
\t\treturn this;
  }
}

const myClass = new MyClass();
const getContext = myClass.getContext;

myClass.getContext(); => MyClass {}
getContext(); => undefined
\n

Passing the write method point-free is the equivalent of assigning it to a variable. No context. Whomp whomp.

\n

Calling the method inside a callback fixes this particular issue.

\n
readBlocks()
\t.then((block) => writer.write(block))
\t.then(console.log)
\n

The context is preserved and everyone gets a medal.

\n

A new challenger has appeared

\n

Unfortunately, even though the context is preserved during the first call, running the code again yields this gem:

\n
\t\tconst writer = this.#writers[type];
                        ^

TypeError: Cannot read properties of undefined (reading '#writers')
\n

The error suggests that this is once again undefined. This seems related to the last problem, but at a different spot. Some more investigation uncovers the location of the cause lies in how I handle arrays in the write method:

\n
write(block) {
\tif (!block) return '';

\tif (Array.isArray(block)) {
\t\treturn block.map(this.write).join(''); // here's the problem
\t}

\tconst { type } = block;
\tconst writer = this.#writers[type];

\treturn writer(block);
}
\n

Again, I’m using point-free style (I’m the worst), and again the context gets completely lost. The reason is slightly different now, though. Array#map is called with a callback, which by default binds this to undefined.

\n

One solution is to nest the write method reference inside a callback like previously. There is one caveat: since we are referring to this.write and not a class instance (writer.write), an arrow function is required to maintain the lexical[lexical] this binding.

\n

[lexical] Lexical is just a fancy way of saying the context of the surrounding scope at the time the scope is being defined, which in this case is the class instance. Lexical is also one of my favorite words. Say it with me: lexical.

\n
write(block) {
\tif (!block) return '';

\tif (Array.isArray(block)) {
\t\t// this doesn't work
\t\t// return block
    //    .map(function (child) {
    //      return this.write(child);
    //    })
    //    .join('');

\t\t// this works
\t\treturn block.map((child) => this.write(child)).join('');
\t}

\tconst { type } = block;
\tconst writer = this.#writers[type];

\treturn writer(block);
}
\n

That’s definitely one way of fixing that problem, but a more interesting way is to use the second argument for map, which is the thisArg:

\n
write(block) {
\tif (!block) return '';

\tif (Array.isArray(block)) {
\t\t// this works
\t\treturn block.map(this.write, this).join('');
\t}

\tconst { type } = block;
\tconst writer = this.#writers[type];

\treturn writer(block);
}
\n

Did you know map took a second argument? Yeah, it does. When we pass a thisArg to map, this is then bound to thisArg inside of the map callback. Huzzah!

\n

Another one

\n

Now let’s run that beautiful code.

\n
\t\treturn `
${this.write(text)}
\\n`;
                      ^

TypeError: Cannot read properties of undefined (reading 'write')
\n

Okay, I quit.

\n

Alright, I’m back. This is really a rollercoaster of emotion for me.

\n

Same issue, different place. It seems like I’ve gotten really good at trying to read properties of undefined. But that’s okay, we will persevere!

\n

After taking a closer look at the error, it seems like the issue is no longer occurring inside of the write method, which I believe to be a sign of progress. This time, the issue is inside a writer definition.

\n

If you recall from a previous code block way back near the top of this article (who remembers that far back, anyway?), we pass a map of writers into the Writer class at initialization. These writer methods can also access the write method with this (or, at least that’s how I planned it; in practice they’re doing jack squat).

\n

The writers need some way to write nested content, so write needs to be present somehow in the writer context.

\n
// a quick reminder of what the writers look like
const writers = {
\tparagraph({ paragraph }) {
\t\tconst { text } = paragraph;

\t\treturn `<p>${this.write(text)}</p>`; // hey, here's a `this` reference
\t},
\t// ...more handlers...
\ttext({ text }) {
    const { link, content } = text;
    return link ? `<a href=\"${link.url}\">${content}</a>` : content;
  }
}

// inside Writer
write(block) {
  if (!block) return '';

  if (Array.isArray(block)) {
    return block.map(this.write, this).join('');
  }

  const { type } = block;
  const writer = this.#writers[type]; // assignment!

  return writer(block);
}
\n

We assign the writer function to a variable within the class’s write method, but this will not bind the instance context to this inside the writer methods. Why?

\n

First of all, we’re doing that thing where we blow away context by assigning an instance method to a variable. D’oh!

\n

Let’s call the method directly and see if that fixes things:

\n
write(block) {
  if (!block) return '';

  if (Array.isArray(block)) {
    return block.map(this.write, this).join('');
  }

  const { type } = block;

  return this.#writers[type](block); // writer called directly
}
\n

We still get an error, but it’s a new error message.

\n
\t\treturn `<p>${this.write(text)}</p>\\n`;
                      \t ^

TypeError: this.write is not a function
\n

This time this is defined (progress!), but write is not (bummer!). Chalk that up to a change in context.

\n

The writers are functions defined in an object literal, so this refers to the surrounding object literal, not the parent class instance. If we want to keep the this references in the writer methods, we’ll need to bind the class instance to the method before calling it:

\n
write(block) {
  if (!block) return '';

  if (Array.isArray(block)) {
    return block.map(this.write, this).join('');
  }

  const { type } = block;
  const writer = this.#writers[type].bind(this);

  return writer(block);
}
\n

The bind function method takes a thisArg as its first argument and binds that function’s this to that argument’s value (in the case of null or undefined, this defaults to the global execution context). Another interesting use of bind is partial application, but that’s a subject for another day.

\n

The use of bind fixes our this problem completely, but it might be a bit confusing for other users. Passing the class instance method of write into the writer as a second argument might seem more reasonable:

\n
write(block) {
  if (!block) return '';

  if (Array.isArray(block)) {
    return block.map(this.write, this).join('');
  }

  const { type } = block;

\t// remember to pass as an arrow function to preserve the current scope!
  return this.#writers[type](block, (block) => this.write(block));
}
\n

We would then use this write method in the writers.

\n
const writers = {
\tparagraph({ paragraph }, write) { // write method injected as an argument
\t\tconst { text } = paragraph;

\t\treturn `<p>${write(text)}</p>`; // works!
\t},
\ttext({ text }) { // if you don't need the `write` method, don't use it!
    const { link, content } = text;
    return link ? `<a href=\"${link.url}\">${content}</a>` : content;
  }
}
\n

Making peace with this

\n

The code works now. Hurray! Looks like I won’t be quitting tech, moving to a large, unincorporated rural area and starting my own country in a prepper basement. Today.

\n

When I started working with JavaScript at an unspecified date in the past, this was one of the most confusing concepts to me. So confusing, in fact, that I avoided it like the plague.

\n

Thankfully there are tons of great resources available to shed light on this. One of the most helpful resources was Kyle Simpson’s excellent You Don’t Know JS series, especially this & Object Prototypes. I consumed that book, as well as several other resources (shout out to Frontend Masters!), and this became less confusing to me, and now I use it all over the place (to my own detriment, apparently).

\n

I guess the point I’m trying to make is not to use this in your every day code; it’s to make peace with the parts of programming that confuse, frustrate, or even frighten you. Understanding core concepts of your programming language of choice empowers you and gives you a better toolset to troubleshoot annoying errors.

\n

Do you love this? Do you wish this was never included in JavaScript? Even more important, do you have a better pattern for unwinding Notion blocks? Let’s discuss on Twitter.

\n

Until next week!

\n", "date_published": "2022-02-12T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-i-blog-in-2022/", "url": "https://www.falldowngoboone.com/blog/how-i-blog-in-2022/", "title": "How I blog in 2022", "content_html": "

It’s a new year, and I’m eager to get back into the habit of blogging on my site. To start, I’m taking another look at my blogging process and what has changed since the last time I wrote about it.

\n

Idea generation

\n

I’ve maintained a blogging Notion for a couple of years now, but I recently adopted Dave Rupert’s Notion blogging kanban.

\n
\n \"\"\n
My blogging kanban, which is completely aped from Dave Rupert. Thanks, Dave!
\n
\n

The kanban has six lanes: No Status, Outlined, Started, Rough Draft, Final Draft, and Published. Ideas get chucked into the No Status lane and slowly make their way from left to right on the board as the post develops.

\n

Each lane is sorted by Last Updated, which I love. As Dave explains:

\n
\n

This gives me a “What’s hot” vibe for each column. It helps me keep momentum on my latest ideas —a freshness seal— to keep them from falling out of view.

\n
\n

If a story gets too stale or I notice it hasn’t progressed in a while, I archive it, which removes it from the kanban view. I have a separate view for these archived, unpublished ideas, which Dave calls the Deadpool. I’ve added a dedicated view for these in case I need to search through them.

\n

Like Dave, I’ve also added a view that organizes all my posts by tag. I haven’t used this view much, but it’s nice to see at a glance what topics I tend to favor.

\n

Publishing

\n

Publishing is still as manual as ever. I export the post out of Notion as Markdown and add it to my local website instance. I adjust the front matter, then send it through Grammarly for final corrections.

\n

After finalizing the article, I commit and open a pull request on GitHub. Pull requests automatically start project tests and spin up a staging site, thanks to Netlify and GitHub actions. After verifying that all is well, I merge into the main branch, and Netlify does the deployment.

\n

Keeping everything in Notion is great because everything is in the same place. The downside is publishing is still a ridiculously manual process. I plan to address this later this month by checking out Notion’s API.

\n

Blogging frequency

\n

After completing a daily blogging challenge last year, I thought seriously about setting a weekly blogging goal. I had written a new piece every day; how hard could it be to move to a weekly schedule? As it turns out, quite hard.

\n

Life happens, and in 2021 it really happened. I talk more about it in my 2021 year-end review, but I got burned out, lost family members, and started a new job. To say my life was chaotic is a bit of an understatement.

\n

That’s not to say that I shouldn’t expect to produce content regularly. I stopped writing because I didn’t have a consistent habit. That’s why I like setting blogging challenges. They give me something to aim for, which keeps me focused on the process itself.

\n

Other changes

\n

When I first launched my latest blog design in 2020, there were more than a few rough edges (by design). I also didn’t know what I wanted because I had never consistently published content.

\n

After upping my content production, I was able to see glaring holes in my simple design that needed plugging.

\n

I made much progress toward plugging those holes in 2021. I shipped several new features, my favorite of which is my new home page. Other shipped features include styling for blockquotes, footnotes, asides, etc.

\n

I’m looking forward to adding some form content later this year when I add a contact section. I have plans to make it especially fun and (hopefully) educational. I also plan on shipping a dark theme in the next couple of months.

\n

Conclusion

\n

So that’s a quick look at my blogging process for early 2022. I like doing these because it helps me understand what’s working and what isn’t. I hope you enjoy them too.

\n

This year should prove interesting. I’ve got some GraphQL and TypeScript content planned, in addition to some of my UI component philosophy. If that sounds like something you’d like to read more about, give me a follow on Twitter or DEV Community to be notified when these posts are published.

\n

Until next time!

\n", "date_published": "2022-02-04T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/year-end-review-2021/", "url": "https://www.falldowngoboone.com/blog/year-end-review-2021/", "title": "Year-end review 2021", "content_html": "

2021 proved to be an eventful year for many of us. Personally, my year brought tremendous successes, failures, victories, and heartbreak. These last 365 days have felt like an entire lifetime!

\n

Last year I wrote a similar year-end review for 2020, where I laid out some 2021 opportunities that I felt were worth pursuing. So how did I do?

\n

2021 opportunities reviewed

\n\n

Other 2021 accomplishments

\n\n

2021 challenges

\n

At the end of 2020, I was hopeful that 2021 would be a much better year, and while I had some incredible experiences, the year was not without its share of setbacks.

\n\n

2022 goals

\n

With 2021 out of the way, I am hoping for a better, brighter 2022. My focus will continue to be growth and learning, but I will also include my health. With everything that’s happened this past year, I’m afraid I haven’t taken care of myself. To that end, here are my personal goals for 2022:

\n\n

Till next year

\n

That does it for my 2021.

\n

I’m curious to hear what you’re excited about in 2022. Let me know on Twitter, and I’ll see you again next year!

\n", "date_published": "2021-12-28T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/kicking-sass-to-the-curb/", "url": "https://www.falldowngoboone.com/blog/kicking-sass-to-the-curb/", "title": "Kicking Sass to the curb", "content_html": "

Google web dev advocate and all-around awesome person Una Kravets mentioned in a tweet earlier this year that got my wheels turning (I can hear them squeaking as I type):

\n
\n

I used to write “Convert your CSS codebase into Sass!” guides\nNow I think it’s time for a “Convert your Sass codebase into vanilla CSS!” guide

\n
\n

Sass is usually the first thing I install in a brand-new project, right after git and npm initialization. Could I bear to do without it now? And why would I want to get rid of Sass anyway?

\n

Simplicity is a worthy goal in any web dev endeavor, but maybe simplicity in the build chain is the most worthy goal of all. Removing a complete build branch makes the process easier to maintain and understand. But before I can even think about getting rid of Sass, I need to examine why I use it in the first place.

\n

Why I use Sass

\n

I’ve used Sass in a variety of ways over the past decade, from Codekit to Gulp, WebPack, and most recently the JavaScript API (I also have experience with Compass, although not by choice). Sass offers several features, but the ones I currently use are:

\n\n

Let’s take a look at each one and see if vanilla CSS offers a suitable alternative.

\n

Static variables

\n

I use Sass variables for storing colors, spacing values, font data, and breakpoints. They are one of the Sass features I lean on consistently. And now they’re easier to reason about thanks to the @use rule.

\n
// _colors.scss
$black: lch(10% 0 0);
$red: lch(38% 68 33);

// style.scss
@use \"colors\" as c;

.text {
  color: c.$black; // namespaced, which is useful for large Sass projects
  
  &:hover {
    color: c.$red;
  }
}
\n

The question is, Can vanilla CSS replace my Sass variables? This one seems easy at first. Variables, by way of CSS custom properties, have already made their way into many of my style sheets.

\n
// root.css

:root {
  --black: lch(10% 0 0);
  --red: lch(38% 68 33);
}

// style.css

.text {
  color: var(--black);
  
  &:hover {
    color: var(--red);
  }
}
\n

Sure, their syntax is weird at first, especially compared to Sass, but custom properties have superpowers Sass variables only wish they had. For starters, custom properties are dynamic and can change value based on the current context:

\n
.container {
  --padding: 0.5rem;

  padding: var(--padding);
}

@media screen and (min-width: 640px) {
  .container {
    --padding: 1rem;
  }
}
\n

Imagine changing the global spacing and typography by setting a couple of custom properties in the :root selector at different breakpoints. I’m heavily utilizing this pattern on this blog.

\n

Another nice thing about CSS custom properties is I can easily share and manipulate them with JavaScript. I talk more about this in my article about sharing variables between JavaScript and CSS, but, in summary, custom properties are computed style, just like every other CSS property, so JavaScript can read and mutate them at will:

\n
:root {
  --my-property: hello;
}
\n
const myProperty = getComputedStyle(document.documentElement)
    .getPropertyValue('--my-property');

console.log(myProperty); // hello

document.documentElement.style.setProperty('--my-property', 'goodbye');

const myMutatedProperty = getComputedStyle(document.documentElement)
    .getPropertyValue('--my-property');

console.log(myMutatedProperty); // goodbye
\n

The above example is scratching the surface of how CSS custom properties outshine their static Sass cousins, but I still haven’t dropped Sass variables altogether. There are a couple of areas where I yet prefer static variables.

\n

The CSS variables spec states that the “var() function can not be used as property names, selectors, or anything else besides property values.” The property value rule is an unfortunate limitation on where and how custom properties are accessed.

\n

First, you can’t use custom properties as part of selectors, so no &__block selectors. That’s not a deal-breaker for me since I’m moving away from doing that sort of thing in my code. Generating BEM selectors with the parent selector may not be terrible in a small, well-known codebase, but it becomes a nuisance when searching for selectors in larger codebases.

\n

The biggest bummer is you can’t use custom properties is in media queries. The first reason is @- rules are top-level, so there’s nowhere to set them and no way to inherit a value. Dynamic media query values can also create update cycles that never resolve (this could be why media queries created with rems tended to be buggy early on as well).

\n

There is currently a proposal to add custom media queries that would solve this problem:

\n
@custom-media --md (max-width: 30em);

@media (--md) {
  ...
}
\n

It’s in Editor’s Draft at the time of this writing, but I’m hoping we’ll see it implemented soon.

\n

Static variables verdict

\n

I already use custom properties everywhere, and I predict custom media queries will one day replace my need for Sass’s static variables. For now, though, it seems Sass’s variables will continue to make my life easier.

\n

Nesting

\n

Nesting was the killer feature when I started using Sass. It was so convenient to nest rules inside of rules that I did it often. Probably too often. Now I limit myself to three levels of nesting, mostly pseudo-selectors and media queries.

\n
.button {
  background-color: lch(57% 40 212);
  padding: 0.25em 0.5em;

  :hover {
    background-color: lch(64% 40 212);
  }

  :active {
    background-color: lch(51% 40 212);
  }

  ::before {
    content: \"→\";
  }

  .uppercase-block & {
    text-transform: uppercase;
  }

  @media screen and (min-width: 70em) {
    padding: 0.5em;
  }
}
\n

The good news for camp vanilla CSS is there is a CSS Nesting Module proposal. It’s slightly different from the Sass implementation. None of those fancy compound BEM-style ( e.g. &__element) selectors and the nesting selector (&) is always required, at least for now (Sass infers the current selector to be the first character unless explicitly used elsewhere in the selector).

\n
.button {
  background-color: lch(57% 40 212);
  padding: 0.25em 0.5em;

  &:hover {
    background-color: lch(64% 40 212);
  }

  &:active {
    background-color: lch(51% 40 212);
  }

  &::before {
    content: \"→\";
  }

  // hey, look, a new at-rule!
  @nest .uppercase-block & {
    text-transform: uppercase;
  }

  @media screen and (min-width: 70em) {
    & {
      padding: 0.5em;
    }
  }
}
\n

Unfortunately, the proposal is in Editor’s Draft as of this post’s publish date. But, hey, that’s also a good thing because at least the W3C is looking at it.

\n

Nesting verdict

\n

I will gladly replace Sass nesting with native CSS nesting, provided it gets implemented. Even if I were to stay with Sass, chances are the Sass spec itself would have to change to support the new native CSS implementation.

\n

Mixins

\n

There was a point when the main thing I would use mixins for was vendor prefixes, but Autoprefixer replaced them. Now that prefixes aren’t as prevalent, I manually add prefixes as needed.

\n

A current use I have for mixins, in combination with Sass variables, is creating custom media queries:

\n
// _utils.scss

$md-min: 611px;

@mixin mq-max($width) {
  @media screen and (max-width: $width) {
    @content;
  }
}

@mixin md-and-up {
  @include mq-min($md-min) {
    @content;
  }
}

// style.scss

@use \"./utils\" as u;

html {
  font-size: 112.5%;

  @include u.md-and-up {
    font-size: 125%;
  }
}
\n

I’ve already mentioned that native custom media queries are under consideration, so this use case is also covered (or, at least will be covered).

\n

I also dry up selector generation with mixins. Here is a sample mixin I’ve used in the past to generate utility classes:

\n
@mixin generateUtils($property-map, $value-map, $suffix) {
  @each $property-id, $properties in $property-map {
    @each $value-id, $values in $value-map {
      .u-#{$property-id}-#{$value-id}#{$suffix} {
        @each $property in $properties {
          #{$property}: $values;
        }
      }
    }
  }
}
\n

This admittedly opaque mixin loops through properties and values to create a bunch of utility classes. It’s a factory for margin and padding utility classes, similar to what you would find in Tailwind.

\n

There are several issues with the above utility factory. First of all, it creates a ton of classes, many of which may remain unused. We must then purge these classes with something like PurgeCSS. This purging is further complicated by dynamically generated markup.

\n

The second issue is, as previously stated, this code is opaque. I can’t perform a simple global search to find a class created dynamically. I need intimate knowledge of the codebase to understand where the code generation occurs.

\n

Removing the factory and manually adding utility classes as you need them solves both problems:

\n
.u-m-0 {
  margin: var(--m-0);
}

.u-m-1 {
  margin: var(--m-1);
}

.u-m-2 {
  margin: var(--m-2);
}

// ...etc.
\n

It’s not perfect, but at least I can search for a utility class and find it. I can also add utilities as needed, which should prevent utility class bloat.

\n

The biggest drawback to this approach is you lose control over the abstraction. I’ve seen team members insert explicit values in the utility names (e.g. u-m-15, which would set the margin property to 15px), which can, ironically, cause class bloat.

\n

Ultimately, I would prefer to avoid a utility-first solution, but if one is necessary, perhaps leaning on a library would be the best solution in this case. Tailwind has been improving leaps and bounds in reducing bloat, and it’s becoming a more familiar solution. Otherwise, it’s probably time to revisit your CSS methodology.

\n

Mixins verdict

\n

There is no one-size-fits-all approach for replacing mixins. Determine why you or your team are using them and whether it makes sense to replace them. In short, It Depends™.

\n

Modules

\n

Sass modules are an improvement over the old @import syntax. My main use for Sass modules is importing other stylesheets via the @use at-rule:

\n
// styles.scss

@use 'reset';
@use 'global';
@use 'objects';
@use 'components';
@use 'utilities';
\n

@use allows me to split large style sheets up into manageable and composable chunks, which is one of the best use cases for Sass. Sass’s module system will only write a style sheet once, even if you import it multiple times.

\n

This module system is an instance where a build tool will always outshine a runtime approach. Sass will concatenate the imported files together and output a single file, which creates a larger style sheet but cuts down on HTTP requests. There are CSS alternatives (multiple link elements and the @import rule[1]), but they involve separate HTTP requests.

\n

Of course, I assume that we still live in a world where fewer, larger HTTP requests are better than several small HTTP requests. HTTP/2 support is prevalent throughout modern browsers now, and many sites I have worked on have HTTP/2 turned on by default. I could forgo concatenating scripts, but I have yet to find a source that wholeheartedly recommends this approach (yet another attack of the It Depends monster).

\n

Modules verdict

\n

Honestly, this is such a new concept in Sass that I don’t see myself abandoning it any time soon. The power and simplicity of a statically-analyzed, build-time module system for CSS is a perfect use of Sass.

\n

PostCSS

\n

A recurring theme throughout this article is certain CSS functionality has been proposed but is not yet available. One solution to this challenge that many of you are probably already thinking is to (🚨 obligatory marketing copy alert 🚨) Use Tomorrow’s CSS Today with PostCSS Preset Env.

\n

The Preset Env plugin is sort of like the CSS equivalent of Babel’s preset-env plugin. PostCSS Preset Env is prone to some of the same issues as Babel, namely code bloat and the risk of changing specifications breaking implementation, but it’s the best (only?) solution if you want to start using some of these future specs today. Available polyfills include the nesting and custom media query proposals mentioned earlier, as well as several others.

\n

Keep in mind, though, CSS affords much less flexibility than JavaScript when extending the language. That means polyfills may come with extreme limitations, like the Custom Property polyfill that only allows custom properties on the :root selector. Your mileage may vary.

\n

Conclusion

\n

Will there ever be a time when I ditch Sass? I don’t know. Sass may continue evolving as CSS evolves, solving new problems we can’t even perceive at the moment.

\n

For now, though, Sass remains on my install list, even as I eye the inevitable list of goodies making their way through the CSS specification process. I’ve tried many times to move over to PostCSS, but I can never get it to stick. Sass is just easier to configure and use, at least for me.

\n
\n
\n
    \n

  1. According to Harry Roberts, you should avoid the @import rule in CSS. @import prevents a browser’s ability to download CSS in parallel and will slow down the initial render significantly. ↩︎

    \n
    2. \n
\n
\n", "date_published": "2021-11-21T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/misadventures-in-web-components/", "url": "https://www.falldowngoboone.com/blog/misadventures-in-web-components/", "title": "Misadventures in web components", "content_html": "

I have been thinking about web components a lot lately, and I wanted to see how we could start using them at The Container Store. The idea was to pick a simple component and recreate it as a web component, and the first candidate that came to mind is our frequently-used quantity stepper. The stepper appears in several places throughout the website, and it’s dependent on an embarrassing amount of jQuery.

\n

Here’s my humble first attempt:

\n

\n See the Pen \n Details by Ryan Boone (@falldowngoboone)\n on CodePen.\n

\n\n

The result isn’t perfect, but I gained a better understanding of web components, their limitations, and where they’re useful.

\n

Lessons learned

\n

My ultimate goal was to create a web component that progressively enhanced from a run-of-the-mill number input to a custom element. I also wanted to explore the limitations of web components inside a form. What I ended up with was this weird solution that sidesteps the shadow DOM altogether.

\n

Progressive enhancement…sort of

\n

The experimental component requires a donor number input, either as a child of my-stepper or, my preference, via a data-is attribute on a native input[type=number]. This is my naive version of customized built-ins, which I suspect would be perfect for this particular situation.

\n

The reason for the hand-rolled functionality is because Safari doesn’t support customized built-ins, nor do they intend to anytime soon[1]. I will probably swap out my custom data attribute solution for a polyfill that supports the native is attribute when implementing in production because this is not implemented to spec.

\n

The my-stepper’s template inserts child content in between two buttons wired up with click listeners. The listeners increment or decrement the value of the input (if present). The interesting thing about template slots is their content remains in the light DOM, making them completely accessible to the parent form.

\n

The result ensures that the input remains an input if JavaScript is disabled or (more than likely) takes a while to load, parse and execute[2].

\n

Native form functionality

\n

The shadow DOM encapsulates style and markup, but that comes at the cost of accessing field data in form field web components. Shadow DOM field values aren’t registered in form.elements and shadow fields cannot participate in the form lifecycle (e.g. field validation) by default.

\n

If you need to access field values, you can use a hidden input or listen for the formdata event on the parent form. Both strategies ensure you can pass data properly on submit, but neither will give you full access to the form lifecycle.

\n

The ElementInternals interface, however, officially grants web components access to the lifecycle of a parent form, including methods to determine the field’s value and validity:

\n
class MyElement extends HTMLElement {
  constructor() {
    this.internals = this.attachInternals();
    // use internals to set the form field value, 
    // determine valid data, etc.
  }
}
\n

In addition to gaining access to the form lifecycle, the ElementInternals specification grants access to the accessibility object model. Only Chrome and Chromium-based browsers support internals at the time of this writing, but, again, there are polyfills.

\n

Accessibility

\n

I learned that elements within the shadow DOM will still receive focus and are properly announced via a screen reader out-of-the-box (curiously, VoiceOver announces shadow DOM barriers as a new frame, at least at the time of this writing). I guess it acts sort of like an iframe in that respect?

\n

One concern I had, though, was how to reference an ID in the shadow DOM with a label in the light DOM. Unfortunately, shadow DOM ID reference is not possible, at least not natively. There have been discussions about somehow delegating labels via an option passed to attachShadow, but I haven’t seen anything regarding implementation.

\n

The only thing I found that works with the shadow DOM is determining the input’s label(s)[3], then adding click listeners to each that imperatively focus the shadow DOM target:

\n
const template = document.createElement('template');

template.innerHTML = `
<input name=\"name\" />
`

class MyInput extends HTMLElement {
  static get formAssociated() {
    return true;
  }
  
  constructor() {
    super();
    this.attachShadow({mode: 'open'});
    this.shadowRoot.append(template.content.cloneNode(true));
    this.internals = this.attachInternals?.() || {};
  }
  
  connectedCallback() {
    this.internals.labels?.forEach((label) => {
      console.log(label)
      label.addEventListener('click', () => {
        this.shadowRoot.querySelector('input')?.focus();
      });
    });
  }
}

customElements.define('my-input', MyInput);
\n

Hey, check it out, we’re exercising the ElementInternals API! That didn’t take long.

\n

Note that we have to first specify that an element is form-associated with the formAssociated static property, then we can access the form-related internals. Also, note that we have to attach the click listeners in the connectedCallback method instead of the constructor (which is what I attempted at first)[4]. Form association only happens after the element has attached to the DOM, so this.internals.labels is null in the constructor.

\n

Styling

\n

There are several ways to customize web component styles. For this experiment, I’m opening up custom styling via shadow parts and the ::part() CSS pseudo-element. I think this strategy works for this particular instance since there are only three pieces that need to be styled: the two buttons and the wrapper.

\n

The ::part() pseudo-element takes an identifier that is assigned with the part attribute:

\n
<button part=\"decrement control\">&minus;</button>
  <slot>CHILD CONTENT</slot>
<button part=\"increment control\">+</button>
\n
my-stepper::part(control) {
  /* styles here */
}
\n

Note that you can pass multiple identifiers to part. I’m using this feature to allow consumers to style both buttons with the control shadow part and the individual buttons with their respective shadow parts.

\n

Shadow parts may not scale that well with more complex elements, and I haven’t tested how they would work on child web components (web components nested in a web component shadow DOM).

\n

Final thoughts

\n

As I mentioned earlier, I think the next step is to redo this component as a customized built-in and let a polyfill or library do all the heavy lifting. I’m curious to see what role, if any, shadow DOM plays in that particular type of web component.

\n

I’m also interested in exploring LitElement and Stencil.js, particularly how they would integrate with our current stack. My ultimate goal is to make web component creation as easy and gotcha-free as possible, and libraries help normalize some of the weirdness you may get with a low-level API like web components.

\n

I had a ton of fun messing around with web components, and I learned a lot as well. If you found this helpful or have something you’d like me to write about, let me know. I enjoy doing these experiments and hope to deep dive even more into web components in the future.

\n

Until next time!

\n

Resources

\n\n
\n
\n
    \n

  1. Safari engineers argue that customized built-ins violate the Liskov substitution principle. Given the fact that this custom stepper will only support an input[type=number], I believe they’re probably right. But also, HTMLInputeElement is the element API equivalent of a dumpster fire. ↩︎

    \n
    2. \n

  2. Yes, the site should just run faster, I agree. Baby steps. And in an ideal world, we would pre-render shadow DOM on the server and hydrate it client-side. Currently, shadow DOM is imperative-only, so there’s no way to render on the server, but there is a proposal for declarative shadow DOM, something I hope to write about soon. ↩︎

    \n
    3. \n

  3. Remember, labelable elements can have more than one label. ↩︎

    \n
    4. \n

  4. It’s a good idea to always run your side effects like attaching listeners inside connectedCallback, even if you have access in the constructor. And make sure you clean up any listeners in the disconnectedCallback method. See the resources section for a link to web component best practices. ↩︎

    \n
    5. \n
\n
\n", "date_published": "2021-05-16T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/pardon-the-dust/", "url": "https://www.falldowngoboone.com/blog/pardon-the-dust/", "title": "Pardon the dust", "content_html": "

In case you didn’t notice, I just pushed up the biggest adjustment to the site design since the last redesign in late 2020. I wanted to go through it briefly and talk about what’s next.

\n

From the moment I published the last redesign, I’ve been working on improvements to the post template. The old posts felt blocky and sterile, and I wasn’t happy with the overall reading experience on smaller devices.

\n

For design exploration I turned once again to Figma, relying heavily on the Figma Mirror app on my iPhone and iPad Air. My design goals were to improve post readability and inject some personality into the site.

\n

Typography updates

\n

The previous body copy was a system font stack, which I think is great for applications, but for a personal blog, I wanted something slightly more unique. I added my former heading font Rotunda to the stack. Rotunda was supposed to be the body copy from the start (it’s all over my old Figma comps), but I never switched it over on the site until now.

\n

Next, I wanted to replace Rotunda as my heading font with something warm and retro. Recoleta Black fills the role nicely with soft serifs, tall x-height, and tons of stroke contrast. It’s a great counterpoint to the crispness of Rotunda.

\n

\"A

\n

Something I’m trying out that I’ve avoided for quite some time is using units in my line heights. For as long as I can remember I’ve avoided units in line height because of the way line-height is inherited. Using a unit, even if it’s a relative unit, forces the calculated value at the point of assignment to be the line-height of all children.

\n

So why am I using units now? Since unit-less line-height depends on the font size of the box it’s assigned to, it was becoming increasingly difficult to maintain a somewhat consistent vertical rhythm. I’m also tying specific line-heights to specific font sizes, so they act like presets now, which makes them easier to track and apply.

\n

This switch was partly inspired by Dan Mall’s Typography in Design Systems article, which I heavily recommend (actually, I heavily recommend anything written by Dan). In the article, Dan talks about the utility of creating presets, something that I intend on doing once I have some breathing room.

\n

The logo

\n

Hey, I’ve got a new logo! The old logo was a quick scribble in Affinity Designer. The new logo features Masifa Rounded, another soft, friendly font (I’m starting to detect a theme here). I feel like in thicker weights it starts to feel like it’s been run through an old copier, which I appreciate.

\n

\"The

\n

The plan is to eventually add some fun, hand-drawn logo animations that load randomly. I think that’ll be a nice way to add a bit more discovery to the site.

\n

More hand-drawn elements

\n

My original plan was to include more sketched elements from the very beginning, and now I’m starting to follow through with that with the new divider. I have plans to add additional sketch elements throughout.

\n

For now, I’m sketching directly in Figma for a mono-line feel. Soon I’ll be getting a new iPad Pro and Apple Pencil, so I’m curious to see what I can do with that setup.

\n

GitHub Projects

\n

One administrative change is I’m managing the project in GitHub Projects. I like keeping everything in a single place, and I’ve been curious about GitHub Projects for a while.

\n

So far it’s been straightforward. I like how I can automate the creation of cards by simply assigning a pull request or issue to my project. I’m using GitHub projects to track my bugs as well.

\n

What’s next

\n

The work is never done, and I’m still focused on finishing out my post template. After that, I have the home page in my sights.

\n

I’d love to look into eleventy-img for improved image performance. I also need to enable heading links for deep linking. That should only take a couple of minutes.

\n

Finally, I have a desire to explore Web Components. In a recent article, Josh W. Comeau dives into how he built his blog, and he talks at length about how he uses React and MDX to create his one-off, interactive examples. I would love to do something similar with Web Components and Markdown.

\n

Conclusion

\n

I hope you enjoyed this quick look at the latest adjustments to my blog. I have a lot of fun working on it, especially being able to revisit my design and illustrative roots. Are you in the middle of a blog redesign? I’d love to hear from you about how it’s going.

\n

That’s it for now. I’ll be returning to my regularly scheduled blog posts next month. Catch you then!

\n", "date_published": "2021-04-30T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/the-curious-case-of-flexbox-gap-and-safari/", "url": "https://www.falldowngoboone.com/blog/the-curious-case-of-flexbox-gap-and-safari/", "title": "The curious case of flexbox gap and Safari", "content_html": "

Update at the end

\n

The gap property was first introduced to add inner grid spacing but was extended in the spec to work with flexbox. With one line of code, you can replace something like this:

\n
.flex-container {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  margin: -0.5em;
}
.flex-container > * {
  margin: 0.5em;
}
\n

with this:

\n
.flex-container {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1em;
}
\n

That’s nice, but Safari doesn’t support gap in flexbox just yet. Normally I’d just reach for @supports:

\n
.flex-container {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1em;
}

@supports not (gap: 1em) {
  .flex-container {
    margin: -0.5em;
  }
  .flex-container > * {
    margin: 0.5em;
  }
}
\n

Unfortunately, Safari already supports gap in grid, so this doesn’t work. This is one of those weird cases where there is no easy CSS-only solution, though there have been proposals for workarounds.

\n

This has left me scratching my head. You could polyfill with JavaScript or use PostCSS, but at this point, is it worth it? That’s a question that all frontend developers have to weigh from time to time, and there’s no one-size-fits-all answer.

\n

I will probably wait until Safari supports flexbox gap in the latest two versions before using it, mainly because it doesn’t take that much more CSS to achieve the same effect. The only drawback is I cannot change the margins of the flex container. This can be overcome with an extra wrapper element, but then you’re starting to complicate the markup.

\n

If you want to read more about the flexbox gap issue, check out this post from Ahmad Shadeed. And if you found this post helpful, please like it on Dev Community and let me know on Twitter.

\n

Until tomorrow!

\n

Update

\n

As of Safari 14.1, flex gap is now supported! This brings me one step closer to replacing my object styles that do the same thing. I typically wait until something is supported in the last two versions of the evergreen browsers (or can be worked around).

\n

I would still love to have a way to use @supports, but I’ll take what I can get. Anyway, happy coding!

\n", "date_published": "2021-04-28T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/baking-in-syntax-highlighting/", "url": "https://www.falldowngoboone.com/blog/baking-in-syntax-highlighting/", "title": "Baking in syntax highlighting", "content_html": "

Another runtime dependency bites the dust. My ongoing work of designing and building this blog continues with moving syntax highlighting from the client-side to Eleventy’s syntax highlighting plugin:

\n
const syntaxHighlighting = require('@11ty/eleventy-plugin-syntaxhighlight');

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlighting);

  // other config stuff...

  return {
    dir: {
      input: 'src',
      layouts: '_includes/layouts',
    },
  };
};
\n

There are a couple of benefits to baking syntax highlighting into the build process vs. runtime. First of all, there’s no flash of unstyled markup in cases where JavaScript is slow to parse. Second, JavaScript is no longer required for syntax highlighting.

\n

There are issues, of course. One of my goals is to add line numbers to code blocks, and while there is a Prism line number plugin, it requires DOM to be present. Since there is no DOM during the plugin phase of Eleventy, this plugin doesn’t work.

\n

After searching around a bit, I found a clever trick involving CSS counters (thanks to Josh Buchea), but it breaks under certain conditions due to an issue with the line highlighting plugin. I detailed a few of the conditions in an issue I filed on my site.

\n

It looks like there is a possible fix that’s been opened, but I don’t see any activity around the pull request. It may be worth it to pull the commit into a third-party plugin, but that’s an exercise for later.

\n

There have been other changes since last I posted about the blog, but nothing too drastic. Now that I’ve got some more time on my hands, I hope to knock out some changes I’ve prioritized and make this a proper frontend playground.

\n

Till next time!

\n", "date_published": "2021-04-01T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/native-form-validation-with-javascript/", "url": "https://www.falldowngoboone.com/blog/native-form-validation-with-javascript/", "title": "Native form validation with JavaScript", "content_html": "

You don’t need to install a validation library to create rich client-side form validation experiences. HTML5’s native client-side form validation is widely-supported and easy to implement, and while its default functionality is limited, the native Constraint Validation API allows for custom behavior with JavaScript.

\n

Enter the humble login form

\n

Let’s build a login form. We’ll use an input for email, password, and a submit button:

\n
<!-- login.html -->

<form id=\"login-form\" action=\"/api/auth\" method=\"post\" >
  <div>
    <label for=\"email\">Your Email</label>
    <input id=\"email\" type=\"email\" name=\"email\" />
  </div>
  <div>
    <label for=\"password\">Your Password</label>
    <input id=\"password\" type=\"password\" name=\"password\" />
  </div>
  <div>
    <button>Log In</button>
  </div>
</form>
\n

That’s a pretty bare-bones login form. There are two inputs, one with a type of email, the other with a type of password, and a submit button. The form posts to an endpoint that handles the login process on the server[1].

\n

Even though we haven’t yet done anything to the form, it already has some client-side validation built in, thanks to the email input. If you were to enter an invalid value into the email field and submit, you would see something like this (screenshot from Chrome):

\n

\"Chrome

\n

The browser has blocked the submission of data, focused the first invalid field, and now we see an error message describing the issue. We have email validation, and at no point did we type npm install and download half of all known JavaScript dependencies.

\n

There is a problem, though. If you submit with both fields left blank, the form submits as valid, but our backend script requires both fields.

\n

Requiring fields

\n

There’s an easy fix for the valid blank fields. Let’s add the required attribute to both the email and password inputs.

\n
<!-- login.html -->

<form id=\"login-form\" action=\"/api/auth\" method=\"post\" >
  <p>
    <label for=\"email\">Your Email</label><br/>
    <input id=\"email\" type=\"email\" name=\"email\" required />
  </p>
  <p>
    <label for=\"password\">Your Password</label><br/>
    <input id=\"password\" type=\"password\" name=\"password\" required />
  </p>
  <p>
    <button>Log In</button>
  </p>
</form>
\n

Now submitting without an email or password will look something like this (again, screenshot from Chrome):

\n

\"Chrome

\n

So far, so good. Who needs JavaScript?

\n

Styling error state

\n

You might want to style your error state to draw more attention to fields with issues. We can do that by using the :invalid CSS pseudo-class.

\n
/* login.css */

input:invalid {
  border-color: hsl(351, 100%, 27%);
}
\n

Now we see the first issue: HTML forms run validation immediately. By default, both the email and password fields are blank, and since they are required, they immediately render invalid. Boo!

\n

Ideally, we would want the fields to appear valid until a user attempts to enter a value. We could choose either to validate on blur or wait until the user tries to submit the form. Either way, we want to validate invalidated fields as their values update to ensure the quickest feedback possible.

\n

Sadly, we have reached the limits of default HTML client-side form validation. But fear not! We have access in JavaScript to all that validation goodness in the form of the aforementioned Constraint Validation API.

\n

Validation, final form

\n

The Constraint Validation API gives you complete access to the built-in validation we’ve been using up to this point but with more control. The first rule of Constraint Validation, much like Fight Club, is to not talk about validation:

\n
// login-validate.js

const form = document.getElementById(\"login-form\");

form.noValidate = true;
\n

Setting noValidate turns off the native client-side validation, freeing us up to do whatever we want. Turning off validation with JavaScript ensures the default validation still runs if JavaScript never executes for whatever reason. It also prevents showing our invalid style preemptively.

\n

The first thing we should do is run validation when the form is submitted. To validate the entire form, use the form method reportValidity:

\n
// login-validate.js

const form = document.getElementById(\"login-form\");

form.noValidate = true;

form.addEventListener('submit', function handleFormSubmit(event) {
  const isValid = form.reportValidity();

  if (isValid) {
    // POST form data to backend with fetch
  }

  event.preventDefault();
});
\n

reportValidity runs the form validation, returns true or false based on whether or not the form is valid, and reports any validation errors to the user. We can use the return value to determine whether or not to post to the backend.

\n

Marking invalid inputs

\n

Before taking the validation reins we could tie into the convenient :invalid pseudo-class to style invalid fields, but now that’s no longer an option. Let’s fix that next.

\n

When reportValidity runs, it will dispatch an invalid event for each invalid field. This event is cancellable, but it doesn’t bubble, which means we’ll have to register an event handler on each element in the form:

\n
// login-validate.js

// ...

for (const field of form.elements) {
  field.addEventListener(\"invalid\", function handleInvalidField(event) {
    field.setAttribute(\"aria-invalid\", \"true\");
  });
}
\n

This will add the aria-invalid attribute to invalid elements, which not only communicates validity state to accessible technology, it gives us a new hook for our invalid styles[2].

\n
/* login.css */

input:invalid,
[aria-invalid=true] {
  border-color: hsl(351, 100%, 27%);
}
\n

Whenever I can, I try to tie style to semantics. This helps communicate the importance of the selector’s existence and avoids unnecessary styles that may not be that reusable outside of the current context.

\n

The styles work now, but they remain even after the input becomes valid. Before we can correct that, there’s another problem we need to solve.

\n

Our new validation pattern

\n

We need to talk briefly about how we want this custom validation to work. Luckily for us, form error UX is well-researched. For this example, I’m referring to guidelines published by the Nielsen Norman Group.

\n

Here’s a quick summary of the plan:

\n\n

First I’ll add the validation on field blur. We’ll add that to our previous field level JavaScript:

\n
// login-validate.js

// ...

for (const field of form.elements) {
  // previous code
  field.addEventListener(\"invalid\", function handleInvalidField(event) {
    field.setAttribute(\"aria-invalid\", \"true\");
  });

  // new
  field.addEventListener(\"blur\", function handleFieldBlur() {
    field.removeAttribute(\"aria-invalid\");
    field.checkValidity();
  });
}
\n

When a field element dispatches a blur event, we optimistically remove the aria-invalid attribute and then run checkValidity, which does everything reportValidity does except report validation errors to the user. We’ll handle error reporting ourselves later.

\n

Next, we need to run validation on user input, but only after a field has been previously visited. For that, we’ll need some local state.

\n

Validating on user input

\n

For tracking fields that have been visited, we’ll use a simple JavaScript array. Once a field has been visited, we’ll push it into the array. To check for visited status, we query the array to see if the field is included.

\n
// login-validate.js

// ...

// new
const visited = [];

// ...

for (const field of form.elements) {
  // ...

  field.addEventListener(\"blur\", function handleFieldBlur() {
    // new
    if (!visited.includes(field)) {
      visited.push(field);
    }

    // REMOVED field.removeAttribute(\"aria-invalid\");
    field.checkValidity();
  });

  // new
  field.addEventListener(\"input\", function handleFieldInput(event) {
    if (!visited.includes(field)) return;
  
    if (!field.validity.valid) {
      field.setAttribute(\"aria-invalid\", \"true\");
    } else {
      field.removeAttribute(\"aria-invalid\");
    }
  });
}
\n

Here we have added a visited array and are adding fields to it inside handleFieldBlur. We’re also removing the aria-invalid attribute code since it’s now handled in the new input handler.

\n

Inside the input handler, we prevent validation from running before the field has been visited with a short circuit. We check the field’s validity using its ValidityState, which is a handy object that contains everything related to field validation. More on that in a bit.

\n

At this point, the desired validation behavior is done. The final thing we need to do is add custom error styling.

\n

Custom inline errors

\n

The current error messages only show up on a submission attempt and have the default tooltip styling. We want to show the errors directly underneath the invalid fields and update them on blur and user input. We need to first create containers for the error messages.

\n
<!-- login.html -->

<form id=\"login-form\" action=\"/api/auth\" method=\"post\" >
  <div>
    <label for=\"email\">Your Email</label>
    <input id=\"email\" type=\"email\" name=\"email\" 
          aria-describedby=\"email-error\" /> <!-- new -->
    <span id=\"email-error\"></span> <!-- new -->
  </div>
  <div>
    <label for=\"password\">Your Password</label>
    <input id=\"password\" type=\"password\" name=\"password\" 
          aria-describedby=\"password-error\" /> <!-- new -->
    <span id=\"password-error\"></span> <!-- new -->
  </div>
  <div>
    <button>Log In</button>
  </div>
</form>
\n

The important thing to notice in the above markup is we’ve added an aria-describedby attribute to both inputs. This attribute ensures that screen readers associate each error message with its respective input. When an invalid input is focused, the screen reader will announce the input’s label and type, pause briefly, then announce the error[3].

\n

We now need to populate the error containers with the appropriate error messages. Luckily the input fields have access to their validation messages:

\n
// login-validate.js

// ...

for (const field of form.elements) {
  field.addEventListener(\"invalid\", function handleInvalidField(event) {
    errorContainer(field).textContent = field.validationMessage; // new
    field.setAttribute(\"aria-invalid\", \"true\");
    event.preventDefault(); // new, prevents default validation errors
  });

  // ...

  field.addEventListener(\"input\", function handleFieldInput(event) {
    if (!visited.includes(field)) return;
  
    if (!field.validity.valid) {
      errorContainer(field).textContent = field.validationMessage; // new
      field.setAttribute(\"aria-invalid\", \"true\");
    } else {
      errorContainer(field).textContent = \"\"; // new
      field.removeAttribute(\"aria-invalid\");
    }
  });
}

// new
function errorContainer(field) {
  const errorContainerId = field
    .getAttribute(\"aria-describedby\")
    .split(\" \")
    .find((id) => id.includes(\"error\"));
  return document.getElementById(errorContainerId);
}
\n

Before we go any further, it looks like every time we set the error container text, we also set the aria-invalid attribute on the field. Let’s clean this logic up by moving it into a function.

\n
// login-validate.js

// ...

for (const field of form.elements) {
  field.addEventListener(\"invalid\", function handleInvalidField(event) {
    setFieldValidity(field); // function-ified
    event.preventDefault();
  });

  // ...

  field.addEventListener(\"input\", function handleFieldInput(event) {
    if (!visited.includes(field)) return;
    setFieldValidity(field); // here too
  });
}

// ...

// new
function setFieldValidity(field) {
  if (!field.validity.valid) {
    errorContainer(field).textContent = field.validationMessage;
    field.setAttribute(\"aria-invalid\", \"true\");
  } else {
    errorContainer(field).textContent = \"\";
    field.removeAttribute(\"aria-invalid\");
  }
}
\n

Here’s what our custom errors look like now when we try to submit with blank inputs (I’m adding the red “X” with CSS):

\n

\"Custom

\n

Better form validation

\n

At this point, there are some rough edges, but it’s working more or less as we want it to. One annoying thing is in Chrome validation messages get wordy. You can substitute a custom validation message based on the type of validation error is associated with the field. I’ll leave that as an exercise for you.

\n

This exploration only looked at required fields and email pattern validation, but there are a variety of validation criteria built into browser validation. Like the email input type, there are several other input types with built-in validation, as well as ways to limit the range or length of an input’s value, and a pattern attribute that gives you even more control over input validation for certain types of inputs.

\n

Keep exploring

\n

I hope this post has inspired you to explore the Constraint Validation API. Taking advantage of native APIs improves frontend performance and moves complex logic off of your plate. Use them whenever possible.

\n

Do you like Web APIs? What’s your favorite? Which one mystifies you? Let me know on DEV Community or Twitter. And if you enjoyed this post, let me know by liking it on DEV Community and giving me a follow.

\n

Until next time, keep exploring!

\n
\n
\n
    \n

  1. Our imaginary backend script also validates and sanitizes the data posted from the form. Client-side validation is a user experience enhancement. Never trust user-generated data and always validate on the server. ↩︎

    \n
    2. \n

  2. To learn more about ARIA attributes, roles, and relationships, check out the WAI-ARIA specification. ↩︎

    \n
    3. \n

  3. aria-describedby can take multiple IDs separated by spaces (aria-described="first-id second-id third-id"). This is helpful if you have instructions associated with an input, like password constraints. ↩︎

    \n
    4. \n
\n
\n", "date_published": "2021-03-27T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/hold-off-on-optimizing-javascript-performance/", "url": "https://www.falldowngoboone.com/blog/hold-off-on-optimizing-javascript-performance/", "title": "Hold off on optimizing JavaScript performance", "content_html": "

As a developer, I love optimizing performance. Learning efficient algorithms makes me feel like a software engineer. But performance is not the only developer concern, nor should it be the first or second. David K. Piano recently pointed this out on Twitter, offering up a suggested framework:

\n
\n

Make it work
\nMake it always work
\nMake it work for everyone
\nMake it right
\nMake it fast

\n
\n

David’s suggestion expands on a well-known programming maxim attributed to Kent Beck, Make it work, Make it right, Make it fast. What does that mean? I want to take some time to expand on each layer.

\n

Make it work

\n

Making working code is the first concern. This step may seem obvious, but there are a few things to consider as you make the code work.

\n

First, consider a test-driven development approach. At the very least, wrap your code in tests as you write. This will make the rest of the process faster and ensure you don’t break core functionality.

\n

Second, don’t worry about writing pretty code. If you find yourself debating what to name a variable, call it thing1 and move on. Use formatting tools like Prettier to avoid thinking about white space and semicolons.

\n

Finally, try to go fast here. You only need working code. If you hit a roadblock, start over. Writing sloppy code at the beginning can help you arrive faster at a better solution.

\n

Make it always work

\n

Now we shift our attention to edge cases, cases involving less-common or unique data sets. These are the areas where bugs tend to show up. Here are some scenarios you might want to consider:

\n\n

If your code involves asynchronous calls:

\n\n

Again, take the time to write tests. Whether you follow test-driven development or write tests after the fact, they will be invaluable as you move up the layers of concerns.

\n

Make it work for everyone

\n

JavaScript is a funny language in that you can never be sure of the execution environment. Identify your feature’s core functionality and make sure it works in a wide variety of browsers. Having a list of your code’s official browser support helps in this step.

\n

There are two approaches to supporting multiple environments: progressive enhancement and graceful degradation. Both involve detecting feature support, but progressive enhancement adds functionality while graceful degradation removes functionality.

\n

Both approaches are viable in different scenarios, and which you use depends on the context of the functionality.

\n

Make it right

\n

The next layer of focus is making the code right. Right means making the code readable and maintainable. All of the tests written up to this point pay off by giving you confidence that functionality remains.

\n

Developers read code much more than write it, so taking the time to make your code readable will help your colleagues and your future self. Readable code is more maintainable and extendable. The small cost of refactoring now can have an exponential impact on future project development.

\n

Focus on small changes that make a noticeable impact. Use domain-specific variable names, ensure your functions are in the correct scope, use comments as indicators for creating functions. I recommend reading Martin Fowler’s excellent book Refactoring for more specific guidance and practical advice.

\n

Make it fast (if needed)

\n

After we’ve made the code work, considered edge cases, added fallback support, and made the code readable, we finally optimize performance. Maybe.

\n

The first rule from the Rules of Optimization is don’t optimize. If you must optimize, however, there are a few things to keep in mind.

\n

First, make sure you are testing production code. Many frameworks bolt-on functionality and tools that help the development process but hinder performance. Production builds exclude this extra functionality, so ensuring you are testing in the right environment keeps you from optimizing performance unnecessarily.

\n

Next, you need to get baseline measurements. These will ensure that your optimizations worked. If possible, emulate slow internet connections and throttle CPU speed, two features Chrome’s devtools offers.

\n

One thing to keep in mind as you optimize is how your optimizations may affect the readability and maintainability of code. Usually, the most optimized solution is nowhere near the most readable. Always favor readable code.

\n

Summary

\n

Performance optimization makes sense to developers because it’s something that’s easily measured. Optimizing code may be a more attractive goal than finding edge cases or making code more readable but should be avoided until the end of the process. Optimizing at the very end forces developers to focus on writing working, maintainable code.

\n

So, thanks for making it to the end! If you found this helpful, please let me know by liking this article on DEV Community and following me to know when I post a new article. And ask me all the questions you’d like (preferably about this article, but no judgment) on Twitter.

\n

Until next time!

\n", "date_published": "2021-03-10T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/what-i-learned-blogging-daily-for-a-month/", "url": "https://www.falldowngoboone.com/blog/what-i-learned-blogging-daily-for-a-month/", "title": "What I learned blogging daily for a month", "content_html": "

I recently challenged myself to write a blog post every day for a month. Up to that point, I had only written eight blog posts for two years. A month later, not only do I have 28 new blog posts, I’ve learned some valuable lessons about my blogging process and my website. I wanted to share things about the experience that worked for me and issues I discovered that need attention.

\n

Worked: Setting deadlines

\n

It’s surprising how an unmoving date can motivate you to complete a post. One of my recurring issues with blogging has been the tendency to overwork a piece until I completely lose interest. Experience has taught me that time is the biggest enemy of posting, and firm deadlines force you to throw away what’s not working and focus on what is.

\n

Being accountable to others dramatically increases the power of deadlines. One of my blogging rules involved announcing in my Twitter feed that I was posting daily. In my mind, I felt like I was accountable to a large audience. Social pressure works, even if it’s imaginary[1].

\n

Worked: Having a healthy backlog

\n

In the middle of February, we experienced the second coldest temperatures ever recorded in North Texas (-2℉, -17℃). That may not be cold for some of you reading this, but our state’s infrastructure is poorly prepared for temperatures that cold. Power generation froze up, and several utility buildings lost power, including our water station. Some were without power and water for a week.

\n

I barely wrote during that week, yet I stayed on schedule thanks to my backlog, a running list of ideas in Notion that I use to build out full posts. Sometimes an article I’ve been working on just isn’t working, so it’s nice to have a safety net.

\n

Worked: Cross-publishing on DEV

\n

I decided at the suggestion of Stephanie Eckles to cross-publish to DEV Community. Cross-publishing ended up being a great decision because DEV’s platform exposed me to a bigger audience than I ever would’ve received on my blog. Coupled with the motivation and encouragement I received from comments and reader interaction, I’ve decided to continue doing this for all posts.

\n

There are, however, some challenges I’ve found cross-publishing, mainly due to differences in platforms. My site is built in Eleventy, and my front matter formatting doesn’t completely align with DEV’s. There are also differences in how I mark up embedded content. If you notice, hardly any of my posts have CodePens embedded, and I didn’t use any images.

\n

Now that I have some time, I’m going to start ironing out these issues, starting with images. That’s a topic I need to address on my site first, which brings me to my first thing that didn’t work.

\n

Did not work: My website styling is lacking

\n

In terms of my blog, falldowngoboone, I discovered many rough edges throughout the month. One such issue that comes to mind is an excerpt filter I created[2], which unfortunately doesn’t process Markdown properly. If anything in the first 20 words of a post contains Markdown, it’s not processed, and if there are any special characters, they are escaped.

\n

It also appears some of the code blocks that Notion produces use a syntax I don’t support. I know that may not seem like a big deal, but it’s broken syntax highlighting on my site. This should be an easy fix.

\n

Finally, my home page needs an overhaul. When I had only eight posts, it was easy to find them. Now, it’s getting a bit ridiculous. I plan to completely change the homepage design, featuring the most popular articles, my most recent posts, and a link to post archives. I may even add a search (gasp!) at some point.

\n

Did not work: My publishing process sucks

\n

Near the end of the month, I wrote about how I write my posts, and I briefly mentioned some ideas I had for optimizing my publishing flow. Currently, I walk through at least 18 different steps to publish a single blog piece. I think better tools and well-planned automation can reduce those steps.

\n

Notion, as I’m currently using it, doesn’t fit with my publishing process. Unfortunately, its exported Markdown output doesn’t align with the format I use in Eleventy. It would be nice if Notion offered a way to tweak the export formats, but I understand that constraints like this are necessary to allow flexibility in other areas.

\n

One idea I have is to write a script that could convert the exported metadata into front matter. Another idea is to change to a full content management solution, like Sanity. Scripting a solution would mean I could keep using Notion, with the downside of maintenance. Using Sanity would give me a streamlined publishing solution with little toil. I’m still weighing my options here (and I’ll make sure to write about whatever choice I make).

\n

Finally, there are areas of my process best suited for automation. My article backlog includes a status flag (Planned, In Progress, and Published[3]). I’d love to figure out a way to automate In Progress when I schedule the piece and Published once the post has merged.

\n

What next?

\n

I will not continue to blog daily, as insightful as it’s been. But I will focus on creating blog posts at a regular frequency, at least once a week. I hope to improve my communication skills and connect with more amazing people through DEV Community.

\n

Finally, if you’re thinking about blogging, do it. Don’t worry about whether or not you have something to say. When I began blogging, I was afraid I wouldn’t have anything to say. Now I can’t stop writing.

\n

That’s it for now. If you found this helpful, please let me know by liking this post on DEV Community and following me so you know when I publish. And if you have any questions, don’t hesitate to reach out to me on Twitter.

\n

Until next time!

\n\n

In case you’re interested, here are my most popular articles from February:

\n
    \n
  1. How to avoid premature abstraction in React
    2. \n
  2. Share variables between JavaScript and CSS
    3. \n
  3. How I write my posts
    4. \n
\n
\n
\n
    \n

  1. If you’d like to learn more about different techniques to help you become consistent at blogging or any other habit, check out Atomic Habits by James Clear. ↩︎

    \n
    2. \n

  2. In case you didn’t know, fdgb runs on Eleventy, a JavaScript-based static site generator that’s a joy to use. Filters in Eleventy act like functions that can transform your blog’s content. They are simple yet powerful. ↩︎

    \n
    3. \n

  3. I’m not completely happy with these names, but they work for now. ↩︎

    \n
    4. \n
\n
\n", "date_published": "2021-03-04T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/share-variables-between-javascript-and-css/", "url": "https://www.falldowngoboone.com/blog/share-variables-between-javascript-and-css/", "title": "Share variables between JavaScript and CSS", "content_html": "

Whether you need site breakpoints for matchMedia or access to theme colors, sharing values between your JavaScript and CSS is sometimes unavoidable. The easiest solution is to copy and paste values, but how can you ensure values stay synchronized when that brand blue color changes to indigo?

\n

The answer is to create a single source of truth by sharing values between the JavaScript and style layers. There are several ways to accomplish this, and the best approach for a project depends on its frontend stack. Here are all of the ways I know how to pass data back and forth between all the layers.

\n

ICSS

\n

CSS Modules, gives us two ways of sharing variables, the Interoperable CSS (ICSS) spec and the PostCSS Modules Values spec. ICSS appears to be the older of the two specifications, so I’ll start there.

\n

ICSS is a low-level specification that’s mainly for loader authors. It describes how to treat CSS modules as JavaScript dependencies and introduces the :export directive to act as a way to export defined values. Coupled with Sass variables, it allows you to export theme values:

\n
// colors.module.scss
// assuming this is within Create React App; the `.module` lets CRA know
// this is a CSS Module

$my-red: #ff0000;

:export {
  myRed: $my-red;
}
\n

The exported values are imported like much like any other JavaScript module:

\n
// MyComponent.js
// assuming this is within Create React App

import * as React from 'react';
import * as colors from 'theme/colors.module.scss';

export function MyComponent() {
  return <p>myRed's value: {colors.myRed}</p>
}
\n

The above should work in Create React App out of the box. If you are rolling your own Webpack configuration (may God have mercy on your soul), you’ll need to configure modules with a compileType of icss:

\n
module.exports = {
  module: {
    rules: [
      {
        test: /\\.css$/i,
        loader: \"css-loader\",
        options: {
          modules: {
            compileType: \"icss\",
          },
        },
      },
    ],
  },
};
\n\n

Setting @value

\n

CSS Modules also offers the @value directive, which explicitly defines module values. @value can also be used to import values from other CSS modules. It’s a catchall solution for passing values to and from CSS modules to anywhere.

\n
// breakpoints.module.css

@value larry: (max-width: 599px);
@value moe: (min-width: 600px) and (max-width: 959px);
@value curly: (min-width: 960px);

// MyComponent.module.css
// this is one of the multiple ways you can import @value definitions
// see https://github.com/css-modules/postcss-modules-values

@value larry, moe, curly from \"theme/breakpoints.module.css\";

@media larry {
  ...
}

@media moe {
  ...
}

@media curly {
  ...
}
\n
// MyComponent.module.js

import * as React from 'react';
import Media from 'react-media';
import { larry, moe, curly } from 'theme/breakpoints.module.css';

export function MyComponent() {
  return (
    <Media queries={{ larry, moe, curly }}>
      {matches =>
        matches.larry 
          ? (
            <p>Oh, a wise guy, eh?</p>
          ) 
          : matches.moe ? (
            <p>Why I outta...</p>
          ) : (
            <p>Nyuk nyuk</p>
        )
      }
    </Media>
  );
}
\n\n

Sass compiler

\n

Sass’s JavaScript API can add custom functions by defining the functions option of render. You can use this to define getter functions that return your theme’s values directly in Sass. I implemented this on our website using node-sass, which exposes the functions option in its CLI:

\n
node-sass src/styles/ -o build/styles --functions path/to/sass-functions.js
\n

And the sass-functions.js file looks like this:

\n
// sass-functions.js

const sass = require('node-sass');
const theme = require('../theme/index.js');

module.exports = {
  'getColorMap()': function () {
    return Object.entries(theme.colors).reduce(
      toSassMap,
      new sass.types.Map(Object.keys(theme.colors).length)
    );
  },
  'getMqMap()': function () {
    return Object.entries(theme.mqs).reduce(
      toSassMap,
      new sass.types.Map(Object.keys(theme.mqs).length)
    );
  },
};

function toSassMap(list, [key, value], idx) {
  list.setKey(idx, new sass.types.String(key));
  list.setValue(idx, new sass.types.String(value));
  return list;
}
\n

Note that I’m having to define Sass types. The getColorMap() and getMqMap() functions return Sass maps that include all of our theme variables. Very handy!

\n

Unfortunately, LibSass, the core engine of node-sass, has been deprecated, along with node-sass. The canonical Dart version of Sass lacks a nice CLI option for custom functions. If you want to recreate this functionality, you’re stuck building a compiler using Dart Sass’s JavaScript API.

\n\n

CSS-in-JS

\n

A common variable sharing solution in React is to simply let JavaScript do all the work. And as controversial as CSS-in-JS seems to be, it presents an easy way to share variables simply because you are defining CSS in a JavaScript file.

\n

Here’s how you might share a variable in the library Emotion:

\n
import { css, cx } from '@emotion/css';
import * as colors from './theme.colors.js';

render(
  <div
    className={css`
      color: ${colors.primary};
      &:hover {
        color: ${colors.secondary};
      }
    `}
  >
    I get so emotional, baby.
  </div>
)
\n

I mean, it’s easy. It’s so easy that I’d debate whether or not this is classified as sharing variables between JavaScript and CSS, but I’m throwing it in anyway.

\n

I’ve already mentioned Emotion, but other CSS-in-JS libraries to check out include Styled Components, JSS, Theme-UI, Radium, and Aprhodite.

\n\n

Custom Properties

\n

If you need a lightweight, “proper” way to share variables between JavaScript and CSS, look no further than Custom Properties. Custom Properties allow you to create arbitrary CSS properties and set them to any value you want.

\n
:root {
  --color-brand: #BADA55;
  --color-secondary: #005DAB;
}
\n
import * as React from 'react';

function MyComponent() {
  const brandColor = getComputedStyle(document.documentElement)
    .getPropertyValue('--color-brand');
  
  return <p style={{ color: brandColor }}>I'm brand color!</p>
}
\n

If you access these properties a lot, you may want to create a utility function to save on typing:

\n
function cssValue(property) {
  return getComputedStyle(document.documentElement)
    .getPropertyValue(property);
}
\n

Custom Properties are completely standard CSS spec, and this is the only solution that is dynamic, meaning properties can change based on context:

\n
:root {
  --color-brand: #BADA55;
  --color-secondary: #005DAB;
}

@media (prefers-color-scheme: dark)
  :root {
    --color-brand: white;
    --color-secondary: #ccc;
  }
}
\n

When you access those properties, they’ll be different depending on the user’s preferences. This is incredibly powerful.

\n\n

Lots of options

\n

Sharing variables between CSS and JavaScript can help reduce toil and cut down on unintentional tech debt. And if you need to, you have no shortage of options. Just make sure you understand what you want to act as the source of truth and know your technical requirements.

\n

If you found that helpful, please let me know by liking this post on DEV Community and sharing it. And if you want more articles like this, make sure you follow me on Twitter so you’ll know when I post new ones.

\n

Until next time!

\n
\n
\n
    \n

  1. Trust me when I say you should not use node-sass. It’s so buggy that it can’t process newer CSS. ↩︎

    \n
    2. \n
\n
\n", "date_published": "2021-02-28T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-i-write-my-posts/", "url": "https://www.falldowngoboone.com/blog/how-i-write-my-posts/", "title": "How I write my posts", "content_html": "

I’ve been posting a new article every day this month, and it’s been interesting. I’ll write about that soon, but today I want to share how I put these posts together. Hopefully, you’ll learn something new from my process, or see how terrible my process is and give me some advice.

\n

Idea backlog

\n

If you’re going to create content, you need a steady stream of ideas. I keep a backlog so I can store notes, write drafts, and constantly reassess what to post next. This post you’re reading? It started out in my backlog.

\n

You can keep an idea backlog in whatever tool you use. I use Notion for a few reasons. First, I can access Notion on anything that’s connected to the internet, so I can capture an idea before I forget it. Second, Notion gives me the flexibility to organize my content however I want.

\n

For Blogruary, I created a special post in Notion with a list view of all posts tagged “blograry” (each view can have its own special filtering and sorting). This allows me to get a quick look at all the ideas available to me.

\n

For more information on using Notion as a project manager, check out this Notion masterclass video from Thomas Frank.

\n

Writing the post

\n

After adding an idea to the backlog, I paste links to relevant material as well as notes into the created entry. This eventually becomes the blog post itself. Depending on how far along the information is, I’ll go ahead and schedule the publish date.

\n

If I’m being honest, this process has been all over the place. Sometimes I’ll start the post without any notes, or the post is a long list of notes until the day I have to post. Many times I’m stuck writing and editing the entire post the day I’m supposed to publish (like today).

\n

I’ve also noticed some issues with writing blog posts in Notion, mainly because of all the manual changes I have to make to the exported Markdown. I’m still trying to figure this part of the process out.

\n

Publishing

\n

After I’ve written a post, I’ll export it from Notion as Markdown, drop it into my blog’s source code, and manually format the front matter for Eleventy. Unfortunately, Notion doesn’t output front matter, nor does it allow me to customize how associated data is displayed. This would be a welcome feature.

\n

I’ve started to run the post content through Grammarly to correct any grammar mistakes. Grammarly has extensions for all the major browsers, as well as a desktop app that allows you to create a new document for analysis (big thanks to Stephanie Eckles for that tip). It’s free to use the basic features, but I’m considering upgrading.

\n

After making corrections in Grammarly, I’ll paste the corrections back into the Markdown file in VS Code, commit the changes, and push them up to GitHub.

\n

After creating a pull request, Netlify runs a series of checks. While that happens, I create a duplicate of the post on DEV Community. I have to add a canonical URL back to my website so I don’t get penalized for duplicate content, but in order to do that, I need to publish on my personal blog first.

\n

By the time I’ve set up a draft in DEV, my pull request has been verified and is ready to merge. The merge kicks off a deployment to Netlify (yay Netlify!). After merging, I grab the post’s URL, add it to the DEV post, then I hit publish.

\n

Thoughts on the process

\n

So that’s what I’ve been doing this entire month. I learned that Notion is a great tool for organizing and writing, but I need a tool that’s closer to the end product. I’m starting to look at Sanity as a viable option.

\n

I’ve also been thinking about streamlining the publishing process by automating the duplicate post to DEV. Challenges include differences in front matter and markup. If I can limit myself to only shared markup, that would make the automation much easier.

\n

Finally, if you’re thinking about starting a blog, a good place to start is signing up for the Blogging for Devs newsletter from Monica Lent. New subscriptions start with a 7-day blogging course sent directly to your inbox, followed by regular emails filled with tips for content makers.

\n

I will be expanding on the rest of what I’ve learned in a future post, so if you want to know when that comes out, follow me on Twitter. And if you found this post helpful, please let me know by liking it on DEV Community.

\n

Until next time!

\n", "date_published": "2021-02-27T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/understand-the-context-of-code-you-copy/", "url": "https://www.falldowngoboone.com/blog/understand-the-context-of-code-you-copy/", "title": "Understand the context of code you copy", "content_html": "

If a problem is too difficult to solve on our own, sometimes the only course of action is to search, copy, and paste. It’s something all developers have done regardless of their experience level.

\n

While there is no shame in copying and pasting code, it can lead to a mess. That’s why I have one copy-paste rule that I follow: understand the context.

\n

A reason for everything

\n

Requirements, constraints, and assumptions all play a role in how we write code. Unless you’ve found a generic solution, the code you copy comes with a context that may not apply to your situation.

\n

The wrong context could cause you to miss story requirements or cause other code to break (e.g. variable name collisions). Taking time to understand the context can help save you and your teammates a headache down the road.

\n

Learning the context

\n

Throughout my experience of dealing with copied and pasted code, I’ve seen a few common problems. These can be avoided by asking yourself some questions as you carefully read the code.

\n\n

This looks like a lot of work

\n

You may be thinking, Geez, Ryan, this sounds like it’s going to take forever, and the reason I’m copying and pasting code is to save time. And you’re right, this will add time to your solution. But that extra time will ensure that you solve the right problem, meet requirements, and reduce tech debt.

\n

Copying existing code can supercharge your team’s velocity, but remember this comes with a cost. If you don’t slow down and ask questions, chances are you’ll pay the price further down the road, and you’ll lose any short-term gains over the long term.

\n

Take the time to save time

\n

Sometimes copying and pasting existing code is the best course of action. But before do, take the time to understand and adapt the context. The time you spend will save you in the long run.

\n

If you’re still reading this, thanks for sticking around to the end! Unless you just skipped to the end. In which case, thanks for at least reading this? If you found this post helpful, please consider liking over on DEV Community, and make sure you follow me so you know when I release a new post.

\n

Until next time!

\n", "date_published": "2021-02-26T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/13-fantastic-web-development-blogs/", "url": "https://www.falldowngoboone.com/blog/13-fantastic-web-development-blogs/", "title": "13 fantastic web development blogs", "content_html": "

There are some amazing web development blogs out there (Smashing Magazine, CSS-Tricks and Codrops come to mind), but today I want to pay homage to the humble personal blog. Here are some of my favorite web developer blogs in no particular order:

\n\n

Didn’t see your favorite? Please let me know on Twitter who I need to add. And if you just discovered a new blog to follow from this post, please let me know by liking this on DEV Community. Likes, much like food, sustain me and give me the strength I need to face the day.

\n

Until next time!

\n", "date_published": "2021-02-25T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-to-get-your-pull-request-merged/", "url": "https://www.falldowngoboone.com/blog/how-to-get-your-pull-request-merged/", "title": "How to get your pull request merged", "content_html": "

When I started my first job as a professional developer, one of my biggest challenges was learning how to create helpful pull requests. I had been using git for a few years at that point, but my experience was limited to merging and pushing directly to the default remote branch. As a result, my first code reviews were fraught with answering questions, rewriting code, and (gulp) interactive rebasing.

\n

What follows is what I’ve learned from the past few years of crafting pull requests. My hope is they’ll help you whether you’re starting your first job in development or trying to contribute to your favorite open source project.

\n

Use atomic commits

\n

Effective pull requests start with atomic commits. Atomic commits add value, don’t break tests, and are the smallest unit of work possible. A list of such commits may look something like this:

\n\n

Each step in that list focuses on a particular domain of the overall task of adding product metadata, first the markup, then the CSS, and finally the behavior.

\n

Why use atomic commits? First of all, they’re easier to read in a code review (more on that in a minute). Second, since they’re self-contained, they’re easy to revert without breaking anything.

\n

Now that we have well-structured commits, we need to think about the commit message.

\n

Follow commit message standards

\n

As anyone who has ever plugged a lamp in a wall can tell you, standards are important[1]. Different projects may have different commit message standards. Make sure you read and understand them before you contribute.

\n

If you can’t find any standards, here’s a great article on how to write commit messages. My work more or less follows these standards. Here’s a high-level summary:

\n\n

And here’s an example commit following these guidelines:

\n
Add new awesome feature

Use this space for anything that needs further explanation. You can 
add a list here as well:

- Added the thing
- Had to pull the other thing out into a separate module for reasons
\n

It’s hard to know what your line character count is when staring into the black abyss of the terminal so you may want to change your default text editor to something you’re more comfortable with. I personally like to use VS Code as my editor:

\n
git config --global core.editor \"code --wait\"
\n

Running that command in your terminal should set up VS Code as the default git editor. The above command assumes you’re using git as your version control and have the VS Code CLI installed.

\n

Keep it short and sweet

\n

I cannot tell you how many pull requests I’ve personally submitted with 20+ files changed and thousands of lines touched[2]. If you’ve ever tried reviewing a PR like that, you’ll know how exhausting it is to simply read the entire thing, let alone reason about what’s going on.

\n

Pull requests should be kept short. If they can’t be kept short, use atomic commits and make sure to arrange your commits in a way that logically tells a story.

\n

Let’s imagine we need to add a new form to a project that uses existing logic. The commit history might look something like this:

\n
Reformat file to match standards
Refactor variable names for readability
Refactor form submission to extract logic
Add form markup
Style form
Share form logic with the new form
\n

This history is arranged to tell a story. The beginning sets up the change with some reformatting and refactoring of existing files. The middle adds and styles the new form. Finally, the previous work is combined to complete the functionality.

\n

Review and clarify if necessary

\n

Your commits are atomic, you’ve followed the project’s standards, and you’ve arranged your commits in a logical order. The next step is to push your code up to the remote repository and review your pull request. I will usually save my pull request as a draft on GitHub at this stage.

\n

After posting a draft pull request, step through each commit, look through the changes, and ask yourself if any potential areas could cause a reviewer to get tripped up. I recommend taking a break before so you can have fresh eyes.

\n

If you find any trip hazards, add a comment to explain why you did what you did. If you can’t explain why you did what you did, this is a good time to say so and ask for any suggestions. These comments give reviewers much-needed context to help inform the review.

\n

Listen to the reviewer

\n

The final step to getting your pull request merged is listening to the reviewer. This can prove challenging sometimes, especially if the reviewer has difficulty communicating in a cordial manner (every team has that one dev…). Aim to receive and consider every comment with equal respect.

\n

Even if you disagree with the comment or request, there is always value in re-examining what you’ve written from someone else’s perspective. That doesn’t mean you should blindly do what the reviewer is suggesting. Sometimes it helps to get a second opinion.

\n

I have had to remind myself not to take each comment personally. In a discussion with Chantastic at a local meetup, he suggested to hold off replying to a review until you can start with “Thank you.” This will help put you in the right frame of mind when responding to a particularly harsh review.

\n

In summary and summation

\n

Creating helpful pull requests is a useful skill to develop, whether you’re contributing to a team or open source software. Creating atomic, standards-based commits in a reasonable order and taking the review process seriously will get you a long way to getting that new feature merged.

\n

If you’d like more information on how to make your pull requests the best they can be, check out the Creative Commons PR guidelines. And if you found this post helpful, please let me know by liking it over on DEV Community, and follow me on Twitter for random thoughts and occasional blog updates.

\n

Until next time!

\n
\n
\n
    \n

  1. True story. Did you know there are 15 different outlet plug design standards in use throughout the world today? ↩︎

    \n
    2. \n

  2. Let me assure you karma is a thing. ↩︎

    \n
    3. \n
\n
\n", "date_published": "2021-02-24T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/talk-to-your-react-components-with-custom-events/", "url": "https://www.falldowngoboone.com/blog/talk-to-your-react-components-with-custom-events/", "title": "Talk to your React components with custom events", "content_html": "

I build pages with both React and non-React components, and sometimes all these components need to talk to each other. Examples include opening a React modal when a customer clicks a button or updating a text block when a customer adds a product from a React stepper. There are many ways to do this, but in my opinion, the best way is to use custom events.

\n

What are custom events?

\n

Custom events are just like regular browser events (e.g. “click”, “keyup”, etc.) except they’re manually created. You can create a simple synthetic event with a custom type using the Event constructor[1]:

\n
const event = new Event('build');
document.dispatchEvent(event);
\n

If you need to pass arbitrary data, you can use the CustomEvent interface[2]:

\n
const customEvent = new CustomEvent('build', { detail: { name: 'primary' } });
document.dispatchEvent(customEvent);
\n

I use the document element as the single event handler for all custom events because it centralizes all event methods and decouples custom events from specific nodes on the page.

\n
document.addEventListener('build', function({ detail }) {
  const { name } = detail;
  ...
}
\n

Using a single entity to manage events makes this approach act like a browser-native publish-subscribe pattern. Benefits to this pattern include decoupling (previously mentioned) and scalability.

\n

Example time!

\n

I’ve built an example app with Create React App to illustrate this. The App component includes a modal built with React Modal:

\n
// App.js

import * as React from \"react\";
import Modal from \"react-modal\";
import \"./style.css\";

export default function App() {
  const [isOpen, setIsOpen] = React.useState(false);

  function closeModal() {
    setIsOpen(false);
 }

 return (
   <div>
    <h1>Trigger modal outside React</h1>
    <p>Custom events are AWESOME!</p>
    <Modal isOpen={isOpen} onRequestClose={closeModal}>
      <p>I was opened by a modal outside of React. How cool is that?</p>
      <button onClick={closeModal}>Close</button>
    </Modal>
  </div>
 );
}
\n

The isOpen prop determines the Modal component open state. We then control this state using the useState hook.

\n

We will create a button outside of the React component that opens the React app modal. Let’s add the button to the page:

\n
<!-- public/index.html -->

<!-- ... -->
<button id=\"open-button\">I'm outside React</button>
<div id=\"root\"></div>
<!-- ... -->
\n

To make things a bit easier and reduce event boilerplate, I’ve put our event functions into a module:

\n
// events.js

function on(eventType, listener) {
  document.addEventListener(eventType, listener);
}

function off(eventType, listener) {
  document.removeEventListener(eventType, listener);
}

function once(eventType, listener) {
  on(eventType, handleEventOnce);

  function handleEventOnce(event) {
    listener(event);
    off(eventType, handleEventOnce);
  }
}

function trigger(eventType, data) {
  const event = new CustomEvent(eventType, { detail: data });
  document.dispatchEvent(event);
}

export { on, once, off, trigger };
\n

You could go crazy and make this look more like traditional pub-sub implementations[3], or you could completely emulate the EventEmitter interface if you want. Here I’ve tried to capture the most common functions.

\n

Now that we have all the pieces in place we need to wire everything up.

\n

Putting it together

\n

The next step is to publish an event when the open button is clicked. For this example app, I’m going to do that in the index.js file Create React App provides:

\n
import React from \"react\";
import ReactDOM from \"react-dom\";
import { trigger } from \"./events\";

import App from \"./App\";

const openButton = document.getElementById(\"open-button\");
openButton.addEventListener(\"click\", function() {
  trigger(\"openButton:click\");
});

ReactDOM.render(<App />, document.getElementById(\"root\"));
\n

I’ve named the event openButton:click. I typically follow a pattern of subject:verb, mainly because that’s what I learned way back in my jQuery days. A nice benefit of this pattern is it reduces the possibility of event name collisions.

\n

Finally, we’ll listen for that event inside the App component and set the isOpen state to true when it’s triggered. Since adding event listeners is a side effect, we’ll use useEffect to do that.

\n
import * as React from \"react\";
import Modal from \"react-modal\";
import { on, off } from \"./events\";
import \"./style.css\";

export default function App() {
  const [isOpen, setIsOpen] = React.useState(false);
  const openModal = React.useCallback(() => setIsOpen(true), []);

  React.useEffect(() => {
    on(\"openButton:click\", openModal);

    return () => {
      off(\"openButton:click\", openModal);
    }
  }, [openModal]);

  function closeModal() {
    setIsOpen(false);
  }

  return (
    <div>
      <h1>Trigger modal outside React</h1>
      <p>Custom events are AWESOME!</p>
      <Modal isOpen={isOpen} onRequestClose={closeModal}>
        <p>I was opened by a modal outside of React. How cool is that?</p>
        <button onClick={closeModal}>Close</button>
      </Modal>
    </div>
  );
}
\n

And now it works (hopefully)! You can test it for yourself over on StackBlitz.

\n

Update 2021-12-12

\n

Many thanks to Johnny Pribyl for rightly pointing out that the useEffect needed a clean up function returned, otherwise a new listener would be added every single time the modal was rendered. useEffect also needs a dependency array to ensure it isn’t needlessly re-run. openModal shouldn’t change, but there’s always the possibility that a new dependency may be added to that useCallback.

\n

Custom events are awesome indeed

\n

Custom events are great when you need two completely separate entities to talk to each other, which is a common problem in UI design. Be aware, though, this pattern’s not all sunshine and rainbows. Drawbacks include an increased difficulty of maintenance (ghost events, or published events that are no longer listened to) and a higher degree of reasoning (indeterminate order of execution).

\n

I hope I’ve at the very least piqued your interest in custom events, and maybe even given you a solution to a problem you’re dealing with right now. If that’s you, please do me a favor and like this article on DEV Community. And while you’re at it, follow me on Twitter so I don’t get lonely.

\n

Until next time!

\n
\n
\n
    \n

  1. Note this code will not work in Internet Explorer (what does, amirite?). You will need to use the old-fashioned event constructor. ↩︎

    \n
    2. \n

  2. The CustomEvent constructor is also unsupported in Internet Explorer (whomp whomp). They are created the same way as Events, but initialize with initCustomEvent. ↩︎

    \n
    3. \n

  3. One addition could be a method to remove all event listeners for a particular event. You would need to manually track listeners in an object since there’s no way of directly accessing event listeners in native browser event handling. ↩︎

    \n
    4. \n
\n
\n", "date_published": "2021-02-23T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/tips-for-vanilla-javascript-dom-manipulation/", "url": "https://www.falldowngoboone.com/blog/tips-for-vanilla-javascript-dom-manipulation/", "title": "Tips for vanilla JavaScript DOM manipulation", "content_html": "

If you need to go au naturale with your JavaScript DOM manipulation, here are some tips for improving performance.

\n

Use DocumentFragments to add multiple elements

\n

Here’s one way you might add multiple DOM nodes to a mounted node:

\n
var root = document.getElementById('fruit-list');
var fruitItems = ['apple', 'orange', 'banana'].map(function(fruit) {
\tvar item = document.createElement('li');
\titem.innerText = fruit;
\treturn item;
});

for (var i = 0; i < fruitItems.length; i++) {
\troot.appendChild(fruitItems[i]); // page reflows every time
}
\n

This code works, but the issue is the page will reflow every time appendChild is called. If you have a long list of items to add, you’re going to end up in a serious performance bottleneck, and an unhappy boss. The solution is to use a [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment):

\n
var root = document.getElementById('fruit-list');
var fragment = document.crateDocumentFragment();
var fruitItems = ['apple', 'orange', 'banana'].map(function(fruit) {
\tvar item = document.createElement('li');
\titem.innerText = fruit;
\treturn item;
});

for (var i = 0; i < fruitItems.length; i++) {
\tfragment.appendChild(fruitItems[i]); // no page reflow!
}

root.appendChild(fragment);
\n

The appendChild method is only called once, and this makes browsers (and my boss) very happy.

\n

But if you can, use ParentNode.append

\n

You can think of the [ParentNode.append](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/append) method as appendChild on steroids (sans the rage and adult acne). Unlike its puny cousin appendChild, append can take multiple nodes, automatically converts string arguments to text nodes, and it utilizes DocumentFragment for us:

\n
// the `consts` are my way of letting you know this is newer...🙃

const root = document.getElementById('fruit-list');
const fragment = document.crateDocumentFragment();
const fruitItems = ['apple', 'orange', 'banana'].map(function(fruit) {
\tconst item = document.createElement('li');
\titem.innerText = fruit;
\treturn item;
});

root.append(...fruitItems);
\n

This is the most convenient way to add multiple nodes to a parent node. Support is great if you don’t have to prop up Internet Explorer. Luckily, if you do, there’s a polyfill for that.

\n

Create DocumentFragments from strings with Ranges

\n

Imagine a world where you want to create HTML from a string. You might do something like this:

\n
// orange you getting tired of this example yet?

const root = document.getElementById('fruit-list');

root.innerHTML = `
\t<li>apple</li>
\t<li>orange</li>
\t<li>banana</li>
`;
\n

This is nice if you’re trying to recreate JSX, but it’s not as performant as using DocumentFragments. Luckily there’s a way to directly create a DocumentFragment from a string. Contrived code warning:

\n
const root = document.getElementById('fruit-list');
const fragment = document.createRange().createContextualFragment(`
\t<li>apple</li>
\t<li>orange</li>
\t<li>banana</li>
`);

root.appendChild(fragment);
\n

The createRange method returns a Range, which is a representation of a sliver of the current DOM document. The createContextualFragment creates a DocumentFragment using a parsing algorithm based on the current document’s context (in this case, HTML). Range methods are meant to be convenience methods built on top of common node editing patterns with optimization in mind, and I’m quite interested to learn more about them.

\n

Memorize the DOM properties that trigger layout

\n

The DOM API is tricky because just observing certain node properties can trigger page layout. Doing this multiple times in a row can be a performance problem. Doing this inside a loop can cause layout thrashing (trust me, it’s as bad as it sounds).

\n

You’ll want to be aware of what DOM properties cause the browser to trigger layout, so you need to get to memorizing. Or you could simply bookmark this convenient list of properties that cause layout.

\n

This is only scratching the proverbial surface

\n

There’s more to DOM layout with vanilla JavaScript, to be sure. I’m interested in looking at some of the performance optimizations VDOM libraries employ to eek the most out of DOM manipulation. I kinda like that sort of thing.

\n

I hope you learned something new today. And if you did, please consider liking this post on DEV Community, and let me know on Twitter. I get lonely sometimes.

\n

Until next time!

\n", "date_published": "2021-02-22T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/11-podcasts-for-the-frontend-developer/", "url": "https://www.falldowngoboone.com/blog/11-podcasts-for-the-frontend-developer/", "title": "11 podcasts for the frontend developer", "content_html": "

I’m a huge fan of continuing education, and one of the ways I binge on information is through podcasts. Here’s a list of 11 podcasts that I find not only educational but entertaining as well.

\n\n

Don’t see your favorite here? Let me know on Twitter. And if you found this post helpful, please let me know by liking it on DEV Community.

\n

Until next time!

\n", "date_published": "2021-02-21T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/what-is-your-code-communicating/", "url": "https://www.falldowngoboone.com/blog/what-is-your-code-communicating/", "title": "What is your code communicating?", "content_html": "

Developers don’t write code for computers. I mean, we do, but not primarily. If we did, it would make no difference whether we wrote in Java, bytecode, or complete binary. Yet when given a choice, we write in abstractions because developers write code for other developers.

\n

The Why? behind the What?

\n

Knowing this, you should always strive to lean into the abstraction and communicate why your code exists in the code itself. That is how you make self-documenting code[1].

\n

Let’s look at an example in Sass. If you’re unfamiliar with Sass, it’s a preprocessor scripting language that compiles to CSS. It’s a further abstraction of CSS built to make CSS more expressive.

\n

Imagine you come across this style in a code review:

\n
.subheading-2 {
  font-size: 1.5rem;
  font-weight: bold;
  line-height: 1;
  margin-top: 20 / 24 * 1em;
}
\n

Does anything jump out? You might ask why margin-top has an equation value (honestly, I’d prefer not to include a margin in this type of style; if you want to find out why reach out to me on Twitter).

\n

You can probably figure out what that line is doing, but it’s an unnecessary speed bump in the middle of an otherwise unremarkable piece of code. And as any good editor knows, anything that unnecessarily slows a reader down needs to be eliminated.

\n

Making the abstraction literally literal

\n

Let’s try making that margin-top a bit more readable:

\n
.subheading-2 {
  font-size: 1.5rem;
  font-weight: bold;
  line-height: 1;
  margin-top: 0.8em;
}
\n

You are less likely to get any questions about that. But I’m still bothered by one thing: 0.8em is a rather arbitrary value, and em units tend to be confusing, especially if you work on a team of developers that aren’t CSS-savvy.

\n

What I want to do is communicate that, at the effective font size of 24px (1.5rem), the margin-top should be 20px. You might be tempted to communicate this in a comment, which is easy to do in Sass:

\n
.subheading-2 {
  font-size: 1.5rem;
  font-weight: bold;
  line-height: 1;
  margin-top: 0.8em; // 20px in ems
}
\n

That certainly communicates what we’re trying to do, but comments like this one are tightly coupled to the code, meaning if the code changes, the comment needs to change as well. This could (and inevitably will) lead to stale comments.

\n

Back to the land of abstraction

\n

If you find yourself writing comments like this, a good rule of thumb is to use the comments as a template for abstraction[2]. Luckily for us, Sass gives us the ability to abstract this meaning into functions. A bit of searching on the interwebs leads me to a useful function to turn pixel values into em units.

\n

Let’s incorporate our new em function into our style:

\n
.subheading-2 {
  font-size: rem($px: 24);
  font-weight: bold;
  line-height: 1;
  margin-top: em($px: 20, $context: 24)
}
\n

Hey, look, I wrote a rem function, too! I would argue this better fits a developer’s mental model when translating redline documents into code. No math, and no confusion around what em’s context is.

\n

How to find opportunities for improved communication

\n

If you are writing the code, often you know too much about what you are doing to reliably recognize confusing lines. Use code reviews to help with this. A good reviewer will always ask questions, and these questions can help identify opportunities for abstraction[3].

\n

Even if you get a terrible code review fraught with nitpicks and complete rewrites (and apologies if you do), there is still some meaningful feedback you can take away. You can see where other developers get tripped up, allowing you to better identify problem areas[4].

\n

Communication is everywhere

\n

Your code is always communicating something, and it’s your job as a developer to make sure it’s communicating the right thing. This not only applies to Sass but to every coding language in existence, from HTML to Rust to whatever hot language the future gives us. Look for confusing lines of code, ask yourself why it exists, and lift that context into an abstraction.

\n

If you can’t tell, this is one of those subjects that I love. If you’d like to hear more about how to better communicate through code, please let me know by liking this article on DEV Community and sharing it with others. Also consider following me on Twitter, especially if you like rage tweets about local infrastructure and random tomfoolery.

\n

One last note: I learned this idea of code as communication from Jonathan Cutrell’s amazing podcast Developer Tea. Whether you’re a beginner or a seasoned pro, I highly recommend subscribing to this podcast. It focuses on the human side of development, a topic that is often ignored.

\n

Until my next communication!

\n
\n
\n
    \n

  1. There’s been some confusion over the meaning of the term self-documenting code, but my definition is code that’s readable and reasonable to other human beings. ↩︎

    \n
    2. \n

  2. This is a technique that I learned from Martin Fowler’s excellent book Refactoring. ↩︎

    \n
    3. \n

  3. The example in this post came from a real code review on my team. ↩︎

    \n
    4. \n

  4. Of course, if someone is a terrible code reviewer, not all of their feedback is going to point to actual problems. You’ll have to use your best judgment here, but it’s at least worth reassessing your choices. ↩︎

    \n
    5. \n
\n
\n", "date_published": "2021-02-20T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-to-avoid-premature-abstractions-in-react/", "url": "https://www.falldowngoboone.com/blog/how-to-avoid-premature-abstractions-in-react/", "title": "How to avoid premature abstractions in React", "content_html": "

As a junior developer, my number one problem was creating premature abstractions. Nowhere was this more evident than my React components.

\n

It started with an input

\n

I worked on a large project involving several form elements, so as part of bootstrapping on top of Create React App, I created some form components that wrapped around Formik. Here’s what the Input element looked like in use:

\n
<Input label=\"Full Name\" name=\"username\" id=\"username\" />
\n

The label, name, and id were all required, which was something I thought was clever to ensure proper input labeling. This component also automatically tied into Formik’s form validation and dynamically generated field errors when data was invalid.

\n

Then the tooltips showed up

\n

I had abstracted away all the complexity into a simple, useful API. I thought this was all we would need. But then a new design came through that required a tooltip to render inline with an input label.

\n

I wanted to keep the interface simple, so I added a tooltip component set to a string, which would become the child element of a Tooltip component alongside the label.

\n
<Input 
  label=\"Cell Phone\"
  tooltip=\"This is required for receiving texts.\"
  name=\"phone\"
  id=\"phone\"
  type=\"tel\"
/>
\n

Not that great, but it still looks manageable. But the variations kept coming. Some inputs needed a visible message. Others needed a special icon by the label.

\n

Enter render props

\n

I decided the best way to handle all these use cases was to extend the label prop to receive render props:

\n
<Input 
  label={({Label, labelProps}) => (
    <div>
      <Label {...labelProps}>Cell Phone</Label>{\" \"}
      <Tooltip>This is required for receiving texts.</Tooltip>
      <p>Cell phones are great, right?</p>
    </div>
  )}
  name=\"phone\"
  id=\"phone\"
  type=\"tel\"
/>
\n

Okay, not as simple as what we started with, but probably maintainable? Then I got even more variations in, this time around the input itself. Designs were calling for an inline icon, a separate button, dynamic images…so I made the input itself a render prop.

\n
<Input 
  label={({Label, labelProps}) => (
    <div>
      <Label {...labelProps}>Cell Phone</Label>{\" \"}
      <Tooltip>This is required for receiving texts.</Tooltip>
      <p>Cell phones are great, right?</p>
    </div>
  )}
  name=\"phone\"
  id=\"phone\"
  type=\"tel\"
>{({Input, inputProps, InputGroup, inputGroupProps}) => (
  <InputGroup {...inputGroupProps}>
    <Input {...inputGroupProps} />
    <IconButton variant=\"phone\" />
  </InputGroup>
)}</Input>
\n

I get panic sweats just looking at that. What is it? Why are there two types of Input? And what is the flow of props? This is not maintainable; it’s barely readable, especially when surrounded by more of these monstrosities!

\n

The example above is a small sample of the horror show this component became. It also had support for checkboxes and buttons. And as terrible as the API looked, the component’s code looked indecipherable. I’m not posting it here for fear of losing my developer card.

\n

Walking back the design

\n

If I had to do it all over again, I would’ve put off making a shared input component. Isolating components allows more real-world use cases to organically develop, leading to a better-informed API.

\n

I’ve since realized it’s much better to break up components into their atomic parts, which allows for more flexibility and composability. What do I mean by atomic? Something like this:

\n
<Field name=\"username\">
  <Label>Full Name</Label>
  <TextInput />
  <FieldMessage />
</Field>
\n

I’ve pulled all the field data out into a Field component, which uses context to build and pass all the necessary information into its children. The children themselves can either utilize the data passed in via a custom useField hook, or fallback to explicit props.

\n

Granted, it’s not as elegant as the original, But it’s more composable. I can now easily rearrange the elements of the input field without render prop soup (e.g., move the FieldMessage above the TextInput). And by using dynamically generated IDs and context, I can forgo the requirement of an explicit ID as well.

\n

The only downside to this is requiring a label becomes trickier. I could probably work out a solution by expecting a label ref to be passed through context, or I could just leave it and see if it’s a real problem to be solved.

\n

And if you still want that nice, elegant API from the very beginning, you could do something like this:

\n
function TextField({name, label}) {
  return (
    <Field name=(name)>
      <Label>{label}</Label>
      <TextInput />
      <FieldMessage />
    </Field>
  )
}

// <TextField label=\"Full Name\" name=\"username\" />
\n

How to avoid this

\n

The answer to avoiding premature abstraction is simple: don’t create abstractions until there is a need. Need is a relative term, but a good, solid rule to follow is don’t abstract duplicated code until you have found at least three instances of duplication. This is known as the Rule of Three.

\n

In React, components are abstractions, so you should hold off sharing a component until there are similar components in three different places. Note that you can, and should, still create private components. It’s a great way to keep duplicated code visible, as well as good practice for fine-tuning the component’s API.

\n

What now?

\n

If you’d like to learn more about the dangers of premature abstraction, I highly recommend watching Dan Abramov’s The Wet Codebase talk from Deconstruct 2019. And if you liked this article, please consider liking it on Dev Community, and follow me on Twitter to receive updates.

\n

Until next time!

\n", "date_published": "2021-02-19T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/12-newsletters-for-frontend-developers/", "url": "https://www.falldowngoboone.com/blog/12-newsletters-for-frontend-developers/", "title": "12 newsletters for frontend developers", "content_html": "

Frontend development is a field that changes daily, and to stay up-to-date, I need a steady source of new information. One way I do this is through newsletters.

\n

Here’s a list of some of the newsletters I subscribe to for all the latest frontend news:

\n\n

Do you have a favorite newsletter? I would be forever grateful if you tell me all about it. And if you liked this list, check out this list of books for developers I just wrote about.

\n", "date_published": "2021-02-18T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/description-lists-are-awesome/", "url": "https://www.falldowngoboone.com/blog/description-lists-are-awesome/", "title": "Description lists are awesome", "content_html": "

The description list (<dl>) is a magical element that can be used to mark up anything from dictionary entries to recipes. So, what’s so special about it?

\n

It’s all relational

\n

The description list, like its cousins the ordered and unordered list, is a list of associated items, meaning all items should be considered related to each other. The big difference is description list items are made up of two parts, a term (<dt>) and description (<dd>).

\n

Here’s what that looks like:

\n
<dl>
  <div>
    <dt>Freshly Brewed Coffee</dt>
    <dd>$1.75</dd>
  </div>
  <div>
    <dt>Iced Coffee</dt>
    <dd>$2.25</dd>
  </div>
  <div>
    <dt>Caffé Americano</dt>
    <dd>$2.25</dd>
  </div>
  <div>
    <dt>Flat White</dt>
    <dd>$3.75</dd>
  </div>
</dl>
\n

Notice that, unlike ordered and unordered lists, you can wrap related terms and descriptions in a single div to aid with styling. Normally a div would indicate a semantic separation of content, but inside a <dl> it’s completely ignored.

\n

And just like an ordered list, the order of the terms may be significant as well:

\n
<dl>
  <dt>If product pricing is hidden</dt>
  <dd>Show \"See price in cart\"</dd>
  <dt>If product is on sale</dt>
  <dd>Show sale pricing and styling</dd>
  <dt>Otherwise</dt>
  <dd>Show regular pricing and styling</dd>
</dl>
\n

That some pretty mind-blowing stuff, right? Okay, it’s not life-changing, but the description list is perfect for semantically establishing a relationship between terms and descriptions.

\n

What are they good for?

\n

So, when would you reach for the description list? Well, I work in e-commerce, so the first thing I can think of is product metadata on a product detail page:

\n
<dl>
  <dt>Price:</dt>
  <dd>$29.99</dd>
  <dt>SKU:</dt>
  <dd>123456</dd>
  <div>
    <dt>Colors:</dt>
    <dd>Red</dd>
    <dd>Green</dd>
    <dd>Blue</dd>
  </div>
  <div>
    <dt>Features:</dt>
    <dd>Non-slip finish</dd>
    <dd>Dishwasher safe</dd>
    <dd>Microwave safe</dd>
    <dd>One size fits most pots and pans</dd>
  </div>
</dl>
\n

Note that you can have multiple descriptions relating to a single term. I’ve seen this type of information marked up as a table and as separate divs, but this is semantically more correct.

\n

Another use of description lists that I’ve seen is in recipes:

\n
<dl>
  <dt>Ingredients</dt>
  <dd>flour</dd>
  <dd>salt</dd>
  <dd>dry yeast</dd>
  <dd>sugar</dd>
  <dd>...</dd>
  <dt>Instructions</dt>
  <dd>
    <p>Mix all dry ingredients in a bowl. Add wet ingredients.
    Let stand for 2 hours.</p>
    <p>Preheat oven to 375°.</p>
    <p>...</p>
  </dd>
</dl>
\n

The description list is useful in any situation where you have a list of related things that need to be broken down into name-value pairs. I even found a great article that suggests several more uses, all the way from the distant year 2004.

\n

Gotchas

\n

Even though the description list has been around since 1993, iOS VoiceOver has lacked proper support since it was first introduced in 2009. However, VoiceOver on iOS 14 and iPadOS 14 finally support description lists. As Adrian Roselli writes in a recent article, however, it is not without its quirks, mostly owed to existing VoiceOver bugs.

\n

The underutilized list

\n

Description lists are great for groups of name-value pairs, which covers a surprising amount of semantic content. Next time you’re marking up your HTMLs and whatnot, consider the humble description list.

\n

Are you already using description lists? Let me know what you’re using them for. And if you’re reading this on Dev Community, please consider liking this post if it is in any way helpful. This helps me know what articles make the most impact.

\n

Until tomorrow!

\n", "date_published": "2021-02-16T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/10-interesting-books-for-developers/", "url": "https://www.falldowngoboone.com/blog/10-interesting-books-for-developers/", "title": "10 interesting books for developers", "content_html": "

Reading is a great way to learn, but it’s also a fantastic way to open yourself up to new ideas and experiences. As a developer, I believe reading is important to my continued growth and advancement. If you believe that too, you might enjoy these ten books that I find particularly interesting.

\n\n

I hope that you find these books as interesting as I do. And if you have some interesting book recommendations, please let me know on Twitter, and be sure to check out some free online books I’ve previously written about.

\n

Until tomorrow!

\n", "date_published": "2021-02-15T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/the-details-element/", "url": "https://www.falldowngoboone.com/blog/the-details-element/", "title": "The details element", "content_html": "

The details element is one of my favorite HTML elements. Yes, I have favorite HTML elements. Yes, I know that’s weird.

\n

The Disclosure pattern

\n

So, what does this wonderful element do? Out of the box, it’s a way to natively achieve the disclosure pattern.

\n

The disclosure pattern involves some content and a button (the summary element) that controls the visibility of that content. When the content is hidden, the button shows the content. When the content is shown, the button hides the content.

\n

\n See the Pen \n Details by Ryan Boone (@falldowngoboone)\n on CodePen.\n

\n\n

Previously this was something that you could only do with JavaScript. And while it wasn’t difficult to do, I love when I can replace JavaScript with a native element that Just Works.™

\n

What’s it good for?

\n

details is a perfect fit for FAQs. You don’t even have to do that much extra styling.

\n

\n See the Pen \n Native FAQ by Ryan Boone (@falldowngoboone)\n on CodePen.\n

\n\n

And even though details isn’t a native accordion element (personally, I would rather have a tabs element), it goes a long way toward a nicer progressive enhancement experience:

\n

\n See the Pen \n Cheap accordion by Ryan Boone (@falldowngoboone)\n on CodePen.\n

\n\n

Just bear in mind that you’ll need to add some extra ARIA roles and keyboard support on top of the default element.

\n

Menus

\n

One particular type of use for details is really why I’m so fascinated with them. GitHub has implemented a pattern to use the element for their menus. It’s pretty ingenious.

\n

My favorite part of their implementation is adding a pseudo-element to the summary element that covers the entire screen. This elegantly closes the menu with an outside click:

\n
[open] > summary:before {
\tposition: fixed;
\ttop: 0;
\tright: 0;
\tbottom: 0;
\tleft: 0;
\tz-index: 80;
\tdisplay: block;
\tcursor: default;
\tcontent: \" \";
\tbackground: transparent;
}

.details-menu {
\tposition: absolute;
\ttop: 100%;
\tleft: 0;
\tz-index: 100;
\t/* more specific styles...*/
}
\n

Gotchas

\n

Of course, it wouldn’t be the web if it didn’t have any gotchas. First, [summary styling](https://css-tricks.com/quick-reminder-that-details-summary-is-the-easiest-way-ever-to-make-an-accordion/) is a bit inconsistent across browsers, but nowhere near as weird as other elements.

\n

Second, summarys can include a single heading element (h1–6), but because it natively carries the implicit ARIA role of button, any children, including headings, will be stripped of their semantic role. Depending on what’s used, certain screen reader and browser combinations may not recognize heading children or allow them to be used for navigation.

\n

Finally, there is no support in Internet Explorer, which is becoming less and less of a problem every day. There is a polyfill, but I would simply let the content display completely. Unless it’s absolutely necessary, sending more JavaScript to less capable browsers just for consistency’s sake doesn’t make much sense to me.

\n

Semantics for the win

\n

So, details provides a simple, semantic way to implement the common disclosure pattern. Its flexibility and availability make it a powerful addition to any frontend developer’s arsenal.

\n

Do you have a favorite HTML element? I would love to hear about it. And if you’re reading on Dev Community, please consider liking this post and sharing it with others. It makes me feel all warm inside and stuff.

\n

Till next time!

\n", "date_published": "2021-02-14T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/the-address-element/", "url": "https://www.falldowngoboone.com/blog/the-address-element/", "title": "The address element", "content_html": "

Did you know there’s an address element? Well, brace yourself, because there is! But its use has been a source of confusion until recently.

\n

In the past, the address element was strictly used for content author info, something it’s still useful for:

\n
<article>
  <!-- article content -->
  <footer>
    <p>Like my stuff? As the kids say, drop me a line via electronic mail:</p>
    <address>
      <a href=\"mailto:rick.cooldood78@example.com\">Ricky Cooldood 😎</a>
    </address>
  </footer>
</article>
\n

Note that this example has the address element nested within a sectioning element, in this case, an article. This is what associates the contact information with the content. If you wanted to associate it with the entire site, you would drop it into the site’s main footer.

\n

Of course, you would think that you could use an address element for addresses as well, but that has not always been the case. Thankfully, a recent change in spec allows for the one thing you would think it could be used for:

\n
<address>
  Richard Cooldood<br>
  1234 No Way Yes Way<br>
  Awesome, USA 77777
</address>
\n

This makes me incredibly happy. Probably too happy.

\n

Anyway, if you need more granular semantics around an address, you can use a structured data format like Microdata or RDFa.

\n

If you’d like to hear more about structured data, let me know, and while you’re at it, hit the follow button, because I’m going to keep writing stuff and you might as well read it, right?

\n", "date_published": "2021-02-13T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/fixing-all-the-things/", "url": "https://www.falldowngoboone.com/blog/fixing-all-the-things/", "title": "Fixing all the things", "content_html": "

If you didn’t already know, your CSS can influence screen readers. One of the most surprising things to me was learning that VoiceOver removes list semantics from uls and ols when list-style-type: none is applied to them.

\n

Turns out, this is actually intended behavior:

\n
\n

This [not announcing a list for a groups of links when list-style is set to none] was a purposeful change due to rampant “list”-itis by web developers…Basically, if you remove all default visible indication of the list, there is no indication to a sighted user or screen reader user that the content is a list…

\n

—James Craig, Webkit Bugzilla

\n
\n

This is one of those interesting things that may seem wrong to developers that apparently was annoying accessible technology users. James goes on to say the easiest way to fix this is to explicitly define a list role on the list:

\n
<ul role=\"list\">
\t<!-- list content here -->
</ul>
\n

Unfortunately, as Scott O’Hara reminds us in his fantastic write up on this issue, the first rule of ARIA is to not use it when there are existing HTML elements that already have the needed role. Scott mentions a nice CSS-only fix put forth by Gerard Cohen and retweeted by Sara Soueidan:

\n
.list li {
\tlist-style-type: none; /* remove bullets */
}

.list li::before {
\tcontent: \"\\200B\"; /* add zero-width space */
}
\n

I think my biggest takeaway from Scott’s article, though, is that “bugs” like this may be best left alone:

\n
\n

While this behavior can be unwelcome in some situations, let’s also not spend too much effort over correcting an over correction which was in response to an over use of unnecessary semantics.

\n
\n

VoiceOver users are used to the quirks that the technology presents. Forcing a consistent experience may end up making things worse. Just like everything else in web development, you need to test with real people.

\n

When I began my journey of learning about accessibility, I enthusiastically “fixed” everything I could find in my code, usually over-complicating markup and making things worse for people. More often than not, it pays to keep it simple.

\n

If you’d like to hear more about how I’ve overcomplicated things in the past, check out this letter to my younger self, or you can just ask me on Twitter about all the hot garbage code I’ve been known to write. Maybe you can learn from my (many) past mistakes.

\n", "date_published": "2021-02-12T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-i-test-for-accessibility/", "url": "https://www.falldowngoboone.com/blog/how-i-test-for-accessibility/", "title": "How I test for accessibility", "content_html": "

I wanted to share what my typical accessibility testing sessions look like. This is a quick over, but I hope you find it helpful (and if you haven’t done so yet, check out some accessibility quick wins I wrote about).

\n

What I typically do

\n\n

What I should do

\n\n

I’m certain this list will continue to grow, but for now I hope it gives you a sense of where to start. If you have any questions or suggestions, I’m always up for a discussion on Twitter.

\n

Until tomorrow!

\n", "date_published": "2021-02-11T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/notes-to-my-younger-self-regarding-accessibility/", "url": "https://www.falldowngoboone.com/blog/notes-to-my-younger-self-regarding-accessibility/", "title": "Notes to my younger self: Regarding accessibility", "content_html": "

Hello, my younger self. How are things? I understand you’re learning about the amazing world of web accessibility, something I wholeheartedly endorse.

\n

Actually, that’s why I’m writing to you. What I’m about to tell you might hurt, but I think you can handle it. There are some things you’re doing right now, things that you might think are helpful. Well, uh, they really aren’t. In fact, they’re pretty terrible.

\n

You don’t need all those nav elements

\n

First, why so many navs on a single page? Multiple nav elements can create a lot of unnecessary noise for screen reader users. Remember what the [nav element spec](https://html.spec.whatwg.org/multipage/sections.html#the-nav-element) says:

\n
\n

Not all groups of links on a page need to be in a nav element — the element is primarily intended for sections that consist of major navigation blocks [emphasis mine].

\n
\n

Major navigation blocks. Not every single link list in the footer. C’mon, man!

\n

Oh, and if you must have multiple navs, make sure you label any that aren’t the primary site navigation:

\n
<nav aria-labelledby=\"nav-label\">
\t<h2 id=\"nav-label\">Secondary</h2>
\t<ul>
    <!-- links in here -->
  </ul>
</nav>
\n

Alternatively, you could use aria-label:

\n
<nav aria-label=\"secondary\">
\t<ul>
    <!-- links in here -->
  </ul>
</nav>
\n

Just keep in mind that in the far, far distant future of 2021, content in aria-label still isn’t translatable.

\n\n

Here’s a snippet of actual code you wrote with your actual hands:

\n
<nav class=\"...\">
  <ul class=\"...\">
    <li id=\"...\">
      <a role=\"menuitem\" class=\"...\" href=\"...\" aria-expanded=\"false\" aria-controls=\"...\" aria-haspopup=\"true\">
\t\t\t\t...
\t\t\t</a>
\t\t\t<!-- more insanity omitted -->
\n

I see you’ve learned about aria attributes. That’s…nice.

\n

There’s just so much wrong here, but what I want to focus on is the role="menuitem". All menu roles are meant for application menus, not navigation links. Unless you’re building the browser equivalent of Photoshop, stay away from them.

\n

Also, I don’t know what you’re up to with all those aria attributes, but I know it can’t be good.

\n

Hide invisible content from screen readers

\n

Remember when you coded up that swanky dropdown menu that faded in and out? Yeah, that was slick! Remember the CSS you used?

\n
.dropdown-panel {
\topacity: 0;
\ttransition: opacity 200ms;
\t// other stuff

\t&.is-open {
\t\topacity: 1;
\t}
}
\n

First of all, kudos on animating opacity. You’re thinking about performance, and that’s a Good Thing.™ But I think you’re missing something.

\n

Did you know that elements set to opacity: 0 can still be read by screen readers? By the look on your face, I can see you didn’t know that. Something else you probably didn’t realize is since opacity: 0 doesn’t remove elements from the focus order, keyboard users get to tab through all 500 invisible links in your mega site nav.

\n

If you are hiding elements for sighted users to reduce cognitive noise, you should do the same for screen readers. Remember that accessibility is about creating equivalent experiences. display: none is a much better choice here to completely hide the panel from everyone.

\n

What’s that? You can’t animate opacity when you’re using display: none? Well, use JavaScript here, ya silly. It’s already a requirement for your dropdown menu to work. Here’s an example Codepen.

\n

That’s it for now

\n

There’s more to discuss, for sure, but frankly, I don’t have the strength to go on. Perhaps some other time. I want to leave you with some advice.

\n

First, one day you’ll want to write a daily blog post for an entire month. Make sure you do more planning so you don’t end up writing weird stuff like this at the last minute. Second, reach out to me through this magical time machine internet connection and say hi to me on Twitter. I get lonely sometimes.

\n

See you in the future!

\n", "date_published": "2021-02-10T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/accessibility-quick-wins/", "url": "https://www.falldowngoboone.com/blog/accessibility-quick-wins/", "title": "Accessibility quick wins", "content_html": "

I sometimes give talks on Web accessibility, and one of the top questions I get is: What can I do right now to make my website more accessible? When I began practicing accessibility, I would’ve probably talked about WAI-ARIA authoring practices, and adding aria roles, and managing focus with JavaScript. That’s certainly true for more complex UI, but most of us aren’t building Twitter.

\n

In reality, the most common accessibility problems can be fixed with simple solutions. What follows is a list of some of the quick wins I’ve compiled from online survey results, third-party auditors, and the A11y Slack group.

\n

Use colors with the proper contrast

\n

This one’s truly easy. Check the color contrast on your page. This should be the designer’s job, but frontend developers should be diligent to double-check and make suggestions as necessary. Usually, it doesn’t take many tweaks to ensure the correct contrast ratio.

\n

Add an alt attribute to all your images

\n

This is a super-quick win. According to the 2020 WebAIM Million survey, one of the top accessibility errors online was missing alt attributes on images. It’s always a good idea to include effective alt text on images that are not purely decorative.

\n

It’s important to note that if you don’t add an alt attribute, the default behavior of screen readers is to announce the source link of the image, which can be annoying, especially if you’re including hashes in the filename for cache-busting. So what about images that are decorative? Use a null value (alt=""). Better yet, add decorative images as background images via CSS (background-image: url('link/to/image');).

\n\n

One way screen reader users can quickly navigate content is by jumping through all the available page links. When all the links on the page are either “Click here”, nonsense (e.g. icon fonts), or empty (e.g. an SVG icon without a label), navigating by page links becomes impossible.

\n

If you’re being asked to create “Click here” links, talk to the content authors about the difficulties of that type of phrasing. As a bonus, using descriptive link text is better for your SEO. You can learn more about link text in WebAIM’s article about links and hypertext, and Scott O’Hara has a great article I continually reference for accessible SVGs.

\n

Label all form elements

\n

This goes along with the last tip. Form elements (input, textarea, select, button, etc,) must have properly associated labels.

\n

button elements are easy to label:

\n
<button>I'm a label</button>
\n

For the rest, you need to associate a label element with the form element in question:

\n
<label for=\"element-id\">Username</label>
<input id=\"element-id\" name=\"username\" />
\n

Notice the label has a for attribute that’s the same as its sibling input’s id. That’s how accessible technology knows what label is associated with what input. Avoid using placeholder as a label. In fact, you probably should avoid using the placeholder attribute altogether.

\n

Don’t use ARIA unless you’ve exhausted all other options

\n

ARIA (Accessible Rich Internet Applications) is a collection of roles and attributes that enrich plain old HTML to support interactions that are currently not possible with HTML. The first rule of ARIA is Don’t use ARIA. Great marketing, right?

\n

The truth is, modern HTML can cover most UI needs. Don’t believe me? There are over 100 current HTML elements, and many of them have ARIA roles already baked into them. This brings me to my next tip.

\n

Use semantic HTML when possible

\n

divs and spans are great to style with, but they have no meaning whatsoever to accessible technology. Wrapping large blocks of text directly in a div should be avoided with few exceptions, and those exceptions involve manually adding semantic meaning via aria roles.

\n
<div>This text has no meaning whatsoever because divs are a 
generic container.</div>
<p>This is a paragraph of content.</p>
\n

Wrapping text in a span is a great way to style a select group of text, just make sure it’s inside another element that has semantic meaning:

\n
<p>This is a paragraph. <span class=\"red\">This span has no semantic meaning, 
but we're still inside a paragraph, so it's fine.</span></p>

<span>Without a semantic parent, this text has no meaning.</span>
\n

Don’t hide the focus ring

\n

You can restyle the focus ring, but make sure it meets contrast guidelines. The reason is keyboard users need to be able to see where they are while tabbing through interactive elements.

\n

One reason why the focus ring gets hidden is that clicking on interactive elements in certain browsers focuses them, activating the focus styling. If you only want to show the focus indicator for keyboard users, try [focus-visible](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible#selectively_showing_the_focus_indicator).

\n

Don’t wrap large blocks of markup in links

\n

So when would you want to do this? How about a cards that link to other pages:

\n
<a class=\"card\" href=\"/page\">
 <h2>Title of Article</h2>
 <p>Small blurb here.</p>
</a>
\n

Why avoid this? For starters, you can’t easily select text inside of links. Second of all, links are announced in screen readers by reading off the contained text content. The more content inside the link, the more inconvenient the link text becomes. I’ve made a Codepen showing a couple of approaches to get around this.

\n

Validate your HTML

\n

Valid HTML is important to ensure that your content renders correctly for years to come and that it works well with accessible technology. Little things like adding closing tags, properly nesting elements, and following the HTML spec can make a huge difference for your SEO as well. The W3C has a solid HTML validator that works well.

\n

Specify the document language

\n

This one’s something you should probably put into a snippet. Specifying the document’s language helps translation apps, improves the SEO of the page, and improves a screen reader’s ability to pronounce certain words. Here’s how that looks:

\n
<html lang=\"en\">...</html>
\n

Of course, use the ISO language code that pertains to your chosen document language. This attribute is inherited by all children, so placing it on the document element (html)

\n

In closing

\n

If you keep this list in mind, you will be well on your way to ensuring your website is accessible to the widest audience possible. Not only will it improve performance, SEO, and readability for all of your users, it’s the right thing to do.

\n

If you enjoyed this article, please consider sharing this article with others. And if you have any questions about any of the points above, feel free to ask me on Twitter.

\n

Until tomorrow!

\n", "date_published": "2021-02-09T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/accessible-content/", "url": "https://www.falldowngoboone.com/blog/accessible-content/", "title": "Accessible Content", "content_html": "

When I was first learning about accessibility on the Web, I stumbled across WebAIM (Web Accessibility In Mind), a fantastic resource for all things accessibility.

\n

They have a ton of great articles focusing on different aspects of web accessibility, but one of my favorites I keep going back to is Constructing a POUR Website. It helps unravel the Web Accessibility Guidelines principles of accessibility and helps shift the focus away from how to make content accessible to why.

\n

In summary, the WCAG guiding principles state that accessible content is perceivable (people can perceive the content with any of their available senses), operable (people can interact with the content as needed), understandable (people can understand the content and how to navigate it), and robust (the content can be interpreted by an array of technologies). These principles form the acronym POUR, which is an easy way to remember them.

\n

To explore these principles in more depth, check out the article. And if you have any questions or would like to discuss it, feel free to reach out to me on Twitter.

\n", "date_published": "2021-02-08T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/lean-into-the-fear/", "url": "https://www.falldowngoboone.com/blog/lean-into-the-fear/", "title": "Lean into the fear", "content_html": "

Chantastic recently spoke at ReactJS Dallas about dealing with Imposter Syndrome. One of my favorite moments was when he talked about being asked to take over React Podcast hosting duties. He said he was afraid he was going to say the wrong thing to the amazing developers he would be interviewing.

\n

Eventually he realized that fear was the only reason not to take the offer. So instead of passing up a fantastic opportunity, he decided to lean into the fear.

\n

Listening to someone I’ve heard interview JavaScript heavyweights on my iPhone for the past few years talk about facing his own fears renewed my long-held belief that I need to lean into the things that make me afraid.

\n

The first time I was asked to give a software talk, I had been a professional developer for less than a year. I was terrified, but I did it. Was it good? Meh. But the important part was I stepped out of my comfort zone. I still experience a fear of public speaking, but the more I push through that fear, the quieter its gets.

\n

If fear is the only thing keeping you from doing something that could otherwise enrich your life, lean into it. Intentionally do something because it scares you. Start a YouTube channel. Give a talk at a Meetup. Try blogging for 28 days straight.

\n

Push past the fear, get comfortable with being uncomfortable. You never know what it might lead to.

\n

Have you ever let fear hold you back from doing something? Make an action plan today to lean into that fear, and let others know so they can encourage you. Don’t know where to start? I’m glad to answer any questions.

\n", "date_published": "2021-02-07T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/your-experience-counts/", "url": "https://www.falldowngoboone.com/blog/your-experience-counts/", "title": "Your experience counts", "content_html": "

On my journey from designer to becoming a developer, I often wondered if I needed a Computer Science degree. This is also one of the most common questions I get from others looking to jump into development from another career.

\n

I began college as a Drama major and eventually switched to a Communications degree with an emphasis in Film and Broadcast. Then I went into graphic design. Not exactly the straightest path to software engineering.

\n

For a long time, I allowed my lack of formal development education to be a source of insecurity. No matter what I accomplished or what I learned, I always felt like I was missing something. It fueled my appetite for growth, but it robbed me of my confidence.

\n

Something that I realized as a designer, though, was even though I didn’t have a formal education in a particular field of study, the education and experience I had acquired up to that point was more relevant than I initially thought. I began reframing the idea that I had no applicable experience into the idea that all experience counts.

\n

In acting, I learned to put myself in the shoes of another person, useful for testing interfaces and writing readable code. In film school, I learned how to tell a story, something that’s useful in crafting version control commit history and interpersonal communication. Finally, in design, I learned how to build systems that scale, which is invaluable to creating software architecture.

\n

There are many different paths to becoming a software developer. Whether or not you should get a Computer Science degree is really something only you can answer. I didn’t need one to become a developer, but the process of getting one can help you choose what field of development you want to pursue.

\n

I think the important takeaway from this is, if you’re struggling with insecurities about a lack of education, look at what you do have. Start to bridge what you know and what you’ve done to what you want to do. Chances are your experiences and interests already have a common theme and share a common skillset.

\n

Your experience counts more than you think.

\n

What has your journey looked like? Has it been as roundabout as mine? Or maybe even more…unconventional? I would love to hear all about it.

\n

Thanks for reading. Until tomorrow!

\n", "date_published": "2021-02-06T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/debugging-javascript-with-binary-search/", "url": "https://www.falldowngoboone.com/blog/debugging-javascript-with-binary-search/", "title": "Debugging JavaScript with binary search", "content_html": "

I recently had to debug a problem that existed somewhere in the middle of around 460 lines of JavaScript spaghetti. Debugging was useless because the bug was taking down dev tools! The approach I took was something that I often employ when facing a seemingly impossible task like this.

\n

First, let me pull up a chair, sit down in it backwards and type out some words about binary search. It’s a search pattern that utilizes a divide and conquer algorithm to locate data.

\n

Let’s say you need to look up something located in a huge heap of sorted data. Oh, maybe you’re looking up a friend’s phone number in a phone book (I mean, not like I ever had to do that in my lifetime…).

\n

Anyway, you need to find a friend’s number, so the first thing you do is open the phone book to the very middle. Is your friend’s last name on the page? Chances are it’s not. Since you know the alphabet, you know whether your friend’s last name comes before or after the page you’re on.

\n

Now this is an important point. Let’s say your friend’s last name comes before the page you’re on. In binary search, you throw away the data you know doesn’t contain what you’re looking for. This leaves you with half the data to search through.

\n

Now you do the same steps over and over, dividing the data, checking where you are, and throwing away the half that doesn’t contain what you’re looking for. This algorithm is simple and elegantly fast (a worst-case time complexity of O(log n), which in plain speak means it remains fast the bigger the dataset you have to search).

\n

So why did I just blow through five paragraphs on binary search? What was I talking about? Oh, right, debugging.

\n

To debug this particular problem, I first commented out the entire block of code as a sanity check, then checked to make sure the bug was no longer occurring (setting up a quick feedback loop is crucial to debugging).

\n

After confirming I had indeed isolated the bug, I commented out the bottom half of the 460 line code block (I always skip commenting out top level function declarations to avoid runtime exceptions that could give me a false positive). A save and refresh showed the bug was still alive and well. I continued to do this until the bug no longer triggered.

\n

After I isolated the bug to a range of lines, I uncommented everything else, saved, and double-checked my work. After confirming the cause was definitely in the last chunk of code I commented out, it was a matter of doing the binary comment-out-and-save on those remaining lines.

\n

I found the source of the bug in about an hour, which is pretty good considering it takes about 30 minutes to deploy the code to our testing environment. Yeah, that’s a topic for another post.

\n

I have been told that repetition helps learning, so let’s do that now. To review:

\n
    \n
  1. Set up a feedback loop
    2. \n
  2. Confirm the code you are editing is indeed the problem
    3. \n
  3. Starting from the bottom, comment out half the code, save and refresh
    4. \n
  4. If the bug remains, repeat Step 3 until the bug is squished; now you know where the bug exists (make sure you double check your work by uncommenting everything but the isolated block of code)
    5. \n
\n

I’ve used this for layout overflow issues as well (CSS is awesome), by deleting huge chunks of a web page in dev tools. It’s an effective, if dirty, solution.

\n

Sometimes I like using the debugger. Sometimes it’s the good ol’ console.log. But when all else fails, I get out the knife and start carving up code.

\n

How do you debug your code? Let me know and I’ll be your best friend. And I am a very good friend.

\n

Till tomorrow…

\n", "date_published": "2021-02-05T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/building-habits-through-relationships/", "url": "https://www.falldowngoboone.com/blog/building-habits-through-relationships/", "title": "Building habits through relationships", "content_html": "

Atomic Habits by James Clear is a fantastic read. At its heart, the message of the book is that setting goals is ineffective in the long run. Real, lasting change only comes through building systems—creating the right conditions for doing the right habits.

\n

One insight Clear offers is we often mirror the habits of those around us, for better or worse. Understanding that, one of the easiest ways to develop desirable life habits is to join a group that shares your interests and is doing what you want to do.

\n

I intentionally look for groups of people that are learners. I hang out with other developers, attend Meetups (shout out to the ReactJS Dallas!) and conferences, belong to various Slack and Discord groups, and listen to several programming podcasts. This has helped me develop healthy learning habits and provides an outlet to share what I’ve learned.

\n

Connecting with other people is critical for personal growth, not only because it helps you develop healthy habits and skills, but, more importantly, because it creates connections and friendships that will enrich your life and expand your world view. I want to encourage you to seek out groups of people that are doing what you want to do. You’ll be surprised at what you learn.

\n

One way to discover groups of people with shared interests is by listening to podcasts. Do you have a favorite podcast? Join their community, and let me know over on the wide wide world of Twitter. I’m always looking to expand my listening library (and if you’d like some suggestions, I have a whole list of favorites).

\n

Until tomorrow!

\n", "date_published": "2021-02-04T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/web-development-resources/", "url": "https://www.falldowngoboone.com/blog/web-development-resources/", "title": "Web development resources", "content_html": "

As a follow up to yesterday’s post, I wanted to share a quick list of online resources that I used to get started in my development career.

\n\n

I’m always looking to expand my resource list, so if you have a favorite you don’t see here, please let me know on Twitter.

\n", "date_published": "2021-02-03T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/on-changing-careers/", "url": "https://www.falldowngoboone.com/blog/on-changing-careers/", "title": "On changing careers", "content_html": "

I had just made the decision to leave my 15-year career as a designer to become a developer, and I had no idea where to start. The only programming I had ever done was building websites for friends and family. I was completely green.

\n

That was six years ago. Now I’m enjoying my fourth year as an Applications Engineer at The Container Store doing fullstack development.

\n

I tell you this because maybe you are thinking about jumping careers and you feel stuck, frustrated, and lost. Maybe you feel like it’s never going to happen. Believe me, that’s normal.

\n

What follows is a short list of things that helped me get through the tough times by keeping my focus on the end goal. It starts with a simple question.

\n

What motivates you?

\n

I have always loved doing creative things, so when I got a job as a designer at a marketing firm in the Dallas/Fort Worth area, I was excited. I thought I would be doing the thing I loved doing more than anything else. A few years in I realized I wasn’t happy, and I didn’t know why.

\n

A coworker suggested I take the StrengthsFinder test (now CliftonStrengths). Now I am not normally someone that takes personality assessment tests, but I liked StrengthsFinder. It’s actually less about discovering your strengths and more about discovering what motivates you.

\n

If you don’t want to take an assessment test, try talking to your friends and family. Ask them what they think you’re good at. Pay attention to what you do that makes time fly. Look for commonalities between these things, and write what you learn down.

\n

Knowing what motivates you gives you an anchor you can always come back to in times of doubt or indecision. And it gives you a point of reference for the next step.

\n

Try your new job on

\n

Knowing my motivation was great, but knowledge without application is useless. At that point, I was leaning in the direction of Web development, but I needed a way to try the role on before making a huge life decision.

\n

I bought a subscription to Treehouse and used my lunch hour to watch web development videos and do exercises. I began volunteering at work to design and build marketing emails (coding like it’s 1999). I worked my way up to building brochure sites for clients.

\n

Finally, I took a big, scary leap. My company announced they were rebranding, and I volunteered to redo their website. It took some convincing, but eventually I had my first official Web project under my belt.

\n

You may not have an hour for lunch, or you may have limited personal time. Be open to finding anything either at work or at home that you can do to try your new job on right now. Create a plan and stick to it.

\n

Focus on moving forward

\n

Completely changing careers didn’t happen for me overnight. Big changes like that rarely do. You have to be patient and stay consistent.

\n

I compare this experience to being on a boat in the middle of the ocean. You can’t see your destination, but you know the general direction. Yes, there will occasionally be the need for course correction, but as long as you’re moving forward, you will get there eventually.

\n

Don’t underestimate the power of tiny, consistent actions. A lot can happen over the span of one year. Don’t lose hope. Chances are you’re closer to land than you think.

\n

Now what?

\n

As I said, this is a (very) small list of things that helped me make the jump from design to development. If you’re on a similar journey, let me know. Oh, and if you’re an aspiring developer, checkout my post on how to get started with coding.

\n

Until next time!

\n", "date_published": "2021-02-02T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/blogruary-28-days-of-posting/", "url": "https://www.falldowngoboone.com/blog/blogruary-28-days-of-posting/", "title": "Blogruary: 28 days of posting", "content_html": "

I suck at blogging. Presently. I presently suck at blogging. I read somewhere that you should qualify negative statements with “presently.” So, yeah, I presently suck at blogging, but I would love to get better at it.

\n

I’ve tried three or four times to start blogging, and I always fizzle out after a handful of posts. Why? I presently (ah, see what I did there?) struggle with finding value in what I have to say. Of course, that’s a pretty poor excuse to not write.

\n

The thing is, I love the feeling I get when I help other people learn something. I get to do that every day at my job as a developer at The Container Store (it’s where space comes from; look it up). I’ve also heard teaching others is a great way to learn, and learning is like one of my top favorite seven things.

\n

With that in mind, this month I have resolved to write 28 blog posts, including this one. I’m calling it Blogruary because I’m a stickler for naming things. The first ‘r’ is silent, in case you’re wondering.

\n

You may ask, Ryan, why February? Well, it’s the shortest month of the year and I feel more comfortable doing 28 posts versus 30 or 31 and mind your own business, okay? Geez!

\n

I’m not going to lie. Going from three blog posts a year to 28 in a month is going to be tough. I’m setting some ground rules to make sure I accomplish my goal. First drafts should take no longer than fifteen minutes to write. Editing should not exceed one hour. And to keep me honest, I will share these blog posts with all my followers on Twitter (hi mom!) as well as on my dev.to account.

\n

The subject matter may be a bit random at times. I’m still trying to figure out what my thing is. But the end goal is to become a better communicator and help others in the process. I hope you come along for the ride.

\n", "date_published": "2021-02-01T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/year-end-review-2020/", "url": "https://www.falldowngoboone.com/blog/year-end-review-2020/", "title": "Year-end review 2020", "content_html": "

2020 is out and I wanted to do a short review of what I did this year, as well as look forward to 2021. This year was difficult to be sure, but in spite of the craziness, or maybe because of it, I was surprisingly able to meet some goals I had previously set.

\n

2020 Accomplishments

\n

In 2020…

\n\n

I’ve started to see a pattern of excitement when working on developer tools. I really enjoyed putting the front end tool chain together, and I’ve gotten to really take charge over a couple internal tools used department-wide.

\n

2021 Opportunities

\n

In 2021…

\n\n

Looking ahead

\n

To be honest, it feels weird to be writing about my accomplishments in a year filled with chaos, but I wanted to at least have a written record for future reference. I’m glad we can mark this year as done, and I’m hoping and praying the next year is better.

\n

Until next time, stay safe, and may this new year be better than the last.

\n", "date_published": "2020-12-31T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/composing-data-in-eleventy/", "url": "https://www.falldowngoboone.com/blog/composing-data-in-eleventy/", "title": "Composing data in Eleventy", "content_html": "

A lot of what I do at The Container Store involves page templates, and one of the biggest challenges with template work (and components, for that matter) is creating a system that’s flexible yet maintainable. One of the ways flexibility can be achieved is by giving child elements a way to hook into the parent element. In JSP templates (what we use at The Container Store), template hooks can be added via the invoke action, but I wanted to figure out how to do this on my personal Eleventy site.

\n

The use case

\n

I use Prism.js to dynamically style my code blocks, and the basic way to use Prism.js relies on the presence of both a CSS file and a JavaScript file to be loaded on a page. The JavaScript adds classes to code blocks based on their type, and the CSS themes the blocks accordingly. The easiest (naive) way to include these assets in Eleventy is to add them directly to a global template:

\n
<!-- _includes/default.njk -->
<!DOCTYPE html>
<html lang=\"en\">

<head>
  <meta charset=\"UTF-8\" />
  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
  <title>{{ title }}</title>
  <meta name=\"description\" content=\"{{ description }}\" />
  <link rel=\"stylesheet\" href=\"/css/global.css\" />
  <!-- Prism.js theme styles -->
  <link rel=\"stylesheet\" href=\"/css/prism-theme.css\" />
</head>

<body>
  <div class=\"o-page\">
    <header class=\"c-header\">
      <!-- ...header content -->
    </header>
    <main id=\"main\">
      <!-- render child content -->
      {{ content | safe }}
    </main>
    <footer class=\"c-footer\">
      <!-- ...footer content -->
    </footer>
  </div>
  <!-- Prism.js JavaScript -->
  <script src=\"/js/prism.js\"></script>
</body>

</html>
\n

In my case, I have two child templates based off of my global template, _includes/page.njk, which is the template for simple pages, and _includes/post.njk, the template for all of my blog posts. Since both are children of the global template, both receive the Prism.js JavaScript and CSS, even though only the post template will ever need it. We could move the script and CSS to the post template:

\n
<!-- _includes/post.njk -->
---
layout: default
---

<!-- Prism.js theme styles -->
<link rel=\"stylesheet\" href=\"/css/prism-theme.css\" />
<h1>{{ title }}</h1>
{{ content | safe }}
<!-- Prism.js JavaScript -->
<script src=\"/js/prism.js\"></script>
\n

The problem is the child templates render in the middle of the final page structure, meaning the link and script tags would render inside the main element:

\n
<!-- rendered post -->
<!DOCTYPE html>
<html lang=\"en\">

<head>
  <meta charset=\"UTF-8\" />
  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
  <title>The page title</title>
  <meta name=\"description\" content=\"The page description\" />
  <link rel=\"stylesheet\" href=\"/css/global.css\" />
</head>

<body>
  <div class=\"o-page\">
    <header class=\"c-header\">
      <!-- ...header content -->
    </header>
    <main id=\"main\">
      <!-- Prism.js theme styles -->
      <link rel=\"stylesheet\" href=\"/css/prism-theme.css\" />
      <h1>The page title</h1>
      <p>...template content...</p>
      <!-- Prism.js JavaScript -->
      <script src=\"/js/prism.js\"></script>
    </main>
    <footer class=\"c-footer\">
      <!-- ...footer content -->
    </footer>
  </div>
</body>

</html>
\n

While technically this works, it’s not optimal. Ideally, we want all stylesheets to render in the document head and all scripts to render just before the closing body tag, both of which are outside the scope of the child templates.

\n

Using extends

\n

The template language I’m using is Nunjucks, which, as luck would have it, has a built-in way to do this using extends:

\n
<!-- _includes/default.njk -->

<!DOCTYPE html>
<html lang=\"en\">

<head>
  <meta charset=\"UTF-8\" />
  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
  <title>The page title</title>
  <meta name=\"description\" content=\"The page description\" />
  <link rel=\"stylesheet\" href=\"/css/global.css\" />
  {% block head %}{% endblock %}
</head>

<body>
  <div class=\"o-page\">
    <header class=\"c-header\">
      <!-- ...header content -->
    </header>
    <main id=\"main\">
      {% block content %}{% endblock %}
    </main>
    <footer class=\"c-footer\">
      <!-- ...footer content -->
    </footer>
  </div>
  {% block script %}{% endblock %}
</body>

</html>
\n
<!-- _includes/post.njk -->

<!-- absolute paths in `extends` resolve to the `_includes` directory -->
{% extends \"default.njk\" %}

{% block head %}
<!-- Prism.js theme styles -->
<link rel=\"stylesheet\" href=\"/css/prism-theme.css\" />
{% endblock %}

{% block content %}
<h1>The page title</h1>
<p>...template content...</p>
{% endblock %}

{% block script %}
<!-- Prism.js JavaScript -->
<script src=\"/js/prism.js\"></script>
{% endblock %}
\n

This works in Eleventy, but not without limitations.

\n

First of all, Eleventy won’t process front matter in templates that use extends, and no aliases set in Eleventy’s configuration will be used in resolving include paths (alternatively you may use relative paths). Second, it locks the project into Nunjucks. One of the things I love about Eleventy is how easily I can change template languages out, but now I have to use Nunjucks. I mean, I like Nunjucks, but, even more so, I like having options.

\n

Using front matter

\n

If you want a child-specific value available to a parent template, you have to specify it in that page’s front matter. We can use this as a way to pass blocks of content up the template chain. I’m going to add two new keys to the front matter, headContent and scriptContent, and render them in the parent template document:

\n
<!-- _includes/post.njk -->
---
layout: default
headContent: |
  <!-- Prism.js theme styles -->
  <link rel=\"stylesheet\" href=\"/css/prism-theme.css\" />
scriptContent |
  <!-- Prism.js JavaScript -->
  <script src=\"/js/prism.js\"></script>
---

<h1>{{ title }}</h1>
{{ content | safe }}
\n
<!-- _includes/default.njk -->

<!DOCTYPE html>
<html lang=\"en\">

<head>
  <meta charset=\"UTF-8\" />
  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
  <title>The page title</title>
  <meta name=\"description\" content=\"The page description\" />
  <link rel=\"stylesheet\" href=\"/css/global.css\" />
  {{ headContent }}
</head>

<body>
  <div class=\"o-page\">
    <header class=\"c-header\">
      <!-- ...header content -->
    </header>
    <main id=\"main\">
      {{ content | safe }}
    </main>
    <footer class=\"c-footer\">
      <!-- ...footer content -->
    </footer>
  </div>
  {{ scriptContent }}
</body>

</html>
\n

Notice the pipe character (|) in the front matter definition. This defines the style of a block scalar in YAML (the language the front matter is written in) to keep line breaks. An alternative to this approach would be to pass a list of paths for each key, but I want the flexibility to inline scripts and styles as well:

\n
<!-- some-post.njk -->
---
layout: post
headContent: |
  <style>
    .custom-page-style {
      /* your custom styles here */
    }
  </style>
scriptContent: |
  <script>
    console.log(\"I'm a custom page script\");
  </script>
---

<!-- page content -->
\n

However, there’s a problem with the code above. Can you see it? It’s re-defining the headContent and scriptContent keys in the front matter, and according to the Eleventy front matter data documentation, “locally assigned front matter values override things further up the layout chain.” The page content blocks are clobbering template content blocks, which means the Prism.js assets aren’t being loaded on this page.

\n

Composing data with eleventyComputed

\n

We can fix the front matter key collision issue a couple of ways.

\n

First, we could create a second template hook that only pages would use (e.g. pageHeadContent). That could work, but what if we want to extend the post layout template with another layout template that needs to add custom styles and scripts? Also, it’s still possible for a page to accidentally overwrite the headContent in front matter. This isn’t an issue on small sites, but maybe you’re building a sharable theme or you’re working with a constantly changing team.

\n

Ideally what we want is some way to compose all of the headContent data into a single block. That way we don’t have to worry about what key to use in the current layout we are in. That brings us to our second option, which is using Eleventy’s computed data.

\n
<!-- _includes/post.njk -->
---
layout: default
eleventyComputed:
  headContent: |
    <!-- Prism.js theme styles -->
    <link rel=\"stylesheet\" href=\"/css/prism-theme.css\" />
    {{ headContent }}
  scriptContent: |
    <!-- Prism.js JavaScript -->
    <script src=\"/js/prism.js\"></script>
    {{ scriptContent }}
---

<h1>{{ title }}</h1>
{{ content | safe }}
\n

eleventyComputed is a special Eleventy front matter key that grants access to the computed data at the time of rendering the individual page. This is how we can pass data from leaf templates up the layout template chain, allowing us to effectively extend leaf data with template data. Notice the leaf data is included at the end of the template block. This ensures the leaf styles have higher order specificity in the style cascade and leaf scripts can override template scripts if needed.

\n

Now we have composable blocks of code that allow us to tie into the base template and extend the page with whatever functionality or styling we want. This is a great example of how powerful Eleventy can be, even though the basic concepts are so simple.

\n

Ideas for further exploration

\n

We’ve explored how to optimize assets in Eleventy templates using composable eleventyComputed values. You can easily adapt this idea to add custom art direction, animations or behavior to an individual page, but this is something that has even more uses outside of styles and scripts.

\n

I hope this inspires you to explore more interesting uses of Eleventy’s computed data. And if you have a favorite Eleventy tip, tell me about it on Twitter!

\n", "date_published": "2020-11-28T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/how-im-redesigning-my-blog/", "url": "https://www.falldowngoboone.com/blog/how-im-redesigning-my-blog/", "title": "How I'm redesigning my blog", "content_html": "

Personal projects are a great way to grow your skillset, learn new technologies and explore new ideas. I began my personal blog with that in mind, but also wanted to share what I learn. With that in mind, I wanted to try and document the process behind this new redesign.

\n

I began this current redesign almost immediately after finishing my last redesign. My original plan was to launch a default Gatsby starter blog and then incrementally redesign it. That did not go as planned.

\n

Difficulties with Gatsby conventions (like using the GraphQL data mesh layer and MDX weirdness) and a growing concern over build performance led me to eventually abandon the framework. I spent the next year or so trying out different tools and tweaking design decisions, until I landed on what you see here.

\n

The Design

\n

As I write this, the design and build out are not complete, but I’ve decided to launch what I have so far. Why? I have confidence that getting the design out into the real world will help me iterate on it quicker, and I can easily see which ideas have value and which do not. With that said, here are some highlights of the design.

\n

Inspiration

\n

I have always been a fan of the Swiss Style, so I knew I wanted to incorporate a strong grid with a grotesque typeface. The grid on the blog pages is based on the Golden Ratio, with the main block on wide displays being roughly 0.618 times the width of the full grid. The text blocks are limited in line length using ch units, which equal the width of a font’s 0 character.

\n

Breaking with the Swiss Style, and as an homage to the cartoons that inspired this blog’s name, I wanted to include hand-drawn illustrations and decoration, just so the site itself didn’t end up feeling too cold or rigid.

\n
\n \"\"\n
Initial sketches of hand-drawn element ideas
\n
\n

My process has been sketching out ideas on paper first, then moving into Figma or Affinity Designer for high fidelity exploration. I’ve tried to move to designing in the browser as quickly as possible because that’s the medium the design will ultimately end up in. If I run into a design roadblock in the browser, I return to Figma or Affinity Designer and explore some more.

\n
\n \"\"\n
Design exploration in Figma
\n
\n

Fonts

\n

I love geometric typefaces, but they tend to be cold. Since I have hand-drawn elements, I wanted something with a bit more warmth. Rotunda filled the role perfectly, with a mix of geometric and humanistic forms. Oh, and I’m a sucker for double-story 'g’s and 'a’s.

\n
\n \"\"\n
Rotunda has humanistic forms as well as geometric alternates
\n
\n

I’m using Rotunda almost exclusively for headings, and for the body copy I’m opting for a simple system font stack. I’m still weighing the cost/benefit of using Rotunda for body copy as well. I’m trying to be somewhat conservative with the page weight.

\n

Animated gradient links

\n

One element of this design I really like, heavily inspired by CSS-Tricks, is the animated gradient link hover style. The effect is achieved using an oversized background gradient clipped to the text with background-clip: text. The only thing that’s animated is the background-position.

\n

There’s some box-decoration-break magic that makes sure the background style translates properly across line breaks, and -webkit-text-fill-color: transparent is needed to hide the text color.

\n

\n See the Pen \n Gradient animation on hover by Ryan Boone (@falldowngoboone)\n on CodePen.\n

\n\n

The Stack

\n

Eleventy and Liquid Nunjucks

\n

The new design is completely static and built with Eleventy. I’ve chosen Eleventy to replace my previous framework of Gatsby mainly because of Eleventy’s flexibility and ease of use. Eleventy is also a great deal faster than Gatsby, though my site is so small that I’ve barely noticed a difference when building.

\n

My template language of choice is Liquid, which, to be honest, I’m rethinking. The syntax can be quite awkward at times (possibly because of its Ruby origins). For example, empty strings in Liquid are truthy values, as opposed to JavaScript, where they are falsy, so in cases where you can either have a falsy value or an empty string, you must check for both. This is something that could be solved with something like a custom filter, but it’s quite annoying, and certainly not the only quirk this template language has.

\n

Update: Yeah, so, I’m not using Liquid anymore. The biggest reason is a practical one: the syntax highlighting and language support has been a constant pain to manage in VS Code. I’ve been using the Liquid VS Code extension, which I’ve had to completely disable due to an incident where it fried some source code at work (long story short, there’s a bug that causes it to encode certain tokens that unknowingly rewrote a large portion of some JSP templates). Even before that, it wasn’t that great of an extension. The author is supposedly rewriting it into a freemium extension called Liquify, but I’m not terribly interested.

\n

To be honest, using Liquid at this point feels like swimming upstream. I’ve switched to Nunjucks, and already I feel less tension with my editor. I was able to convert everything over in an hour or so. I won’t tell you how long it took me to convert over to Liquid.

\n

Modern CSS

\n

CSS has been going through a layout renaissance over the past few years, and I have been keen to explore some Intrinsic Web Design techniques. In particular, I wanted to avoid screen width media queries as much as possible. And as I’m working toward that goal, I’ve been using this site to get better acquainted with CSS Grid.

\n

I’m also using some fluid typography, as well as the shiny new clamp function. I should note that fluid typography utilizes viewport units, which breaks custom default values for users. For that reason, I’ve limited the fluid typography to the page title and site spacing.

\n

Of course, this wouldn’t be modern CSS without a good dose of custom properties. I’m trying to use property names that are more representational of their use and not their description (e.g. --color-main instead of --color-black). This should make it easier for theming in the future for things like a “dark mode.”

\n
:root {
  --color-main: #{$color-black};
  --color-secondary: #{$color-gray-700};
  --color-bg: white;
  --color-bg-secondary: #{$color-gray-200};
  --color-border: #{$color-gray-500};

  --link-color: #{$color-purple};
  --title-color: #{$color-purple};

  --code-bg: #fffafb;
  --code-color: #e2003a;
  --code-border: #ffe7ed;
}
\n

Finally, I’m following the ITCSS way of organization for all of my styles. If given the choice, it’s my preferred methodology. I think the concept of going from wide usage and weak specificity toward very specific, focused styles best represents my mental model of CSS.

\n

Dart Sass

\n

This is the first project where I have fully embraced Dart Sass over node-sass. There are a few reasons for this.

\n

First of all, Dart Sass has the latest and greatest Sass goodies, like Sass modules, which offer a superior experience for limiting the scope of modules and optimizing imports. I personally like the explicitness of creating namespaces so you know what file that magical mixin came from.

\n

Second, in case you haven’t heard, LibSass is being deprecated. It seems Dart Sass will soon be the only supported implementation of Sass. LibSass has been known for its superior speed (an advantage it still has over the JavaScript bindings for Dart Sass), but it has also been plagued with a slow development cycle.

\n

This slow development cycle means LibSass can’t even keep up with the CSS spec. If you attempt to use the max or min functions as they are supported in CSS, you will receive an error due to Sass’s history with these functions. There are workarounds for this and other issues, but I prefer not to bother with them.

\n

Netlify

\n

Finally, in order to get my site to you, I’m using Netlify. There’s nothing really special about my deployment configuration; it’s basically the configuration file that Eleventy generates. The only difference is I’m generating the Sass at build time as well.

\n

Something to note: when I first deployed the new site, I kept getting a build error. It looked like there was a process that wasn’t ending properly. Turns out my the clean script I had added to the build was the culprit. I’ve patched up the issue by creating a separate build step for production only.

\n

I think eventually I would like to write a custom build script, one that relies on environment variables to do things like watch for changes or clean build files. This is something I’ve been trying to work towards in my work on The Container Store website’s front end tooling, and this would be a great place to try some different ideas out.

\n

Metrics

\n

One reason people tend to pick static site generators is performance, so how does my site perform? It depends on what day you’re auditing the site. I’m still tweaking some of my Lighthouse scores, but performance is coming out to a score of 100. Honestly, my Gatsby site had the same score (again, this is not a big site at the moment, and it’s mostly text).

\n
\n \"Performance\n
Site metrics in Lighthouse at original publish date (November 15, 2020)
\n
\n

Some things I need to work on are SEO and some annoying duplicate ID issues that are dinging me on my Accessibility score. Ultimately, the goal is to get to 100 in all categories, and hopefully I’ll get there by the time people are reading this post.

\n

Update: The last few issues have been corrected and now I’m getting all 100s!

\n
\n \"Performance\n
Updated site metrics in Lighthouse on November 16, 2020
\n
\n

The Future

\n

So, I am by no means done with the site. My future plans are to add a contact form that utilizes Netlify forms, add an About page with some more detail about me, and add a bookshelf section that shows what I’ve been reading. In terms of features, I’d like to integrate my Twitter feed into the home page to show my latest TIL (today I learned) tweet, add site-wide messaging, finish the home page layout, and possibly switch from Liquid templates to Vue via Eleventy’s experimental Vue support.

\n

I also want to incorporate more design elements I just haven’t been able to get to, like adding animations and more hand-drawn visuals. I want to be considerate of site performance as well, so I’m cautiously experimenting with different approaches.

\n

Conclusion

\n

So that’s a short overview of my blog’s redesign. I promise there’s more to come, but my ultimate goal is to push past my tendency for perfectionism. You can’t share what you’re doing if you wait for perfection. I hope this has been helpful in some way to you.

\n

Are you in the middle of designing and/or building your own personal project? I want to hear from you. Do you have any questions about my process or the stack I’m using? I want to hear from you, too.

\n

Until next time!

\n", "date_published": "2020-11-15T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/accessibility-is-hard/", "url": "https://www.falldowngoboone.com/blog/accessibility-is-hard/", "title": "Accessibility is hard, but we can do better", "content_html": "

Recently I made the trek to New York City to attend SmashingConf. A recurring theme this year was accessibility, and for good reason. The Domino’s Pizza case has been trending in the Front End Dev community for a while now, and I’ve been preoccupied with accessibility as of late as well, due to circumstances surrounding my current place of employment (I think this would be a good time to state that my opinions expressed are solely my own and do not express the views or opinions of my employer, blah, blah, blah).

\n

While I was in New York, I read Robin Rindle’s CSS-Tricks article Why Are Accessible Websites so Hard to Build, and I think it helps bring to light one of the common misconceptions about corporations and the lack of accessible websites. If I were to sum up my belief why accessible websites are difficult to make, it would be ignorance.

\n

I am an idiot

\n

I remember taking on the task of making an existing web feature accessible, something that I thought in theory I could do rather easily, but it wasn’t until I started to use (or try to use) accessibility tools like VoiceOver that I realized how unequipped I was. To top it off, the entire design and implementation of the feature made it close to impossible to simply bolt accessibility on top (disclosure: I’m the one that built it in the first place. 🤦‍♂️).

\n

This was just one feature. And I thought I initially built it to be accessible. My problem was I had no idea how to confirm my assumptions, nor had I not been instructed on how to test for accessibility. I simply wrote semantic markup and thought that was enough. It was not.

\n

Now imagine a monolithic website created over the course of ten years by dozens of developers, most of whom never even thought about accessibility, and most of whom are no longer with the company. This is what most legacy retail sites are working with.

\n

Lawsuits are not the solution

\n

According to a 2018 report from UsableNet, an independent, full-service accessibility agency, accessibility-related website lawsuits increased from 814 in 2017 to 2,285 in 2018, up 181%. This report states that even companies proactive in making their sites accessible have been targets of these lawsuits.

\n

Rindle in his aforementioned article says his personal hope is that “[these lawsuits] will get folks to care more about semantics and front-end development best practices.” I don’t believe they will. I think they will merely propagate a cat and mouse game between lawyers and corporations where a business will fix one thing only to be called out on another thing that could be interpreted as inaccessible.

\n

The sad reality is the only people that seem to be getting anything out of these lawsuits are the plaintiff and defendant lawyers. They get paid regardless.

\n

Regulation is part of the solution

\n

The basis of these recent lawsuits is the Americans with Disabilities Act, specifically Title III, which “directs [private places of public accommodation] to make ‘reasonable modifications’ to their usual ways of doing things when serving people with disabilities” and also “take steps necessary to communicate effectively with customers with vision, hearing, and speech disabilities” (source).

\n

The ADA became law in 1990, so websites weren’t even considered. There have been several judgements regarding websites as places of public accommodation, all with mixed decisions. To this day, Congress has done little in the way of addressing how to define accessibility with regards to websites, let alone even specifically including websites in the ADA. This, in my opinion, is the number one problem we have right now.

\n

There is some guidance as a result of trial decisions that point to WCAG 2.0 level AA (2.1 is the latest) as the gold standard of accessibility, but a 2018 letter from Assistant Attorney General Stephen E. Boyd seems to suggest that WCAG is not necessarily the baseline for accessibility, stating that “public accommodations have flexibility in how to comply with the ADA’s general requirements of nondiscrimination and effective communication.” This letter, which was written in response to a bipartisan Congressional letter, basically told Congress that they needed to provide more clarity through legislation.

\n

What we need

\n

It is my personal belief that Congress needs to clarify that websites are indeed covered by Title III of the ADA, and with that, Congress needs to provide clear direction of a standard that websites must adhere to (I’m personally in favor of WCAG). I also would like to see the ADA applied to non-brick-and-mortar websites as well. Then entire web needs to held to the same standard.

\n

I also believe there needs to be an official website accessibility certification process that large corporations must go through annually, provided by an independent third-party auditor. Non-compliance would require a business to submit a plan that must be enacted within a reasonable amount of time, during which a company would be immune to Title III related litigation.

\n

Failure to meet the timeline would result in fees, which would go toward policing legislation and accessibility advocacy.

\n

What we can do today

\n

In short, we need to build accessible websites. We need to do better as developers being advocates for minorities. We need to do better as an industry with hiring QA and developers with special needs. Perspective and empathy are invaluable tools to build a better web.

\n

I hope to write more in the future about what I’m doing at The Container Store to promote accessibility, as well as future accessibility wins. If nothing else, my hope is that my co-workers see accessibility as a necessity, not a feature. Ignorance is fought with awareness and empathy.

\n

If you agree (or even if you disagree) with anything I’ve said, let me know on Twitter. And please write to your representative and let them know you want clarity on the protection of individuals with disabilities. Finally, be an advocate for accessibility where you are. Whether you are a developer or designer, you can make a difference where you are.

\n", "date_published": "2019-10-27T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/the-feedback-loop/", "url": "https://www.falldowngoboone.com/blog/the-feedback-loop/", "title": "The Feedback Loop", "content_html": "

Getting feedback fast is one of the most important things in development. What do I mean about feedback?

\n

Let’s imagine playing a video game. You have a console, a controller, and a screen. If you press left on the controller’s d-pad, your character walks to the left on the screen. If you press right on the d-pad, your character walks right. Makes sense, right?

\n

Of course, if you’ve ever used a sketch online video game service, you may be familiar with lag. Maybe you press right on your d-pad and your character waits a split second before walking to the right. Not terrible lag, but enough to notice. Maybe the lag’s even worse. Maybe you press right and nothing happens, then you press left and your character walks to the right. This is arguably not only going to affect your game, but also how you perceive the game.

\n

In video games, you’re used to immediate feedback. What you input into the controller gets translated immediately (at least perceptively) to the screen. This is one of the fundamental reasons certain video games are easy to pick up and learn. Any lag in this feedback loop makes learning incredibly difficult and frustrating.

\n

Now, instead of a screen and a controller, imagine a text editor and an open browser. It doesn’t take too much of an imagination to see the same rule applies to development.

\n

When I start a new project, the first thing I do is figure out how to establish a feedback loop. A good example of this is a project I’m currently working on. It involves consuming a SOAP service and marshalling the responses to Java objects so they are ultimately expressed as JSON to a JavaScript front end. You may have no idea what some of that means (at the beginning of last week, I didn’t either), but that’s why establishing a feedback loop early is so important. The more direct and immediate the feedback, the more confidence I can have in my experimentation with the code.

\n

The way I established a feedback loop in this case was to create a REST-ful endpoint on the Java app where I could GET arbitrary information. Then, after rigorous (and tedious) configuration on the SOAP service part, I began retrieving information and printing it to the screen.

\n

Is this the best feedback loop? Maybe, maybe not. The point is, it’s good enough for now. The more I work on this project, the better (hopefully) my feedback loop will get.

\n

Good feedback loops are important. If you’re new to coding, work on establishing a good feedback loop immediately. Learn to identify when you need more information, then learn how to get that information. Maybe it’s a well-placed console.log. Maybe it’s dumping the contents of an object to the screen. Whatever it is, make sure it gives you the most direct information in the quickest way possible.

\n", "date_published": "2019-09-29T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/container-component-pattern-using-context-and-hooks/", "url": "https://www.falldowngoboone.com/blog/container-component-pattern-using-context-and-hooks/", "title": "React Presentational and Container Components Using Context and Hooks", "content_html": "

Updated: I’ve updated the code to export a named function, not an anonymous arrow function.

\n

When I first started using React, I learned about Presentational and Container Components from Dan Abramov. This pattern prescribed splitting UI into smart (container) components that encapsulated state and logic, and dumb (presentational) components that simply presented data in a styled manner. In general, the containers were class components that managed state and lifecycle methods, whereas presentational components were stateless function components.

\n
// List.js

// presentational component
export default function List({ items = [] }) {
  return (
    <ul class=\"styled-list\">
      {Boolean(items.length) &&
        items.map((item) => <li class=\"styled-item\" {...item} />)}
    </ul>
  );
}

// MovieContainer.js

// container component
export default class MovieContainer extends React.Component {
  state = {
    movies: [],
  };

  async componentDidMount() {
    const movies = await movieService.fetch();
    this.setState({ movies });
  }

  render() {
    return typeof this.props.children === 'function'
      ? this.props.children(this.state)
      : React.Children.map(this.props.children, { movies: this.state.movies });
  }
}

// MovieList.js

// put it together (children as function FTW!)
export default function MovieList() {
  return (
    <MovieContainer>{({ movies }) => <List items={movies} />}</MovieContainer>
  );
}
\n

This pattern both decouples views from logic and creates logic that is easily shared. If you need to represent albums as a list, replace <MovieContainer /> with <AlbumContainer />. If you need to represent movies as a grid, replace <List /> with a <Grid /> component. This pattern is flexible and effective, but it was not without its problems.

\n

First of all, this pattern makes use of class components, which, at least in my experience, bring with them all sorts of developer pain (React specifically; I’m not above using classes when appropriate). Second of all, lifecycle methods tend to break up related logic, so the more complex your components become, any changes introduced significantly increase the chance of bugs.

\n

To address these problems (and more), the React team introduced the Hooks API. Using Hooks, you can easily encapsulate complex logic without the use of class components. One result was the ability to have stateful function components.

\n

Now that we can move logic into custom hooks, we no longer need container components that control state for us. We can handle calls to these hooks inside the presentational components themselves.

\n

I pair the Context API with Hooks, particularly the useContext hook, to recreate the Presentational and Container Component pattern without any classes whatsoever:

\n
// List.js

export default function List({ items = [] }) {
  /* no changes */
}

// MovieProvider.js

export const MovieContext = React.createContext();

export function useMovies() {
  const context = React.useContext(MovieContext);
  if (!context) {
    throw new Error('Use inside context provider!');
  }
  return context;
}

export function MovieProvider({ children }) {
  const [movies, setMovies] = useState([]);
  React.useEffect(() => {
    // you can't pass async functions to Hooks
    movieService.fetch().then(setMovies);
  }, [setMovies]);
  return (
    <MovieContext.Provider value={movies}>{children}</MovieContext.Provider>
  );
}

// MovieList.js

export function MovieList() {
  const movies = useMovies();
  return <List items={movies} />;
}

// You need to wrap the component with the context
// provider somewhere. Here we've exported a \"connected\"
// version already wrapped. Don't do this if you need
// to consume a single provider in multiple components.
export default function ConnectedMovieList() {
  return (
    <MovieProvider>
      <MovieList />
    </MovieProvider>
  );
}
\n

Note that the presentational <List /> component remains unchanged, but now we are grabbing the movies state from a custom hook and applying it directly to <List /> without the need for a child function. This ends up being so much more readable and, in my opinion, easier to follow compared to the original. The “Container” component becomes a combination of a context provider and hook.

\n

It doesn’t take much to imagine getting more types of state out of the useMovies hook, like a loading state or an error message in the case of service failure. When your state management becomes more complex, you can look at using the useReducer Hook in lieu of useState. In that case, it’s recommended you pass the resulting dispatch method down in a separate context:

\n
// List.js

export default function List({ items = [] }) {
  /* no changes */
}

// MovieProvider.js

// now we have two contexts
export const MovieStateContext = React.createContext();
export const MovieDispatchContext = React.createContext();

export function useMovieState() {
  const state = React.useContext(MovieStateContext);
  if (!context) {
    throw new Error('Use inside context provider!');
  }
  return state;
}

export function useMovieDispatch() {
  const dispatch = React.useContext(MovieDispatchContext);
  if (!context) {
    throw new Error('Use inside context provider!');
  }
  return dispatch;
}

function MovieReducer(state, action) {
  /* reducer logic in here */
}

const initialState = {
  isLoading: false,
  error: '',
  movies: [],
};

export function MovieProvider({ children }) {
  const [movieState, dispatch] = React.useReducer(movieReducer, initialState);
  React.useEffect(() => fetchMovies(dispatch), [dispatch]);
  return (
    <MovieStateContext.Provider value={movieState}>
      <MovieDispatchContext.Provider value={dispatch}>
        {children}
      </MovieDispatchContext.Provider>
    </MovieStateContext.Provider>
  );
}

// completely ripped off from Kent C. Dodds and Dan Abramov;
// now you can async await all the things!
export async function fetchMovies(dispatch) {
  dispatch({ type: 'pending' });
  try {
    const movies = await movieService.fetch();
    dispatch({ type: 'success', payload: movies });
  } catch (error) {
    dispatch({ type: 'error', payload: error.message });
  }
}

// MovieList.js

export function MovieList() {
  const { isLoading, error, movies } = useMovies();
  return isLoading ? (
    <LoadingAnimation />
  ) : error ? (
    <Message type=\"error\">{error}</Message>
  ) : (
    <List items={movies} />
  );
}

export default function ConnectedMovieList() {
  /* same as above */
}
\n

This is pretty much how I structure my components now. The advantage of this pattern is that I can wrap components with providers that override state for use in Storybook or tests. I can also easily keep my styled presentational components separate from my logic.

\n

Of course, now you have the overhead of understanding how closures can affect your values in Hooks. Also, Hooks have a strict set of guidelines you have to adhere to (only call Hooks inside a component or other Hook, don’t call conditionally, don’t call in loops, etc.). But if you can accept that, you can enjoy fewer bugs and more sharable logic.

\n", "date_published": "2019-09-15T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/free-online-web-design-and-dev-books/", "url": "https://www.falldowngoboone.com/blog/free-online-web-design-and-dev-books/", "title": "Free Online Web Design and Development Books", "content_html": "

One of my favorite pastimes is reading. When I started out as a developer, I would read anything I could get my hands on. And, since I was cheap, I tried to find as many free books as I could. What follows is a list that I’ve accumulated over the past few years of fantastic, completely free material that has helped me grow as a developer.

\n

A quick note before I get started: If you like what you’re reading, consider either buying the original source material or making a donation to the author. When you do that, you are paving the way for even more publicly available, high-quality material. Okay, here’s the list!

\n

Web Design

\n

Software developers are designers by extension. We interpret (or sometimes ignore) what we are given by designers. If you want to become a better developer, I would argue you need to build empathy for good design.

\n

Atomic Design

\n

When I grow up, I want to be Brad Frost. His material was heavily inspirational in my early freelance web design career. In Atomic Design, Brad introduces the concept of how to break a web design down into systems instead of pages. This is required reading for anyone who designs or develops design systems. This is one book I highly recommend buying.

\n

Read Atomic Design by Brad Frost.

\n

Buy Atomic Design by Brad Frost.

\n

Resilient web design

\n

Jeremy Keith is a thought leader in the web design community. This book (beautifully designed for reading on a screen) is a call to embrace inclusivity in web design and development. This book, and anything written by Jeremy Keith, makes me want to be a better web developer.

\n

Read Resilient web design by Jeremy Keith

\n

The Shape of Design

\n

Frank Chimero’s treatise on design is both beautiful and useful, whether in digital or printed form. You will come away from this book believing that, as software developers, we are uniquely positioned to build things that can shape the design of this world.

\n

Read The Shape of Design by Frank Chimero.

\n

Buy The Shape of Design by Frank Chimero.

\n

Butterick’s Practical Typography

\n

If you want to become a better frontend developer, you need to learn what makes for good typography. This resource by Matthew Butterick is an extensive journey through the core concepts of typography. Bookmark this and return to it frequently.

\n

Read Butterick’s Practical Typography by Matthew Butterick.

\n

Support Matthew Butterick.

\n

Frontend Development

\n

Learning JavaScript Design Patterns

\n

Addy Osmani is a developer at Google, and back in 2012 he wrote a book that completely jumpstarted my interest in JavaScript development. This book (revised in 2017 online only) introduces the idea of programming design patterns, what they are, why they’re useful, etc., and then shows how to implement some of them in JavaScript. The idea of design patterns in software ignited my imagination, and I haven’t stopped learning since. This is a useful book whether you are a beginner or a more advanced developer.

\n

Read Learning JavaScript Design Patterns by Addy Osmani.

\n

Eloquent JavaScript

\n

This is another book I was heavily inspired by early on in my developer career. Marjin Haverbeke’s introduction to JavaScript is thorough, with great example snippets you can interact with directly in the browser. If you are learning JavaScript, this is a great place to start. I would highly recommend buying this one to have around the house or office.

\n

Read Eloquent JavaScript by Marjin Haverbeke

\n

Buy Eloquent JavaScript by Marjin Haverbeke

\n

Front End Developer Handbook (updated yearly)

\n

Frontend Masters is an online learning website that is known for their quality, up-to-date front end info, and starting in 2018, they started releasing these nice handbooks that highlight some current front end best practices. I highly recommend both the handbooks and Frontend Masters’ paid content.

\n

Read Front End Developer Handbook 2019

\n

General Programming

\n

You Don’t Know JS

\n

JavaScript can be confusing and frustrating, but Kyle Simpson is here to help you make sense of it all. The YDKJS series focuses on one or two topics per book, and they are honestly the best place to start when you decide to take the JS plunge. Highly recommend you buy these babies (“Scope and Closures” and “this & Object Prototypes” are required reading IMO), but they are totally free to read on GitHub. Oh, and it looks like a second edition is in the works.

\n

Read You Don’t Know JS 1st Edition by Kyle Simpson.

\n

Buy You Don’t Know JS: Up & Going by Kyle Simpson.

\n

Buy You Don’t Know JS: Scope & Closures by Kyle Simpson.

\n

Buy You Don’t Know JS: this & Object Prototypes by Kyle Simpson.

\n

Buy You Don’t Know JS: Types & Grammar by Kyle Simpson.

\n

Buy You Don’t Know JS: Async & Performance by Kyle Simpson.

\n

Buy You Don’t Know JS: ES6 & Beyond by Kyle Simpson.

\n

Functional-Light JavaScript

\n

Kyle Simpson knows JS, and he also knows functional programming. To prove it, he wrote a whole book about it. This book, squarely aimed at the beginner, effectively introduces the core concepts of functional programming, something I’m excited about. There’s even a Frontend Masters class if you are so inclined.

\n

Read Functional-Light JavaScript by Kyle Simpson.

\n

Buy Functional-Light JavaScript by Kyle Simpson.

\n

Professor Frisby’s Mostly Adequate Guide to Functional Programming

\n

Okay, this is definitely an advanced book. Functional programming is one of those concepts that takes a while to get, but in my opinion, it’s well worth it. This book introduces the core concepts of functional programming through the voice of Professor Frisby, a cute, unassuming badger that somehow learned to type and then get tenure at university. Later, the book gets super heady. I honestly struggled to finish, but the beginning stuff is gold.

\n

Read Professor Frisby’s Mostly Adequate Guide to Functional Programming.

\n

Software Architecture

\n

The Twelve-Factor App

\n

I learned about The Twelve Factor App from David Ayers, who was the Technology Director at the time I started at The Container Store. It piqued my curiosity regarding technical architecture, and now I’m actually starting understand some of it.

\n

Read The Twelve-Factor App by Adam Wiggins.

\n

Programming JavaScript Applications

\n

This book by Eric Elliott is a bit long in the tooth (it was published in the ancient year of 2014), but it’s filled with super-useful, still-relevant architectural concepts for building applications that go well beyond the world of JavaScript. Just know this is not a book for beginners. Try reading this after you have a few projects under the belt.

\n

Read Programming JavaScript Applications by Eric Elliott.

\n

Buy Programming JavaScript Applications by Eric Elliott.

\n", "date_published": "2019-09-08T00:00:00Z" },{ "id": "https://www.falldowngoboone.com/blog/get-started-with-coding/", "url": "https://www.falldowngoboone.com/blog/get-started-with-coding/", "title": "Where to start your development career", "content_html": "

Becoming a career developer can be challenging at times. With a ton of material out of the internet, it can be difficult to know where to start. And even if you know where to start, it can be difficult to stay motivated.

\n

What follows is a brain dump of tips to help you on your journey to coding greatness. I don’t go too deep into anything here, but I may use some of these tips as a jumping off point for future posts.

\n

Become friends with your terminal

\n

I was intimidated when I first started using my terminal, but now I use it every day. You may be intimidated as well. If you are, know there is hope. The more your use your terminal, the more comfortable you will be with it.

\n

Start with simple tasks, like learning how to navigate your computer or how to read a file. Then, work your way up to more powerful tasks, like creating, updating or deleting files, as well as how to pipe data through multiple tasks. Maybe even do a deep dive into bash.

\n

Learn how to git

\n

Git is by far the most popular version control system (VCS) available today, and if you want a career in software development, you need to learn how to use it. Preferably within the context of a team.

\n

Start a Github account. Push and pull code to and from your repo. Create a new branch and open a pull request. And if you’re feeling adventurous, learn git’s internals.

\n

Take a class

\n

There are literally hundreds of places to learn development online. My advice is to look for classes that encourage you to build things. It’s also important to get feedback on what you make. Get involved in the class’s community. Show your work. Ask questions. If your class doesn’t provide a channel for feedback, contact me. You can never truly learn where you need improvement without the input of others.

\n

If you want to supercharge your learning (and you have the time and money), do a bootcamp. Keep in mind bootcamps are usually designed to expose you to the most current concepts and frameworks in a short amount of time. They are focused on giving you a breadth of knowledge, not necessarily depth. But they also usually help with job placement.

\n

Join a community

\n

No developer is an island. You need a community of people with like interests that inspire and motivate you on a regular basis. Find some dev meetups. Join a dev Slack group. Put yourself out there and make some connections.

\n

Keep at it

\n

Learning to code is not easy. It will stretch your brain in ways you never thought possible. But you can do it. I know you can because I did. It took me four years while working a full-time job, but I was able to make the move from designer to developer.

\n

Honestly, I think the most difficult thing I had to do was figure out what I wanted to do with coding. Being a designer, I naturally gravitated to front-end development, but I wasn’t really sure. It took getting my current job at The Container Store to help me realize I’m passionate about accessibility, scalable CSS, and building UI.

\n

Build things. Get help when you’re stuck. And don’t be afraid to take on challenges you may not be able to accomplish. When you’re first starting out, you have to figure out what ignites your curiosity.

\n

If you thought this was helpful, or if you have any questions, let me know on Twitter or drop me an email. I am always eager to help.

\n", "date_published": "2019-06-18T00:00:00Z" } ] }