Steven Woodson

Adding Bluesky Activity to an Eleventy Blog

2026-04-03T15:58:37.000Z

I’ve been noticing so many folks adding Bluesky likes and comments to their personal blogs, after tacking on webmentions a while back I thought it’d be a great addition to mine too. So, I finally made some time to get it added.

I’ll share some implementation notes first, then the 11ty-centric code that pulls the feed and displays it. My solution was deeply inspired by the notes and code graciously shared by a handful of folks, I’ve linked to their content at the bottom of this post.

Let’s dive in!

Implementation Notes

I’ll admit this was simpler than I had anticipated, the public API has everything you’ll need to grab likes, reshares, and responses. That said, I wanted to make note of a few specifics that you may want to change depending on how you want this set up.

Eleventy-specific

This is specific to an 11ty (now Build Awesome) build, but the JavaScript is largely portable. All you’d need to change is how you cache the responses, or include eleventy-fetch into your project.

Static HTML Rendering

I’m going against the grain a bit and am only grabbing Bluesky data when the site is built.

Pros – No need for client-side JavaScript, more performant
Cons – Not real-time, so my site will lag behind a bit

I felt the pros outweighed the cons for my own case. I’m humble enough to admit I don’t get the most social media activity, so I’m okay if a like on one of my posts takes a couple hours to show up on my blog.

Bluesky Post URL

This (any?) Bluesky reactions implementation necessitates that you have a Bluesky post URL somehow attributed to your blog posts. For static files, that’d be as simple as adding bluesky to your frontmatter and updating the Javascript to grab that instead of post.custom_fields.bluesky.

If you’re pulling blog data from elsewhere then it’ll need to come with that payload somehow. In my case, all my blog data is coming from a headless WordPress implementation so I’m saving the Bluesky post URL as a WP native custom field.

Code

Finally, some code!

bluesky.js

Here’s my full bluesky.js data file, it’s grabbing and caching all Bluesky likes, reshares, and responses for any post with a bluesky post url attributed.

import { AssetCache } from "@11ty/eleventy-fetch";
import getBlogposts from "./blogposts.js";

const BSKY_API = "https://public.api.bsky.app/xrpc";

/**
 * Parse a bsky.app URL into handle and post rkey
 * e.g. https://bsky.app/profile/stevenwoodson.com/post/3jzu2ove5g22i
 */
function parseBskyUrl(url) {
  const match = url.match(/bsky\.app\/profile\/([^/]+)\/post\/([a-zA-Z0-9]+)/);
  if (!match) return null;
  return { handle: match[1], rkey: match[2] };
}

/**
 * Resolve a Bluesky handle to a DID
 */
async function resolveHandle(handle) {
  try {
    const params = new URLSearchParams({ handle });
    const response = await fetch(
      `${BSKY_API}/com.atproto.identity.resolveHandle?${params}`,
    );
    const data = await response.json();
    if (!data?.did) {
      throw new Error(`Could not resolve handle: ${handle}`);
    }
    return data.did;
  } catch (err) {
    throw new Error(`Failed to resolve handle ${handle}: ${err.message}`);
  }
}

/**
 * Fetch the post thread (replies)
 */
async function getPostThread(uri) {
  try {
    const params = new URLSearchParams({ uri, depth: 10 });
    const response = await fetch(
      `${BSKY_API}/app.bsky.feed.getPostThread?${params}`,
    );
    const data = await response.json();
    if (!data?.thread) {
      throw new Error(`No thread data returned for URI: ${uri}`);
    }
    return data.thread;
  } catch (err) {
    throw new Error(`Failed to fetch thread ${uri}: ${err.message}`);
  }
}

/**
 * Fetch likes for a post
 */
async function getLikes(uri) {
  try {
    const likes = [];
    let cursor;

    do {
      const params = { uri, limit: 100 };
      if (cursor) params.cursor = cursor;
      const response = await fetch(
        `${BSKY_API}/app.bsky.feed.getLikes?${new URLSearchParams(params)}`,
      );
      const data = await response.json();
      if (data?.likes) {
        likes.push(...data.likes);
      }
      cursor = data?.cursor;
    } while (cursor);

    return likes;
  } catch (err) {
    throw new Error(`Failed to fetch likes for ${uri}: ${err.message}`);
  }
}

/**
 * Fetch reposters for a post
 */
async function getReposters(uri) {
  try {
    const reposters = [];
    let cursor;

    do {
      const params = { uri, limit: 100 };
      if (cursor) params.cursor = cursor;
      const response = await fetch(
        `${BSKY_API}/app.bsky.feed.getRepostedBy?${new URLSearchParams(params)}`,
      );
      const data = await response.json();
      if (data?.repostedBy) {
        reposters.push(...data.repostedBy);
      }
      cursor = data?.cursor;
    } while (cursor);

    return reposters;
  } catch (err) {
    throw new Error(`Failed to fetch reposters for ${uri}: ${err.message}`);
  }
}

/**
 * Flatten replies from a thread into a simple list
 */
function extractReplies(thread) {
  const replies = [];
  if (!thread?.replies) return replies;

  for (const reply of thread.replies) {
    if (
      reply.post &&
      reply.post.author &&
      reply.post.author.did &&
      reply.post.uri
    ) {
      replies.push({
        author: {
          name:
            reply.post.author.displayName ||
            reply.post.author.handle ||
            "Unknown",
          handle: reply.post.author.handle || "unknown",
          avatar: reply.post.author.avatar || null,
          did: reply.post.author.did,
        },
        text: reply.post.record?.text || "",
        createdAt: reply.post.record?.createdAt || null,
        likeCount: reply.post.likeCount || 0,
        replyCount: reply.post.replyCount || 0,
        url: `https://bsky.app/profile/${reply.post.author.handle || reply.post.author.did || ""}/post/${reply.post.uri.split("/").pop()}`,
        replies: extractReplies(reply),
      });
    }
  }

  // Sort by likes descending
  replies.sort((a, b) => b.likeCount - a.likeCount);
  return replies;
}

/**
 * Fetch all Bluesky reactions for a single post URL
 */
async function fetchBlueskyData(bskyUrl) {
  const parsed = parseBskyUrl(bskyUrl);
  if (!parsed) {
    throw new Error(`Invalid Bluesky URL: ${bskyUrl}`);
  }

  const did = await resolveHandle(parsed.handle);
  if (!did) {
    throw new Error(`Could not resolve DID for handle: ${parsed.handle}`);
  }

  const atUri = `at://${did}/app.bsky.feed.post/${parsed.rkey}`;

  const [thread, likes, reposters] = await Promise.all([
    getPostThread(atUri),
    getLikes(atUri),
    getReposters(atUri),
  ]);

  if (!thread || !thread.post) {
    throw new Error(`Invalid thread data for ${atUri}`);
  }

  const postUrl = `https://bsky.app/profile/${did}/post/${parsed.rkey}`;

  return {
    postUrl,
    likes: likes.map((like) => ({
      name: like.actor?.displayName || like.actor?.handle || "Unknown",
      handle: like.actor?.handle || "unknown",
      avatar: like.actor?.avatar || null,
      url: `https://bsky.app/profile/${like.actor?.handle || like.actor?.did || ""}`,
    })),
    reposters: reposters.map((reposter) => ({
      name: reposter.displayName || reposter.handle || "Unknown",
      handle: reposter.handle || "unknown",
      avatar: reposter.avatar || null,
      url: `https://bsky.app/profile/${reposter.handle || reposter.did || ""}`,
    })),
    replies: extractReplies(thread),
    likeCount: likes.length,
    repostCount: reposters.length,
    replyCount: thread.replies ? thread.replies.length : 0,
  };
}

export default async () => {
  const cache = new AssetCache("bluesky");

  if (cache.isCacheValid("2h")) {
    console.log("Using cached bluesky");
    return cache.getCachedValue();
  }

  console.log("Fetching Bluesky comments...");
  const blogposts = await getBlogposts();
  const postsWithBluesky = blogposts.filter(
    (post) => post.custom_fields?.bluesky,
  );

  if (postsWithBluesky.length === 0) {
    console.log("No blog posts with Bluesky URLs found");
    const empty = {};
    await cache.save(empty, "json");
    return empty;
  }

  console.log(`Found ${postsWithBluesky.length} blog posts with Bluesky URLs`);

  const results = {};

  for (const post of postsWithBluesky) {
    try {
      const data = await fetchBlueskyData(post.custom_fields.bluesky);
      if (data) {
        results[post.slug] = data;
      }
    } catch (err) {
      console.warn(
        `Failed to fetch Bluesky data for "${post.slug}":`,
        err.message,
      );
    }
  }

  await cache.save(results, "json");
  return results;
};

Filters

I then set up these two filters for use in my template.

  blueskyBySlug: (bluesky, slug) => {
    return bluesky && bluesky[slug] ? bluesky[slug] : null;
  },
  blueskyIsOwn: (handle) => {
    return handle === "stevenwoodson.com";
  },

The first one blueskyBySlug grabs the Bluesky data for that particular post, based on its slug. The second one blueskyIsOwn helps me add a little extra styling for responses that are from me.

Template Partial

I then pull from the data gathered using the filter when rendering each post, here’s the full partial file that I’m using just below the post content.

{% set blueskyData = bluesky | blueskyBySlug(blogpost.slug) %}

<div class="l-bluesky flow">
  {% if blueskyData %}
    {% if (blueskyData.likeCount > 0) 
      or(blueskyData.repostCount > 0)or(blueskyData.replyCount > 0) %}
      <header data-header-type="inline">
        <h2 class="headline3" id="bluesky-reactions">
          <span aria-hidden="true" class="fe fe-Bluesky"></span> Bluesky Reactions</h2>
        <a href="{{ blueskyData.postUrl }}" rel="noopener noreferrer">View on Bluesky</a>
      </header>
    {% endif %}

    {% if blueskyData.likeCount > 0 %}
      <h3 class="headline5">
        <span aria-hidden="true" class="fe fe-thumbs-up"></span>
        {{ blueskyData.likeCount }}
        {% if blueskyData.likeCount == 1 %}Like{% else %}Likes{% endif %}
      </h3>
      <div class="avatars">
        {% for like in blueskyData.likes %}
          <a class="bluesky-avatar" href="{{ like.url }}" rel="noopener noreferrer">
            {% if like.avatar %}
              <img src="{{ like.avatar }}" alt="{{ like.name }}" class="avatar" loading="lazy">
            {% else %}
              <img src="{{ '/assets/images/default-avatar.gif' | url }}" alt="{{ like.name }}" class="avatar" loading="lazy">
            {% endif %}
          </a>
        {% endfor %}
      </div>
    {% endif %}

    {% if blueskyData.repostCount > 0 %}
      <h3 class="headline5">
        <span aria-hidden="true" class="fe fe-repeat"></span>
        {{ blueskyData.repostCount }}
        {% if blueskyData.repostCount == 1 %}Repost{% else %}Reposts{% endif %}
      </h3>
      <div class="avatars">
        {% for reposter in blueskyData.reposters %}
          <a class="bluesky-avatar" href="{{ reposter.url }}" rel="noopener noreferrer">
            {% if reposter.avatar %}
              <img src="{{ reposter.avatar }}" alt="{{ reposter.name }}" class="avatar" loading="lazy">
            {% else %}
              <img src="{{ '/assets/images/default-avatar.gif' | url }}" alt="{{ reposter.name }}" class="avatar" loading="lazy">
            {% endif %}
          </a>
        {% endfor %}
      </div>
    {% endif %}

    {% if blueskyData.replyCount > 0 %}
      <h3 class="headline5">
        <span aria-hidden="true" class="fe fe-message-square"></span>
        {{ blueskyData.replyCount }}
        {% if blueskyData.replyCount == 1 %}Reply{% else %}Replies{% endif %}
      </h3>
      {% macro blueskyReply(reply) %}
        {% if reply.text %}
          {% set blueskyHandle = reply.author.handle | default('') | lower | replace('@', '') %}
          <li class="reply bluesky-reply{% if blueskyHandle|blueskyIsOwn %} reply--own{% endif %}">
            <div class="reply__meta">
              {% if reply.author.avatar %}
                <img src="{{ reply.author.avatar }}" alt="{{ reply.author.name }}" class="avatar" loading="lazy">
              {% else %}
                <img src="{{ '/assets/images/default-avatar.gif' | url }}" alt="" class="avatar" loading="lazy">
              {% endif %}
              <p>
                <strong>
                  <a href="{{ reply.url }}" rel="noopener noreferrer">{{ reply.author.name }}</a>
                  {% if reply.createdAt %}
                    on <time datetime="{{ reply.createdAt }}">{{ reply.createdAt | readableDateFromISO }}</time>
                  {% endif %}
                </strong>
              </p>
            </div>
            <div class="reply__content">
              {{ reply.text }}
            </div>
            <small class="bluesky-reply-meta">
              {{ reply.likeCount }}
              {% if reply.likeCount == 1 %}like{% else %}likes{% endif %} &bull;
              {{ reply.replyCount }}
              {% if reply.replyCount == 1 %}reply{% else %}replies{% endif %}
            </small>
            {% if reply.replies and reply.replies.length > 0 %}
              <ul class="replies bluesky-nested-replies">
                {% for childReply in reply.replies %}
                  {{ blueskyReply(childReply) }}
                {% endfor %}
            </ul>
          {% endif %}
        </li>
      {% endif %}
    {% endmacro %}
    <ul class="replies">
      {% for reply in blueskyData.replies %}
        {{ blueskyReply(reply) }}
      {% endfor %}
    </ul>
  {% endif %}
{% endif %}
</div>

Shout outs

Shout out to these folks who added Bluesky content to their blogs as well, and also chose to write about their process:

How I show Bluesky likes on my blog posts by Salma Alam-Naylor
How I added Bluesky likes to my Astro blog by Luciano Mammino
Bluesky Likes Web Components by Lea Verou
Adding Bluesky Comments to 11ty Blog by Joseph Jude
I finally added Bluesky comments and likes to my blog (and you can too!) by Brittany Ellich
Adding Bluesky Comments to Your Astro Blog by Jade Garafola

Why Every Client Relationship Matters More Now

2024-12-01T13:47:06.000Z

Saying goodbye to a client is always tough, but as a freelance consultant, it feels profoundly different from my agency days. Back then, wrapping up a project was just another routine in the consulting lifecycle—finishing one assignment, then smoothly transitioning to the next. I’d write out some documentation, exchange brief pleasantries and occasionally connect on LinkedIn or share emails, and move on without much emotional investment.

Recently, I said farewell to one of my first long-term clients as a freelancer, and the experience cut deeper than I expected. We parted on great terms, even leaving the door open for potential future collaboration, but something about the goodbye felt more personal, more significant.

As I’ve reflected on this feeling, I’ve realized the core difference: when you’re a freelancer, you’re not just delivering a service—you’re building relationships under your own name and reputation. Every project is a direct reflection of you, not an agency’s broader portfolio. This shifts everything. I found myself investing more deeply, caring more intensely about the work and the people behind the project.

These clients have become more than just professional contacts. In many ways, they’ve replaced the co-workers I no longer see daily. When the project ended, it didn’t feel like a simple contract conclusion—it felt like saying goodbye to colleagues, to a temporary work family.

This emotional complexity is new territory for me. I’m learning that giving every client my absolute best means opening myself up to deeper connections—and potentially deeper goodbyes. But I’m not going to change my approach. These genuine relationships are a strength, not a weakness. They’re what set independent consultants apart.

As I move forward, I’ll continue to pour my full self into each project, knowing that professionalism and personal connection aren’t mutually exclusive. They’re what make freelance consulting not just a job, but a meaningful professional journey.

In the end, this was a great reminder of why I pursued this path in the first place.

Fluid Font Size by Character Count

2024-03-17T20:13:10.000Z

I recently had a use case where CMS provided headlines needed to reasonably fit into a well defined space within a hero section. The hope was to fill that space a bit better by using larger font sizes for short headlines, and smaller sizes for longer ones, all based on character length.

The Result

Putting the end result up here at the top because I know you’re pressed for time and just want Something That Works™️

See the Pen Length-dependent Font Size by Steve Woodson (@stevenwoodson) on CodePen.

The part you want to copy is the JavaScript, the CSS is mostly just for illustrative purposes as is most of the HTML. Here’s how to use it:

Add the JavaScript to your page
Change any of the six variables (minFontSize, maxFontSize, minLineLength, maxLineLength, minViewportWidth, maxViewportWidth) to fit your needs.
Add data-dynamic-font-size to any headline you want to have this fluid size

How it Works

The TL;DR is “with CSS Clamp and a bit of JavaScript”, read on for something a bit more descriptive.

The Variables

We need a general range of characters that should affect the font sizing. This could vary based on the amount of space you have available. These are defined in minLineLength and maxLineLength.

We also need to know how big (and small) the text should be allowed to get. These are defined (in pixels) in minFontSize and maxFontSize.

Finally, we need to know the range of browser widths that should affect the calculations. These are also in pixel values and are defined in minViewportWidth and maxViewportWidth.

Relative Max Size

The first thing we need is a character count of the text in the container we’re referencing. This is achieved by the line dynamicFontEl.textContent.replace(/(<([^>]+)>)/gi, "").trim().length towards the bottom. That’s stripping out any HTML tags and then trimming before getting a string count.

With the variables and the total number of characters defined, the first calculation is to determine the ideal max font size for that character length, this is gathered in relativeMaxFontSize. The fewer characters there are, the more space there is available to make the font size bigger.

const relativeMaxFontSize =
  textLength < minLineLength
    ? maxFontSize
    : textLength > maxLineLength
    ? minFontSize
    : maxFontSize -
      ((maxFontSize - minFontSize) * (textLength - minLineLength)) /
        (maxLineLength - minLineLength);

Some examples to illustrate:

If the text is less than or equal to minLineLength, the font size will be maxFontSize
If the text is in between the min and max line length, we calculate where in that range it is and use the same range percentage for the font size. So a line length that is right in the middle of the min and max would lead to a font size right in the middle too.
If the text is greater than or equal to maxLineLength, the font size will be minFontSize

Introducing Clamp

We could stick with just the calculation above, set that resulting relativeMaxFontSize to be the font size of the container and call it a day. But, I wanted to make use of fluid typography so the text would size appropriately on smaller viewports too. This is where good old CSS clamp comes in.

First we calculate a subsection of the viewport width range set in minViewportWidth and maxViewportWidth relative to the max size we calculated before. We’re doing this because we don’t need the smallest character length headlines to size down until much smaller than the rest. Less characters means it can stick around at the larger size for longer without unwanted line breaks.

// Relative max viewport width, gets smaller the bigger the font size so it doesn't resize too soon
const relativeMaxViewportWidth =
  maxViewportWidth * (minFontSize / relativeMaxFontSize);

// Relative min viewport width, gets bigger the smaller the font size so it doesn't resize too late
const relativeMinViewportWidth =
  minViewportWidth * (maxFontSize / relativeMaxFontSize);

// Viewport width calculations
const viewportWidth =
  (100 * (maxFontSize - minFontSize)) /
  (relativeMaxViewportWidth - relativeMinViewportWidth);

Then, we get the viewportWidth and relativeFontSize to use in the clamp(). These are using the relative viewport sizes to adjust the font size at the right viewport size for that character length.

// Viewport width calculations
const viewportWidth =
  (100 * (maxFontSize - minFontSize)) /
  (relativeMaxViewportWidth - relativeMinViewportWidth);

// Relative font size calculation
const relativeFontSize =
  (relativeMinViewportWidth * maxFontSize -
    relativeMaxViewportWidth * minFontSize) /
  (relativeMinViewportWidth - relativeMaxViewportWidth);

Finally, we’re ready to pull together the final clamp values!

The clamp min is always going to be minFontSize represented in rem values, the clamp max value uses relativeMaxFontSize, because we want to make sure it’s not allowed to ever get any bigger than that. The current font size uses all that calculation magic above and is set to ${viewportWidth}vw + ${relativeFontSize / 16}rem.

The End Result

What we’re left with is a calculated font size that is bigger the shorter the text gets, and that font size fluidly resizes based on the viewport width at the ideal time for the size and space available.

The best way to get a better sense for how this works is to open up that CodePen shared above in a new tab and resize the browser. You’ll notice that the last (longest and smallest) headline doesn’t resize at all, and each subsequent headline going up will start to resize one after the other.

All filling the available space as well as they possibly could. Pretty cool, right?

References

I’m always big on giving credit to the posts and projects that inspired me, here’s some for this work in no particular order:

Practical Developer Tips for Digital Accessibility Advocacy

2023-12-11T12:17:07.000Z

Hat tip to all the other digital accessibility focused folks out there, fighting the good fight to advocate, educate, and drive accessibility forward.

This post is my little contribution to the rallying cry of doing everything we can to push digital accessibility and equal access forward. This is coming from my perspective as a web developer so these tips are going to skew pretty heavily in that direction, but I’m hopeful they give you ideas for your own unique situation.

Sometimes, all we need is to give ourselves permission to just do it anyway.

It’s hard out there

The difficulty of accessibility focused work is well known, and others far smarter than me have written some thoughtful articles about it.

Stress and adversity are standard for people who have chosen accessibility careers.
Sheri Byrne-Haber, CPACC

And because we care so much, we end up sinking a lot of our energies into this work. Mental as well as physical energy.
Nic Steenhout

From combating misconceptions and willful ignorance, to painfully slow progress and performative allyship with little action – there’s a lot to be stressed about.

But we have to keep trying

One strong common thread in an industry full of “it depends” grey areas is our dedication to equal access, it’s a primary motivator keeping us going.

Perhaps the most difficult thing is internalizing all of this. Digital accessibility work is not easy, but it is vital.
Eric W. Bailey

In the end, we must guarantee an accessible web that everyone can use and adjust to their needs. This is the basic promise of the web, a promise that is broken every day.
Eric Eggert

Practical Tips

As a web dev consultant, I’ve had the opportunity to be part of quite a few different kinds of teams and have worked on just as many different tech stacks. With that breadth of experience, I’ve also had the opportunity to try several ideas to push accessibility forward.

Here’s the top three that have worked for me, both in terms of delivering a more accessible end product and in sparking more interest and support from those around me.

Be the squeaky wheel

Sometimes you just know that accessibility is not a shared priority. Likely you’ve already had “the talk” with the team/stakeholders/client and, while they sounded receptive and interested, there hasn’t been much follow through.

In these situations, the best advice I have is to be the relentless “squeaky wheel“. For example:

Ask about user stories, acceptance criteria, and testing instructions that can help ensure an equal experience is considered throughout their lifecycle.
Ask about user testing, especially for complex and/or novel interactions.
Ask accessibility related questions when talking through a new design.
Bring up issues while in development, and in code reviews.
Get a commitment to addressing tech debt on a regular cadence, and push for accessibility to be part of that.
Make sure testing is happening on assistive devices too.

Some specific questions I recall asking recently:

“What should focus states of interactive controls look like?”
“How should this custom widget work for keyboard only navigation?”
“Can we get annotations for the preferred tab order?”
“How can we guarantee a minimum contrast for this text on a background image?”
“The video player doesn’t have play/pause controls, can we add?”

The main goal here is to center accessibility in as many discussions as possible. Get others thinking about it and asking questions too. Show the practical benefits, explain how minor course corrections early on can save a lot of time later.

Celebrate attempts as well as wins

There are few topics in our industry with more grey area and “it depends” answers, so it’s natural for folks still new to accessibility to be hesitant or misinformed.

In fact, I’ve put in several years of reading, learning, and applying accessibility best practices and eventually built up enough experience and confidence to even go get CPACC certified. And yet, I still struggle with imposter syndrome.

There are so many “moving parts” to accessibility that it’s hard to define specific technical requirements.
Nic Steenhout

The key is to identify an enthusiasm to learn and improve in those around you, and encourage that in any way you can. For example:

Give kudos when you notice all color combinations in the design system are accessible, then show how to annotate appropriate active, focus, and hover states for interactive controls.
Celebrate their effort put into adding ARIA roles to a new interactive widget, even if they’re all wrong. Then coach them through how to fix it, and explaining the first rule of ARIA.
Give appreciation to the QA folks that try a screen reader for the first time, and explain the difference between tabbing through operable controls and using a screen reader to navigate all content.

The main goal here is to encourage more growth and learning, and to build up enough psychological safety for folks to feel comfortable asking questions and trying. Be their mentor and provide the guardrails, help them work through it on their own and in real situations.

When all else fails, do it anyway

This may be the most controversial, but I can’t deny it’s effectiveness when applied at the right time. When you come across situations where you know the chosen direction is going to be inaccessible, and you have the means (and the spoons) to make it accessible anyway, just do it anyway.

Examples from a developer’s perspective:

In the video player missing pause controls scenario noted above, go ahead and add them in during development. Force someone to say “yes I acknowledge this is bad for accessibility and still want you to remove it” and see how often that happens. In our remote first world, this usually means you also have it in writing.
If you see a non-decorative image without alt text – and no path to get it “officially” provided – do your best and add it yourself.
Links that should be buttons, buttons that should be links, interactive controls using span and div tags. If you’re touching that code anyway, fix them.
No design direction on focus and hover states and no connection to the design team? Yeah I hate that too, but add them anyway and try to follow the designs as best as you can. If someone hates it, you’ll hear about it and will get a chance to make it even better.

The main goal here is to do our best to release products that are just a bit more accessible then they otherwise would have been. It may not move the needle very much for accessibility as a whole, but will help the people using your digital product have a better time.

There’s a reason this one is last, because it’s generally not a great idea to be subversive, and depending on your situation could even land you in a bit of trouble. So please do take some caution.

From my experience, there have been countless situations where I’ve made the decision to do it anyway and no one noticed, because they’re not looking for it. There are also many situations where my work was quite noticeable (like the pause controls on a video) and someone asked about it. More than half the time they’ll say something like “huh, okay then” and move on, sometimes those people slowly turn into accessibility advocates too.

Every bit helps

I leave it up to you to determine which may be appropriate for your situation. Remember that the overall intent is to drive progress despite an initial lack of support, while you continue to try building that support.

Sometimes, these tips help spread the word and builds momentum. Sometimes they don’t. Either way, every bit helps when it comes to accessibility.

Nuxt 2 to Astro 3 Replatforming – from Setup to Production

2023-12-03T18:33:17.000Z

I keep hearing great things about Astro, and just so happened to have a personal project that I needed to move off of Nuxt 2 as its end of life date is rapidly approaching.

Here’s my journey from never using Astro to pushing the refactored codebase live. Luckily, there’s a handy Nuxt to Astro migration guide that I’ll be using to get started.

Initial Setup

Install

Thanks Astro installer for the reminder that I’m on an embarrassingly old version of Node. Got the new shiny Node LTS version 20.9.0 installed and ready to roll.

Little attention to detail things like this really goes a long way!

First impressions matter, and the Astro installer was really great. The step by step questions to get the project set up using npm create astro@latest was a great touch. I didn’t bother with adding TypeScript support for this, sorry TS fam but this project ain’t it.

Opened the demo index.astro file and realized I didn’t have any code formatting. Quick search and – of course – there’s a whole page for IDE setup. I installed the Astro VS Code Extension and I was up and running. Also ended up adding the Astro-specific Prettier plugin too.

Initial Struggles

Web Components

As this was the first bigger topic I tackled (and struggled with), I ended up blogging about this particular topic separately over at Web Components in Astro.

Check that out for a deeper dive of my initial struggles wrapping my mind around astro components and how they can play nice with native web components.

Avoiding TypeScript

Little did I know that the “I didn’t bother with adding TypeScript support for this” comment above would come back to haunt me. Turns out, there’s no way to truly opt out of TypeScript and if you’re using Astro VS Code Extension you’re also locked into TS linting that surfaces TS errors too.

I did a whole lot of increasingly desperate searches, trolled through the Astro Language Tools Github issues, and even joined the official Discord to finally come to this conclusion. I was particularly bummed to find out that the previous V1 version for the Astro VS Code plugin had an option for this, and it had to be removed (I think) due to the language server swap to Volar.

For sake of completeness, here’s some of what I tried unsuccessfully to disable TypeScript linting in VS Code for this Astro project:

Set "typescript.validate.enable": false, in my VS Code workspace settings & restarted
In the tsconfig.json file
- Set "exclude": ["src"]
- Set { "compilerOptions": { "skipLibCheck": true } }
In a newly created tslint.json file
- Set "linterOptions": { "exclude": [ "src" ] }

I’m unsure why the standard advice of adding rules to workspace settings, tsconfig, and tslint didn’t work, but I have a feeling it’s due to the linting coming from another extension.

The Only Thing That Worked Disabling TS Errors

Because this is a relatively small project and I was thoroughly defeated with all the above research and attempts, I finally gave up. Here’s what I’m using to be able to move forward without errors:

Adding // @ts-nocheck at the top of files that I wanted to ensure the whole file ignored TS errors.
In smaller use cases, I’m using // @ts-ignore for individual statements to ignore.

I’m not sure why file-based ignoring works where project and IDE workspace settings didn’t, so if you have any explanation I’d love to hear about it. Will update this post if I do get some clarification.

Layouts & Styles

I figured, while I’m tearing everything apart I might as well overhaul the styles a bit to take advantage of fluid type and space, design tokens, and to simplify the overall setup.

Without considering that refactoring, this was the most straightforward part of the process. I copy/pasted all the style folders into a new src/assets/css folder and imported the app.css file in my primary layout and it just worked. I opted not to use the src/styles convention because it wasn’t required and I typically use an assets directory in other projects so that felt more comfortable.

Migrating Content

Static Content

Static content goes from /static to the /public folder, simple enough! This basically consisted of the code examples (which are saved as independent minimal HTML, CSS, and JavaScript files) and images including the favicon.

Page Content

For actual site pages, I didn’t have a whole lot more than plain HTML in my page components so moving them consisted of:

copying the .vue files over and renaming them to .astro
removing the <template> container and replacing with <Layout>
Moving the page title from the Vue component to the Layout container.
Changing links from <nuxt-link> to plain <a> links.

For example, here’s some pseudocode that encompasses all my pages structured in Nuxt .vue components, using the Accessibility Statement as an example.

<template>
  <article>
    <h1>Accessibility Statement</h1>
    <p>Page Content.</p>
  </article>
</template>

<script>
export default {
  data() {
    return { title: 'Accessibility Statement' };
  },
  head() {
    return { title: this.title };
  },
};
</script>

This page moved to Astro then looked like this.

---
import Layout from '../layouts/Layout.astro';
---

<Layout title="Accessibility Statement">
  <article class="page-container">
    <h1>Accessibility Statement</h1>
    <p>Page Content.</p>
  </article>
</Layout>

For any Nuxt links in the content, I did a find and replace and that worked out just fine. Nuxt links like <nuxt-link to="/solutions/focus/">Focus</nuxt-link> changed to <a href="/solutions/focus/">Focus</a> instead.

Dynamic Routes

I would say this ended up being the vast majority of my work in migrating over, dynamic routes is how static content is compiled into pages based on the content inside /content and the route templates in /pages.

I referred back to the Convert NuxtJS Syntax to Astro reference quite a bit for these routes.

Lack of Content Subfolder Support

The biggest difference between Nuxt and Astro is that it appears Astro doesn’t allow for nested content collections (source), so I needed to pull subfolders up to the root content folder all together under “solutions”. Not my favorite, but I’m going with it so I don’t have to figure out a customized workaround to do it.

Another interesting tidbit is that content slugs have to all be unique, even if they’re in different content subfolders.

Migrating Components

Vue Components

At first, I had grand ambitions of not pulling Vue into this project and going vanilla JS for everything. But for the sake of time to get everything ported over and online as soon as possible, I opted to keep some Vue components.

To add Vue support on an existing Astro installation, you can use the Astro Add command. So in my case I did npx astro add vue and it loaded everything up including the necessary configuration updates.

Luckily, I didn’t have to change much in my Vue components. Even though I was also upgrading from Vue 2 to Vue 3 as part of this process. Woohoo!

For me, it mostly consisted of swapping from v-bind.sync to v-model. If you’re jumping from Vue 2 to Vue 3 as part of this too, I recommend reading through the migration guide for additional breaking changes.

Vue + Web Components

I had a bit of trouble getting Vue to play nice with my native web components, and realized I’ve not had to address this before. Vue will try to find a registered Vue component for any custom tags it encounters, throwing a “failed to resolve component” error for any that don’t match.

After some research I found out that there’s a really elegant solution to this with a configuration update, setting isCustomElement to be anything with a dash (or in my case ending with a -l) in the compilerOptions is all it takes.

To Astro-ify the above solution, these same settings can be added to the Vue portion of the Astro config at astro.config.mjs. Mine ended up looking like the following:

import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

// https://astro.build/config
export default defineConfig({
  integrations: [
    vue({
      template: {
        compilerOptions: {
          // treat all tags with a -l as custom elements
          isCustomElement: (tag) => tag.includes('-l'),
        },
      },
    }),
  ],
});

Finishing Touches

Great, I’ve got all my pages loading again! Now for a few remaining items that I had before and wanted to maintain in this new codebase.

Site Search

Nuxt 2 had a full text search option built in, that was what I used for the site search functionality before. I’m unsure if there is something comparable for Nuxt 3 without relying on an third party provider like Algolia.

I really didn’t want to have to give up the full site search functionality, and I didn’t see anything built in to help pull this off. I did a bit of searching and found a couple options, ended up sticking with Pagefind through CloudCannon. I really liked this walkthrough by Reuben Tier for getting it set up specifically in Astro.

That worked really great, and it’s part of the build process so it can’t get much more set-it-and-forget-it than that.

Sitemap Generator

Now that the site itself is looking pretty good, I set my sights to cleaning it up for a production launch. The first thing I look at when doing that is making sure I have an accurate sitemap.

Astro sites don’t come with a sitemap by default, but there is a really easy integration for adding it here. Essentially, you just need to run through that installer and then add the root site URL to the config. When it was done, mine ended up looking like this

export default defineConfig({
  site: 'https://a11y-solutions.stevenwoodson.com',
  integrations: [vue({
    template: {
      compilerOptions: {
        // treat all tags with a -l as custom elements
        isCustomElement: tag => tag.includes('-l')
      }
    }
  }), sitemap()]
});

View Transitions

There’s a neat built-in feature of Nuxt that lets you do cross-fade page transitions. I thought, since Astro would be static generated, I would lose that little nice to have. Turns out I was wrong! Astro View Transitions to the rescue, I imported and added the <ViewTransitions /> to my primary layout and it worked.

Only thing I noticed, was that the main navigation would briefly lose its style every time I clicked on a new page. It looks like that may be because it’s a Vue component loaded in an astro island? Utilizing the transition:persist property to persist its state worked in this case, thankfully. I had experimented with moving the CSS of that component to the global styles which also helped, but I much prefer the portability of keeping styles with the component so I’m sticking with the persist property instead.

Final Thoughts

This was a great exercise for me to learn about and explore Astro, and besides the few snags I hit early on it was as smooth of a process as I could have hoped. Here’s some general notes now that I’m done.

Ideal Projects for Astro

I now feel like I have a better understanding of what kind of projects will benefit most from this framework. I think the sweet spot would be sites that are mostly static, but have some mild to moderate interactivity that could benefit from a more robust library.

For example, as noted above in the Vue Components section, there were cases where I tried to do the JavaScript heavy lifting within an Astro component with the ultimate goal being to remove Vue altogether.

But, all that vanilla JS added up quickly. Shifting back to Vue for only the component pieces that made sense shrunk the code in those components to less than half.

Performance

This is a relatively small site, and I was able to get most of it statically generated both in Nuxt and Astro, so I didn’t notice a whole lot of performance change between the two versions.

Looks like Lighthouse agreed with that sentiment, both received a 99 of 100. That 1 is likely due to some cumulative layout shift that I really should dig into.

I do, however, feel like I had a much better control and understanding of components that could potentially affect performance and more control over how their handled because of the concept of Astro Islands.

Time to Complete Replatform

While this blog post is rather long, I do feel like I’ve glossed over the more time intensive parts which may give a the wrong impression regarding how long this actually took me. So I’m going to try to describe the replatforming efforts that took the most time, and then estimate how long it all took me to complete.

Replatforming Accessibility Solutions included the following:

Learning Astro
Nuxt 2 to Astro 3 conversion
Deep dive into Web Components within Astro
Vue 2 to Vue 3 conversion
SCSS to vanilla CSS
Styles overhauled to use custom properties and fluid typography & spacing
Native search to Pagefind

With all the above, I’d estimate this took me around 80 hours to complete. Inclusive of reading documentation, coding, troubleshooting, testing, and releasing.

Why Budgets are so Important for Software Development Projects

2023-11-25T13:20:33.000Z

As a freelance web dev consultant, I’ve been having a whole lot of introductory conversations. They generally fit in one of a few categories:

potential clients looking for a developer for an upcoming project
fellow consultants looking for a dev to join them on a project
someone for either of the previous two groups that don’t yet have something specific in mind, but want to find potential consultants for work they’re trying to get started soon.

One big question I always ask all of them is “What’s your budget?”. As you might expect, this is also one of the hardest questions to get answered.

In this post I’m going to share why I believe it’s a critical question that should be considered carefully. Starting with a real estate analogy.

A Real Estate Analogy? Really?

I have a way with analogies to help convey details about software development. Usually they’re half-baked comparisons shared with folks as a shortcut to get them to understand some eccentricity, difficulty, or complexity in the topic we’re discussing.

The critical requirement of such analogies is that they’re based on a shared understanding, which we rely on to bridge that gap.

In one such conversation, I got the idea to compare a software development budget to a real estate budget and it worked surprisingly well. So well, in fact, that I’ve started using it all the time and led to writing this post.

You Have to Start Somewhere

This is the crux of why this analogy works, budgets may not be the most fun thing to talk about but they certainly are the most practical way to set expectations and find a good starting point.

It’s just as true with a software project as it is with buying a house. Knowing the budget is one vital step to finding a solution that is within reach and provides maximum value.

Setting Expectations, Saving Time

What’s one of the first questions you’ll get from a realtor? Yep, budget and probably location.

Why? Because they’re not going to take you to an open house for a $2MM home when you’re looking to spend a fraction of that. They’re not going to suggest a home that’s 200 miles (320km) away from your ideal location.

Would you love that $2MM house? Probably.

Do you want to be responsible for the maintenance and monthly bills? Probably not.

Taking the Analogy Further

Here are some other examples I gave when sharing this analogy, depending on the situation.

Additional Constraints – I had briefly mentioned in the analogy that desired location is another early question that sets some helpful constraints.
The same would be true for required technologies or an existing codebase that needs to be retained.
Prebuilt vs Custom – You may have the budget and desire for a custom built home, giving you full control over every detail. It’ll take longer, but you have more opportunity to get exactly what you want.
I would say this is even more true with software development, the potential return on investment is higher when you have something built specifically for your unique needs.

Wrapping Up

I hope this analogy helps highlight the importance of discussing budget – and any other constraints – from the start. It’s important to understand and work within these constraints as early as possible

So when you’re ready to start that new web application project and are asked about budget, rather than concluding their motivations are “how much can we make on this deal”, consider instead that they’re trying to determine “how can we achieve the most value that’s within budget”.

Web Components in Astro

2023-11-06T19:11:20.000Z

I’ve recently been jumping into learning more about Astro, using a personal project that needs to be replatformed as an excuse to give it a try. The first thing I wanted to dive into and learn more about was how components are handled, and especially how well it plays with browser native Web Components.

I burned a lot of time here just trying to understand how a web component could be copied into an Astro project. So instead of waiting to blog about the whole process, I wanted to share my learnings about components separately first.

First Attempt – AstroHeart

My first attempt was to get the AstroHeart example in the Web components with custom elements section of the Scripts and Event Handling documentation to work.

I got it working when the whole code block was placed in a layout or a page, but not when it was a referenced component from the /components/ directory. I think we can all agree that adding web components to a page or layout would be categorized as a “Bad Idea”.

After much fiddling I came to the conclusion that an Astro component that then instantiates a native web component is the best I could manage. It feels weird, but it works.

Here’s the full minimal example of AstroHeart working as a web component wrapped with an Astro component on Stackblitz.

Second Web Component Attempt – Sidebar

Now that I know it’s possible, I wanted to ramp things up with an actually usable — and slightly more complicated — example. The first web component I needed to port over for my project happened to be the excellent Sidebar from the Every Layout project.

A couple new issues emerged in this process of adding it, here’s how I got passed them both.

Passing Props

Welp, the Every Layout Sidebar has five separate attributes that can be added to the <sidebar-l> custom element and I quickly realized I need to manage that prop handshake between Astro and the native web component.

First, I went with the most obvious solution of gathering all props and manually passing them in, something like the following:

---
const { side, sideWidth, contentMin, space, noStretch } = Astro.props;
---

<sidebar-l
  side={side}
  sideWidth={sideWidth}
  contentMin={contentMin}
  space={space}
  noStretch={noStretch}
>
  <slot />
</sidebar-l>

But that so verbose and error prone, there’s gotta be a better way right? Turns out, there is! Replace that code above with this and you’re all set.

<sidebar-l {...Astro.props}>
  <slot />
</sidebar-l>

Still a little weird but much better, right? Now if names change or more props are added I don’t have to keep going back to update this.

Scoped vs Global Styles

When styles are added to the Astro component using <style> tags, they’re automatically scoped. In some cases, as is the case for this Sidebar component with several modification options, this can be less desirable.

I found this out first hand when I was attempting to adjust the spacing between the sidebar and the main content area using <Sidebar space="var(--space-m)">. I came to realize that the default styles were of a higher specificity than the modified styles applied via that space attribute.

In cases like this, drop a is:global into the opening style tag like this, <style is:global> and it’ll be treated as a global style where the cascade for modifications will work.

I suppose you could also move the component styles to where the rest of your global styles are located, but you lose that encapsulation of everything being in one place.

Live example

I’ve worked up another Stackblitz for this Sidebar component example too.

Third Attempt – Auto-import Multiple Components

I still felt a bit odd with wrapping web components inside Astro components, even though I was able to overcome any blockers that emerged. I think it’s because having to manually Astro-ify every component I wanted to use feels like it goes against the portability of native web components.

So, I tried again.

With a bit more encouragement from Daniel Saunders, who reminded me that all it really takes is an import of the web component somewhere in the page, I set my sights on trying that.

As a quick proof of concept, I grabbed another of the free Every Layout components – the Stack – and built up a minimally viable page with the following. The references to web-components is because I wanted another separate directory under src to keep Astro components separate from web components.

<stack-l space="3rem">
  <h2>H2 headline</h2>
  <stack-l space="1.5rem">
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quasi aperiam,
      cupiditate qui totam incidunt ipsum dolores.
    </p>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quasi aperiam,
      cupiditate qui totam incidunt ipsum dolores.
    </p>
  </stack-l>
  <h2>H2 headline</h2>
  
</stack-l>
<script>
  import '../web-components/Stack/Stack.js';
  import '../web-components/Stack/Stack.css';
</script>

Sure enough, that worked just fine!

Automating imports

But, adding a script tag with imports of the (potentially double digit) JS and CSS web component files I’d need to use on every page doesn’t sound like fun to me. Instead, I set my sights on auto-importing based on a glob pattern.

Enter Astro.glob() as that sounds like just what I need. I realized that what I was doing wasn’t going to work though, because I was attempting the import in the front matter which meant this was trying to import on the server side where HTMLElement isn’t defined.

Remembering that it needs to be in a script tag within the content of the page rather than in the front matter got me away from that error, but it still didn’t work.

I read up on what Astro.glob() is doing, it’s a wrapper for Vite’s Glob Import (import.meta.glob). That’s set up by default to lazy load which meant that it wasn’t going to end up on the page because I wasn’t using it on the server side. From the docs:

Matched files are by default lazy-loaded via dynamic import and will be split into separate chunks during build. If you’d rather import all the modules directly (e.g. relying on side-effects in these modules to be applied first), you can pass { eager: true } as the second argument

Once I did just that, I got it working!

Auto-importing at the Layout Level

One more change now that I had something functional, instead of doing this import on the page I moved it to the bottom of my global layout file.

Now, I have access to all web components on all pages that use this layout. Here’s the final code for importing everything, placed in my layout:

<script>
  const webComponentsCSS = await import.meta.glob(
    '../web-components/**/*.css',
    { eager: true }
  );
  const webComponentsJS = await import.meta.glob(
    '../web-components/**/*.js',
    { eager: true }
  );
</script>

I added a second web component to my setup to make sure it was importing both, and sure enough it did! Rather than pasting all that code here, scroll down to the Live example link below to see it all isolated in another Stackblitz.

Performance Implications

Because I’m still learning about all this, and the project I have in mind to use it is very small, I’ve not delved too deep into the implications of importing all web components in this way. I did run a production build to see how everything came together, it appears that all components are compiled into one hoisted.js file.

There’s likely some consideration needed for very large applications, because I’d bet the compiled source wouldn’t be ideal for projects of any real complexity. The first thing I’d try is bundling web components into sub directories and using this glob import pattern in smaller chunks.

Live example

Once again, I made this a minimally reproducible Stackblitz of two native web components being used on a page after being auto imported in the parent layout.

Conclusion

That’s where I’m at as of November 2023, I’m pretty happy with the auto-importing method noted in that third attempt above. But I am still very interested in hearing about other ways to do this, and especially about how it affects page performance. If you’ve got other methods to make this work, I’d love to see some examples!

I’ve already updated this post with the third example after some more fiddling, if I figure out or hear of any further updates I’ll be sure to keep this post updated.

I’ve also completed the replatforming of Accessibility Solutions from Nuxt to Astro, which was the impetus behind this deep dive into web components in Astro. If you’re interested in reading more about that experience, check out Nuxt 2 to Astro 3 Replatforming – from Setup to Production.

Fighting Back Against Toxic Productivity

2023-10-31T16:23:08.000Z

I received some great feedback from a recent social media post (on LinkedIn and Mastodon) about my sometimes unhealthy obsession with my todo list, I’m glad it resonated with so many people!

It’s been a topic on my mind all year, though the nature of my fixation has shifted over the past 6 months – especially as I transitioned from a full time job into freelance – the underlying basics remain the same.

After diving into the subject a little deeper I came to find out about the term Toxic Productivity which sums it up pretty well. There are other related terms like “action bias” and “hustle culture“, but the former makes it sound more positive and the latter seems more about external pressure.

What is Toxic Productivity?

I want to focus more on strategies to combat toxic productivity in this post, but felt a quick definition would be useful to start with.

Toxic productivity is the desire to be productive at all times and at all costs, pushing yourself to unhealthy extremes in order to accomplish more.

I’ve pulled together some articles that helped me learn more if you’re interested in diving deeper too:

Strategies to Fight Back

Following are the most impactful things I’ve tried, so much so that I’ve utilized them all multiple times.

Recalibrate the importance of “the List”

This was the focus of the social post I mentioned and led to this blog post. Read the full post on LinkedIn or Mastodon for more.

TL;DR

I like being organized with a list of tasks, and marking something off my list is a really effective motivator for me. But I tend to lose sight of the big picture if left to my own devices for too long.

Just because it wasn’t “on the list” doesn’t mean it’s not still something important to do.
Just because it is “on the list” doesn’t mean you’re going to be ready and able to do it when you planned.

I regularly remind myself that “the list” doesn’t define me or my worth.

Define your Core Values

By core values, I’m referring to the rarely changing long term principles and beliefs that guide our choices. How we want to be perceived and remembered by others.

I went through the exercise of defining them in my Mission Statement that I completed nearly 5 years ago, I still refer back to it periodically for a boost of motivation and to realign my goals.

Knowing your core values helps clarify what’s important now, what is essential, and what can wait.

Set Realistic Goals

It’s a great exercise to think big and set long term goals that stretch you personally or professionally, but those should continue to be broken down into short term goals, and then into tasks that are each individually achievable.

These tasks should have realistic deadlines too, estimating is a difficult and imprecise practice. Give it your best guess, see how it goes, and recalibrate. For example, I _constantly_ underestimate how long content marketing and outreach efforts take so I’ve continued to adjust my expectations.

To quote Amy Hupe from her presentation It all means nothing in the end, “fuck moonshots”.

Set Boundaries

I wrote a bit about this in How I Hacked My Brain to Let Myself Relax in the Evenings, and happy to say I’m still holding firm on some of the key points there:

I get to bed and wake up at the same time every day, even weekends. That regular cadence helps with sleep quality more than I thought possible.
I still have general time boxed sections of the day that I hold myself to no matter what. No more work after dinner unless there’s a very good reason for it.

Setting boundaries to get the sleep I need, reframing time away from work so I don’t feel guilty about it, and having a predictable schedule all lead to more productivity in less time.

Embrace Low Energy Days

As I get older, I’ve noticed that some days I really can’t force myself to power through like I used to. Maybe I should say “not willing to” rather than “can’t” there, older Steve recognizes when something isn’t the fire drill that younger Steve may have thought.

Rather than fighting myself, over-caffeinating, and generally wasting time trying, I’ve instead opted to take another path when this happens.

I ask myself “What can I do today to make tomorrow better?”

Focusing on tomorrow’s productivity helps me to reframe and not think so critically about my lack of it today. Some days it means getting up and doing a bit of meal prep, going for a walk, taking a nap, cleaning up my todo list and low-level prepping.

All of these things can make tomorrows productivity that little bit easier.

The Common Thread

It may come as no surprise that the common thread through all the strategies mentioned above is self awareness. Forcing myself to think about my actions, acknowledge habits I should stop (or start), and embrace my limitations all require some level of self awareness.

If you’re feeling the pressures of toxic productivity, give some of these strategies a try. It’s likely that not all of them will work for you, but maybe the act of trying will give you some ideas for your own situation.

Any time and attention put towards figuring out core values, clarifying what feels out of alignment, and steps taken to improve is time well spent.

State of the Browser 2023 Conference Recap

2023-10-18T02:34:43.000Z

Preamble

I’ve been working on this recap in bits and pieces since the State of the Browser conference in September. Now that it’s already mid-October I’m happy to finally be able to share my lightly edited notes from each of the speaker sessions.

I also added a “More Background” section at the end that gets into more detail about how a guy from the Midwest ended up sponsoring and attending a conference in London.

SotB Sessions

Michael R. Lorek – “Web Standards: Does Anyone Actually Care?”

Validate your code, test for accessibility, pen test it – it all contributes towards the resilience of the code you release. Educate yourself and your peers on web standards, it’s important!

Recording and Transcript of “Web Standards: Does Anyone Actually Care?”

My Session Notes

Highlights of the evolution of the web, from introduction in 1991 to 1.13 billion (200 million active) websites on the internet today
Recap of UX layers of a Web Page from 2006
Definition of Web Standards from the W3C, standards are important. But now in 2023, do folks still care about web standards?
- Zero of the global top 100 used sites in 2022 contained valid HTML, two in 2021
- Three had valid CSS in 2021, 13 of 94 were valid CSS in 2022
The web is broken, why? What’s the cause
- WYSIWYG tools, building sites without any code
- WordPress, themes are rarely validated
- Third Party Snippets, often risks of questionable code quality
- Design systems are mostly on JS frameworks
- Enterprise tech like No code, SaaS
- AI? Not ready but will it ever fix all that flawed code?
- Inadequate teaching of semantics and standards
Why do we need to validate, what are the benefits?
- SEO – better crawlability, semantics are going to help
- Accessibility – Improper formatting can lead to barriers, lack of semantics or misuse causes confusion
- Security – Missing doctypes, unescaped characters, improper attribute quoting. All can lead to inconsistent rendering, opens up vulnerabilities, and manipulating attributes for XSS attacks
Details matter
- HTML charset needs to be prioritized in the first 1024 characters
- Be aware of inconsistencies and semantic details, acronyms vs abbreviations for example
- UTC, Cities and Time Zones – adding <time> to the code to detail the time zone
- Multiple languages mixed on one page
Code quality is imperative
- Ensure code is clean and readable, understand its backend and frontend performance, accessibility, sustainability
- It all adds up!

Chris Ferdinandi – “Speedy Dev Insights”

Recordings and Transcript of “Speedy Dev Insights”

My Session Notes

My First Web Component
- Creating a custom element requires at least one dash (single word elements are reserved)
- customElements.define()
- constructor function runs when a new instance is created
- additional functions can be created to manage callbacks and other actions like the connectedCallback example
- Quick intro of a counter button, placed in the page 3 times to illustrate the same component being used multiple times and maintaining its own state
Two-way data binding with 15 lines of JavaScript
- Demo is two identical forms that we want to match values across them
- JS native API called Proxy watches for changes and lets you take action in response
- input event listener can trigger when changes are made to inputs, that in turn can trigger the change that Proxy is watches for which updates the other input
13 web dev tricks
- Event Delegation – To catch events on multiple elements, attach an event listener to a parent and filter to only the ones you care about
- Early Return pattern – nested if statements are hard to read, can return return; when the opposite is true instead
- Multiple Selectors – You can pass a comma separated string to querySelector and querySelectorAll
- Data Attribute selectors – cleaner code, but also can make event delegation easier by using the handler name to run the equivalent function
- Object => Query String Conversion – Use the URLSearchParams method and run the toString() method on it
- Dedupe an Array – Utilize a Set which can’t have duplicate values, Array.from(new Set(wizards));
- Random ID generator – crypto.randomUUID();
- True Type checking – typeof is unreliable because it returns an object for several different types. Instead call the Object.prototype.ToString method on the item instead. Returns object followed by the actual object type like [object Array]
- Numeric separators – In modern JS you can use underscores to break big numbers into smaller parts, commas will cause issues
- Looping over objects – Rather than for/in, instead use a simple for/of loop and Object.entries
- Object Property shorthands – Variable names as the property and name will auto-assign
- Simpler Boolean returns – Returning the conditional check if it’s returning a boolean itself
- GIF is pronounced ‘jif’ – (personal note, this is also backed up by the creator of the format)

Amy Hupe – “It all means nothing in the end”

We need to know where we’re heading to, and we need to derive meaning from the journey and the destination. And the good news is that we get to decide that. It all means nothing in the end, but only if you let it.

Recording and Transcript of “It all means nothing in the end”

My Session Notes

Had historically derived meaning from her work, very career driven
Sudden loss of motivation early this year, leading to an existential crisis.
Time away to travel and recharge, came back still feeling uninspired
Turned to journaling and deep introspection, realized a loss of purpose in her work
Emphasized the importance of connecting one’s work to a core perspective
- the intersection of skills, experiences, and values.
- It’s unique to you.
Setting meaningful goals is crucial and that goals should:
- align with my core perspective
- be something I care about
- be achievable (fuck moonshots!)
- be measurable (know if I’m making progress)
Achieving goals and tracking progress are important for avoiding burnout. Signs of burnout:
- Emotional exhaustion – the fatigue that comes from caring too much, for too long
- Depersonalization – depletion of empathy, caring, and compassion
- Decreased sense of accomplishment – sense of futility, feeling that nothing you do makes a difference
Disconnect from external validation, we’ll always need some but it should not be the sole source of self-worth. Examples:
- pay raises
- promotions
- performance reviews
Cultivating meaning involves focusing on fulfilling my purpose, making progress against my goals, and enjoying the journey.
While the ultimate outcome might be uncertain, the journey and how one gets there can bring meaning to one’s work and life.

Ian Lloyd – “Accessibility Is Easy… Except for When It Isn’t”

Leverage native HTML for built in accessibility affordances, use ARIA and tried & tested patterns for common use cases, get creative with complex UIs but be sure to test thoroughly.

Recording and Transcript of “Accessibility Is Easy… Except for When It Isn’t”

My Session Notes

Acronyms referred in the talk

WCAG – Web Content Accessibility Guidelines
SC – Success Criterion
ARIA – Accessible Rich Internet Applications
a11y – Accessibility
AT – Assistive Technology (e.g. screen readers)

Accessibility low hanging fruit

<button>, if you need to roll your own you’ll need to make sure they’re keyboard operable, with a button role, styled, and state maintenance

Hall of Shame

the linkput – an input element of type button wrapped with a link
the lutton – a link with a role of button
disclosure/checkbox/button/link/heading combo – div
First rule of ARIA – don’t use ARIA if a native HTML element or attribute exists with the semantics and behavior you need.

Tricky examples

Table row selection, shows the detail of selected rows in the right panel
Multi-select menu – choosing between <select>, checkboxes, checkboxes in a disclosure
Theater seat chooser – be sure to convey detail, if seat button is dimmed explain why, make navigation easier with keyboard (arrow keys), group sections of the seats together for quicker traversing

Recap

Native HTML is preferred
Use ARIA and tried & tested patterns where possible
For complex UIs, start with as much native HTML and tested patterns first and then get creative. Test with as much Assistive Technology and as many users as you can

Kilian Valkhov – “Stop using JS for that: Moving features to CSS and HTML”

Just because you know something needs a specific browser hack, that may not be true anymore. You can make better websites if you check those assumptions every now and then.

Recording and Transcript of “Stop using JS for that: Moving features to CSS and HTML”

My Session Notes

The rule of least power suggests choosing the least powerful language for a given purpose in web development. Helps to maintain accessibility and performance.
- HTML is preferred over CSS
- CSS is preferred over JavaScript
Old techniques will still work, but just because it used to require JavaScript doesn’t mean that’s still the case.
- Several web features and interactions that traditionally required JavaScript can now be achieved with HTML and CSS.
- It’s important to question assumptions and try new web development techniques.
Examples
- custom toggles – can be achieved with CSS using pseudo elements :before and :checked
- datalists – HTML <datalist> auto suggest using the <option> items inside
- color pickers – <input type="color"> and it can pick colors from anywhere on the screen (even outside the browser)
- smooth scrolling – scroll-behavior: smooth; CSS property on html
- scroll margins – CSS property that only applies while scrolling scroll-margin-top
- scroll target – :target property will let you style the scroll target
- fixed (sticky) elements – CSS position: sticky will lock elements to the top as you scroll
- scroll snapping – useful for carousels or sliders, scroll-snap-type on the parent and scroll-snap-align on the child items
- accordions – <details> and <summary> can do essentially the same thing, can also use :marker to have a different marker for when the details element is open or closed.
- modals – <dialog> gets us most of the way there, still needs a bit of JavaScript
- container queries! Not in the presentation, wanted to make note of them

Diego Gonzalez – “THE BLUE PWANET”

The evolution of Progressive Web Apps (PWAs), their core technologies, deep integration with the operating system, Project Fugu for enhancing web capabilities, and the potential future of the Web Install API

Recording and Transcript of “THE BLUE PWANET”

My Session Notes

Progressive Web Apps (PWAs) – Yes they’re still a thing, yes they still exist, and are stronger than ever.
Evolution of web applications
- starting with Ajax and the ability to change web page elements without reloading the entire page.
- Link to homescreen, just a link with no other functionality
- PWAs
PWAs have three fundamentals
- HTTPS
- Manifest file
- Service Worker
Project Fugu, a joint effort between various companies to bring powerful APIs to the web platform
- Importance of deep integration into the operating system, more advanced applications and no longer a “lite” version
- new features for web apps such as access to clipboard, window controls, file handling, shortcuts, and web share targets.
Every PWA is a web app, but not every web app is a PWA
Coming up short on getting developers on board with building PWAs, using Service Workers and Manifest files, and understanding the benefits
- Calls into question if install-ability criteria should change, Chrome already dropped the service worker requirement
Web Install API, a new idea
- allow websites to install other websites or web applications without proprietary workarounds
- enable scenarios of online web stores
- install same ad cross-domain apps
- Challenges – Preserve privacy of users, avoid install prompt spam
Expansion of PWAs
- widget – companion apps using adaptive card templates
- sidebars – introduces new display override values, can be detected in CSS & JS too
- these initiatives are Edge-specific, seeking interest from other browsers
mentions the evolution of apps and the appearance of new app types packaged in web bundles

Harry Roberts – “Cache Rules Everything”

We only have two jobs; we only need two tags – cache-control and etag. Consider how fresh a file needs to be and set these headers accordingly, and don’t revalidate hashed files.

Recording and Transcript of “Cache Rules Everything”

My Session Notes

The best request is the one that’s never made
Key Concepts
- Cache – how long can I reuse this file without checking for updates?
- Revalidation – How do I check that a file has changed after my cache time limit is up?
- Cache stops the client from speaking to the server so revaldation shouldn’t happen while cached
- Fresh – file is in the cache within it’s expiration date
- Stale – file is in the cache but has passed it’s expiration date
- Fresh does not mean up to date
- Request – Client requests a response from the server
- Response – Server responds to the request, with a status code like 200 (success) or 304 (renewal of cache)
Headers we don’t need
- pragma – pragma: no-cache, not meant to be a response header, just delete immediately
- expires – expires: wed, 13 sep 2023 08:49:31 gmt, not terrible but expires at an absolute time and fails if a user has changed their system time. Cache-control is better
- last-modified – last-modified: wed, 13 sep 2023 08:49:31 gmt, a revalidation header that’s not harmful but etag is better
Headers we do want
- cache-control – cache-control: private, max-age=300, must-revalidate, a caching header, rules and conditions for caching a response
  - max-age – how long, in seconds
  - no-store – don’t store this file
  - no-cache – forbids the browser from going straight to the cache, will check with the server first before releasing a cached file to the browser
  - public – max-age assumes public, exposes cacheability on a CDN
  - private – intended for personal use, don’t reuse or store in CDN
  - must-revalidate – caches are permitted to serve stale content (e.g. when offline) unless explicitly told otherwise with this directive
  - stale-while-revalidate – revalidation is synchronous, this makes it async while revalidation is pending
  - s-maxage – shared max age for CDNs, separate from browsers. Can flush CDN cache on build, so you can afford to make these higher
  - immutable – contract with the browser that “this file will never changed”
- etag – weak etags only hashes the file name, strong etags hash the contents of the file and are preferred. This is a revalidation header, slightly more reliable than last-modified
Can we cache this file?
- yes – cache-control: max-age=3600
- no – cache-control: no-store
Does this need to always be up-to-date?
- yes – cache-control: no-cache
- no – cache-control: max-age=3600
Can this response be shared?
- yes – cache-control: public, max-age=3600
- no – cache-control: private
Can we reuse this response even if it’s stale?
- yes – cache-control: max-age=3600
- no – cache-control: max-age=3600, must-revalidate
Can we tolerate a slightly out of date response while performing revalidation?
- yes – cache-control: max-age=3600, stale-while-revalidate=600
- no – cache-control: max-age=3600
Do we need to configure CDNs and browsers differently?
- yes – cache-control: max-age=3600, s-maxage=86400
- no – cache-control: max-age=3600
Is the file hashed?
- yes – cache-control: max-age=2147483648, immutable
- no – cache-control: max-age=3600
Prefer etag, so we don’t fall into the trap of last modified forcing revalidating – especially with static site generators
Don’t revalidate hashed files, because those are always going to change with a new build.
We only have two jobs; we only need two tags – cache-control and etag

Ana Rodrigues – “Exploring the Potential of the Web Speech API in Karaoke”

Working example of a karaoke app using vanilla HTML, CSS, and JavaScript using the Web Speech API. You can learn by building “useless” things. Side projects don’t need to be monetized in order to be valid.

Recording and Transcript of “Exploring the Potential of the Web Speech API in Karaoke”

My Session Notes

Exploring the potential of the Web Speech API to gamify karaoke, inspired by her love for the Rasmus and the desire to sing their songs (other than “in the shadows”)
Using HTML, CSS, and vanilla JavaScript – avoiding libraries – to demonstrate browser native capabilities
Web Speech API – split into two, speech recognition and speech synthesis
Web Speech API isn’t perfect and has certain quirks
- not supporting continuous dictation, so there’s JS that forces it to start itself back over again when it stops
- needing HTTPS to send data
- doesn’t work offline
- not supported in Firefox
Demo of the karaoke interface, where the speech recognition begins with the song and transcribes her singing, trying to match the lyrics with the input and highlighting correctly matched portions in green and unmatched in red
Some matching challenges when singing vs speaking, with demos of both ways
Concludes by encouraging side projects and creative exploration as valid learning experiences in web development.
You can learn by building “useless” things. Side projects don’t need to be monetized in order to be valid. They don’t need to become NPM packages or open source projects.

Heydon Pickering – “What are Accessibility Overlays?”

The conference was ended with a world premiere of “What are Accessibility Overlays?” by Heydon, a masterpiece that blends useful information and humor in a way only Heydon can. Check it out here.

Other Recaps

Here are a few links from others regarding SotB2023, I’ll try to keep this updated as I find more. Send me a link if you know of one I’m missing!

What we learned at State of the Browser 2023 by Alistair Shepherd
It all means nothing in the end by Chris Ferdinandi

More Background

I’ve shared bits of this on social and in conversations, figured it’d be worthwhile to also share here to complete the picture of how a random guy from the Midwest in the States would find himself sponsoring and attending an event in London.

How it Started

For me, it all started back in April as initial details about State of the Browser 2023 were being released.

Even though the conference had been going since 2011, I hadn’t personally been aware of SotB until late in 2022 as recordings from that year’s conference were making the rounds. I greatly enjoyed those recordings and really liked the focus on web standards, accessibility, performance, and sustainability.

When I heard about the call for sponsors in April for the 2023 conference, I had a feeling there’d be a significant overlap between folks interested in attending and those with potential interest in Be Inclusive. So I decided to go ahead and sponsor not realizing at the time that sponsorship came with an in person ticket to attend as well.

The Snowball

My wife and I had never been outside of North America before, and hadbeen talking about visiting England first. We even looked up some flights and rates but we found it to be too expensive (this was around mid 2022 at the height of the “revenge travel” boom) so we opted to wait it out.

This snowball of a sponsored in person ticket renewed our interest, and in May of 2023 we started researching again. To our surprise, flights and rates had improved enough to make this a viable option. So we got to planning, where should we stay? How long?

That snowball grew until we had booked a vacation spanning nearly two weeks and four destinations. The SotB Conference would be the first full day and once that was done, it’s vacation time!

Final Prep

Now that I had quite a bit riding on this one decision, and I was about to take an 8 hour flight to be there in person, my next thought was “oh no, how do I force myself to get social and talk to people?”

I ended up deciding to rely on an ice breaker in the form of individually customized business cards. They were something visual, and afforded me a way to walk up to someone and say “Hey I’m Steve, want a one of a kind business card?”

Happy to say I was able to give away half of the 50 unique cards I had printed! If you’d like to read more about the process of making them, check out my One of a Kind Business Cards blog.

Aftermath

It was a lot of time and effort to prepare, but this conference and the vacation that followed it were truly highlights of the year for me. I had a blast learning from these wonderful speakers, the conversations during breaks and at the after party, and the ideas that re-watching and cleaning up my notes have sparked.

Every time I come back to these speaker sessions I find myself digging into details, finding tangents, reading more, and experimenting. Huge kudos to every single one of the speakers, I’m sure I’m not the only one they’ve inspired to give more thought and experimentation towards the topics they covered.

Onward and upward! 🚀

One of a Kind Business Cards

2023-09-10T12:46:36.000Z

It’s been a while since I made some business cards, but I really wanted something to leave with folks I meet at conferences and meetups that would be both memorable and personal.

A tall order for some business cards, but I think I did alright. Here’s how it came together.

The Idea

I wanted every card to have a personal touch, and a unique touchpoint for every person that received one. I know cards are a bit dated so my primary focus was to get them to _want to_ find me online.

So I thought, what about a unique QR code for each card? That’d be great start for a unique experience online, but different QR codes are not visually distinctive.

Okay, what about in addition to those QR codes there’s a unique plaid swatch on each card too? Now we’re talking! Plaid is kind of my thing, and making a custom plaid color palette for each person would be really memorable.

To pull that off, I knew I could take advantage of what Moo refers to as Printfinity, basically they let you upload a unique back to every single card you order.

Digital Implementation

SVGs

I already have a plaid swatch generator (read more about how I made the plaid swatch generator here) so I jumped right into creating 50 unique color palettes. This was likely the most time consuming part, but the end result was so worth it!

Swatches of all 50 unique plaid color palettes

I used the SVG Export Chrome extension to grab a copy of all the unique SVGs for later use.

QR Codes

I just googled “QR Code Generator” and found this one called QRExplore that was able to generate them all in one go. I was dreading having to make these individually manually so this was a welcome shortcut!

Personalized Contact Pages

I then got to work building out the pages that the QR codes point towards. Each QR code has a unique code at the end that lets me know which particular card – and thus which plaid swatch – the person received.

So the page itself features that same plaid fairly prominently, just after a big vCard download button (because that’s the #1 reason they’re here in the first place). I’m hoping the vCard is a helpful touch, so folks could add me to their contacts as easily as possible.

Example of the plaid from card #1 at the top of the contact page in the QR code

Since I went through all the trouble of making these unique plaid swatches, I saved them all as exportable SVGs so the recipient can download and use them too. I’m surrounded by exceptionally creative people all the time, hoping something fun comes out of this!

Because I plan on keeping card #1, I’ll share the URL to it here so you can see the final result for yourself, Card 1 of 50 Contact Page.

Print Implementation

While I’m not a designer by trade, I do occasionally enjoy exploring creative layouts and personal projects like this are the perfect time for that. I used Affinity Designer to pull my assets in and get to work.

After a whole lot of fiddling (which I didn’t screenshot unfortunately) I settled on a fairly unconventional portrait orientation for both the front and back of the cards.

The front of every card, and the back of card #1 once the designs were finalized

I made the sections that don’t change into symbols first, just in case I spotted a typo or wanted to change something, at least I wouldn’t need to do it 50 times later on.

Then, I copied the back artboard 9 times horizontally, selected all 10 and copied them again vertically 5 times to end up with 50. The next time sink was then replacing the plaid backgrounds on every card back, and adding the unique QR codes to each of them.

The glorious end result of all 50 card backs

Because I’m a web developer with a deeply engrained sense of “measure twice and cut once” I also then manually tested each and every QR code before sending this off to print.

The Printed Cards

I went with Moo mainly because of the Printfinity, without which this whole idea wouldn’t have been possible. But, I also knew they had a 100% recyclable print option and that was one of my only requirements for printing. I’m trying to be mindful of my environmental impact and wanted to make sure these cards matched that intent.

It wasn’t until around this point that I realized I took some chances on several of the color combinations I used and wasn’t quite sure if they’d translate on card stock. I live and breathe RGB, I’ve seen that mindset lead to some muddy results when translating to CMYK, and yet I still didn’t think about it til the end. Oh well, I thought, let’s just go for it and see.

The Grand Reveal

The day my cards arrived felt like my birthday, I could not wait to see how they turned out in print.

After testing a handful of the QR codes (again) and satisfied I actually pulled this off. I let it sink in that it’s a real thing now.

The glorious result of all that effort, so pleased with how it turned out!

I’m happy with how they all turned out, some are more muted and others a whole lot more vibrant in print but that just adds to the variety I think.

With my order, I also purchased a neat ShowCase to hold a bunch of them (pictured above). It’s the perfect way to let folks pick the swatch they like the most.

So, now if we meet in person be sure to ask for your very own one of a kind business card!

Going Independent – Two Months In

2023-08-30T13:47:53.000Z

I mentioned in the last post that I was considering only taking this through week 8. I’ve confirmed that desire, opting instead to focus on content that’s more relevant to potential clients, other freelancers, and web devs.

Hope you enjoyed these glimpses into my day to day of building this up. Here’s week 1, week 2, and week 3 as well if you’re interested in some earlier posts about this evolution.

Let’s dive in one last time!

What’s Happened the Past Few Weeks

Cutting back on social network posting to LinkedIn and Mastodon. I had been posting some content on LinkedIn, Twitter (X?), BlueSky, Mastodon, and Facebook for a bit. After looking through the stats and feedback, I decided to narrow focus to these two to save time. I may incorporate others again later depending on the topic, but want to see how it goes with two.
I realize follower & view stats can often be a vanity metric, but I’m happy to note that I’ve seen slow but steady increases in website traffic, LinkedIn followers & views, and Mastodon followers and interactions. Any one of them can spark a connection so I don’t take it for granted!
I released that 11ty style guide generator and shared how to add it to an existing site after doing so for this site. Still a work in progress, but feel free to check it out!
Just before integrating that style guide generator, I overhauled the styling of this site to use more modern CSS best practices like custom properties, fluid grid and typography powered by clamp, and generally making better use of the space with a touch more color.
I just received some business cards that I took more time than I care to admit designing, they have a unique IRL -> online connection that I’m pretty proud of. I’ll be blogging about that process too so stay tuned for more on that (likely next week).
I’m getting started on a web dev project for a former colleague that reconnected, more to come on that as soon as I can!
I stopped counting the number of touchpoints I’ve had, from meetings, email conversations, and social connections I know I’m easily in the triple digits of new contacts since the last update. Surprisingly, it does get a little easier each time. The harder part is tracking progress and making sure I don’t miss reconnecting. I have a pretty nice homegrown CRM (as I hinted at last time) that is working for me for now. Trying to be frugal and so many of the CRM offerings out there are pretty expensive for my needs at the moment.

What’s Coming Up

Focusing on this active project I had mentioned above, going to knock it out of the park! I’m working with a really great guy who is also a freelance consultant, we’re just getting started but it’s already been nice working with someone who “gets it”.
Getting really excited about the State of the Browser conference coming up in a few weeks! My accessibility auditing SaaS app Be Inclusive is a sponsor of that wonderful event, and with the sponsorship I get an in-person ticket to attend. So I’m packing up and traveling internationally to meet some new people and share some of my fancy new business cards!
I have a few additional project leads that are in various stages of the pipeline, all so different and exciting. Looking forward to seeing where those go.
Upcoming updates to Be Inclusive including the addition of WCAG 2.2 criteria.
I have a handful of additional side projects and blog post ideas I’m going to continue to chip away at, now would be a good time to follow the RSS feed so you don’t miss any of it!

As I had mentioned in the intro, this’ll be the last “Going Freelance” update post here but I do intend to still share bits of my progress on social media. So be sure to connect with me on Mastodon and LinkedIn!

Thanks again for reading, onward and upward! 🚀

Eleventy Style Guide Generator – Step by Step guide adding to an existing site

2023-08-25T13:43:42.000Z

I shared the Eleventy Style Guide Generator (source is on GitHub, here’s the demo site it generates, and an intro video from the September Eleventy meetup) a few weeks ago. Because it’s a full Eleventy repo and not a plugin (can’t be until Virtual Templates are supported), I received a few questions about its requirements including:

Are design tokens required?
Is the use of WebC required?
Can I use a CSS preprocessor like SCSS?
How do I add this to an existing Eleventy site?

This post attempts to answer these questions, I’ll also be updating the repo with more of these details as well.

Are design tokens required?

No, you don’t need design tokens to use this generator.

If you decide not to use design tokens you can also remove some of the additional dependencies and files including:

the Tailwind dependency & configuration file at `tailwind.config.js. All it’s doing is converting the JSON sourced design tokens into usable CSS custom properties.
the two CSS utilities at src/_utilities/css-utils. Similarly, they’re only being used by the Tailwind configuration to generate the custom properties.
the tokens static design system page at src/design-system/Atoms/tokens.njk. It’s only there to itemize the individual design tokens.

Is the use of WebC required?

Not technically, but it’s highly encouraged.

WebC brings first-class components to Eleventy, this being a way to itemize components in a style guide it stands to reason that the two are well suited as a pair.

If you choose not to use WebC, or need to ease into supporting it in your existing project, here’s a few considerations.

Naming Collisions

The generator is assuming that each component under src/_includes/components has a .webc component and an .njk example defined. If your components are also going to be in Nunjucks you’ll need another qualifier added to example files so you can programmatically tell them apart.

Something like .stories.njk (like Storybook) would work fine. Then you’d update src/design-system/components-pages.njk to include that extra qualifier, for example like this

{%- macro c(path, name, params) -%}
  {% include "components/" + path + "/" + name + ".stories.njk" ignore missing %}
{%- endmacro -%}

Layouts

There are also two WebC layouts that are being used to generate the style guide files at src/_includes/layouts/ds-static.webc and src/_includes/layouts/ds-wrapper.webc.

You could enable WebC just for new pages and templates like these, but it should be fairly straightforward to convert into another template language if you don’t want to enable WebC at all.

Existing components

There are a handful of components defined in the repo and they’re all WebC based components, so you won’t (easily) be able to make use of them.

You could convert them to another template language but that effort may not be worthwhile depending on your needs.

Can I use a CSS preprocessor like SCSS?

Sure, you can still use a preprocessor like LESS, SCSS, or Stylus if that fits better in your workflow.

I had decided on using only CSS to reduce the number of dependencies required, that’s all.

How do I add this to an existing Eleventy site?

I jotting down what I’ve needed to do to add this to my own site, and listed it all here.

This including everything that I had noted above as optional, so I’ve split it up into sections so you can skip the bits you don’t want.

File path references directly relate to the paths in the 11ty-design-system repo starting with src

Essentials Setup

First, you need to determine where you want the style guide to live, in the repo I’ve set this as /design-system but you can place it anywhere that makes sense for your project.

Copy the following pages to this new folder

src/design-system/components-pages.njk – generates the style guide page for each component, with tabs for Demo, HTML, and Context. Loads the demo as an iframe of…
src/design-system/components-full-pages.njk – this is the isolated component in a blank page. Iframed into the component page above.
- This is relying on a “base” layout too, if yours is in a different location you’ll need to update layout: layouts/base.webc as well.
src/design-system/index.md – The style guide homepage, feel free to replace the content here (and even change the template language).
src/design-system/Atoms – This folder contains files that itemize the design system tokens and most major native HTML elements

Copy the following to your layouts directory

src/_includes/layouts/ds-wrapper.webc – The layout of the design system pages, including the sidebar menu.
- This is relying on a “base” layout too, if yours is in a different location you’ll need to update layout: layouts/base.webc as well.
src/_includes/layouts/ds-static.webc – The layout for any static content pages you add in addition to the auto-generated ones.

Copy the following into your `.eleventy.js` config

/* Shortcodes */
config.addPairedShortcode('brace', function (content, type = 'curly') {
  const [opening, closing] = {
    curly: ['{{', '}}'],
    silent: ['{%-', '-%}']
  }[type];
  return `${opening}${content}${closing}`;
});

config.addPairedShortcode('prettify', (content) => {
  return prettify(content);
});

/* Filters */
config.addFilter('console', function (value) {
  return JSON.stringify(value, null, 2);
});

/* Custom Collections */
// Filter source file names using a glob
config.addCollection('dsAtoms', function (collectionApi) {
  return collectionApi.getFilteredByGlob('**/design-system/Atoms/**/*');
});

Descriptions in the same order as the code above:

Brace & Prettify shortcodes, for help displaying content in the Code and Context tab panels
console filter for stringifying the JSON configuration in the Context tab
dsAtoms custom collection so we can also add the static pages under the Atoms directory to the style guide menu

Copy the foundational CSS & JS

src/assets/css/design-system.css – helps with setting up design system specific styles like color swatches. Everything is prefixed with ds- to avoid CSS collisions.
src/assets/js/vendor/seven-minute-tabs.js – Powers the Demo, HTML, and Context tab structure for the component style guide pages

Copy the following data files

src/_data/components.js – generates all the components as a collection, be sure to update the folder paths here too if they’re different in your setup.
src/_data/global.js – defines the random function used in some templates to cache bust the CSS.
- If you have a cache busting filter in place you can skip this one and update references to global.random() with that instead.

With these steps I had a functional style guide being generated. You can see my progress at https://stevenwoodson.com/design-system/.

Screenshot of the Design Tokens design system page after following the steps in this section to get it added to my site.

Adding Design Tokens

Here’s what you need to copy to get design tokens set up:

tailwind.config.js – This is what powers the generation of all the CSS custom properties
postcss.config.js – PostCSS triggers the tailwind configuration, it also minifies the CSS
Build step for the above in your package.json, "css": "npx postcss src/assets/css/*.css --base src --dir dist", for example
src/_data/designTokens – This is where all the design token JSON files are stored, they’re in the data directory to make it easier to parse that data with Eleventy’s automated data cascade
src/_utilities/css-utils – Utility classes that the tailwind config needs in order to generate the custom properties and the clamp values that many of them need

The act of utilizing the design tokens is likely another post entirely, but the TL;DR of it is that you’re going to need to comb through your CSS and replace color, spacing, and other tokenized values with those coming from this generator.

Adding WebC Support & Components

Adding WebC support

You’re going to need Eleventy 2.0.0 or newer to be able to utilize WebC. I was on an older 1.x version and was surprised at how easy the upgrade process was. Hoping you have similar luck if you need to upgrade as well.
Follow the install steps from the official WebC docs, currently it’s not bundled with core so you’ll need to perform an NPM install and add the plugin to your config.

WebC Component Structure

All components are to be stored under src/_includes/components. One component per folder is the ideal and you can nest folders down to three levels currently.

Here’s the structure of a typical component folder, using the Sidebar component as an example:

sidebar-l.webc WebC component file – This is where the component itself is defined, in this case the WebC component is a wrapper for a pre-defined true web component so it only loads the CSS and JS.
sidebar.config.js Configuration file – Defines the component name and any additional context needed to demonstrate what the component can do.
Sidebar.css Web Component – it’s not required to store component styles here rather than with the rest of the site styles but can be a nice way to keep everything together in one place.
Sidebar.js Web Component JavaScript – This is where the Web Component is initialized using standard HTMLElement and customElements syntax.
sidebar.njk style guide example – The Nunjucks template file is where we demonstrate the component with example content.

Check out the Card component for an example of a simpler HTML-only component. This one contains a .webc component, a config, and a Nunjucks template for rendering the examples.

Send me your feedback!

Did you add this Eleventy Style Guide Generator to your site? I’d love to hear about it! If you’re willing to share your process adding it as well, that could inform future updates and documentation to make it easier for the next person. So please do reach out!

Pulling WordPress Post Categories & Tags Into Eleventy

2023-08-11T19:21:02.000Z

TL;DR

This is another part in a series of posts about WordPress content being pulled into Eleventy, including:

Composable Architecture Powered by WordPress (where it all started)
Pulling WordPress Content into Eleventy
Adding a Table of Contents to dynamic content in 11ty

This post is specifically expanding on the progress from the Pulling WordPress Content into Eleventy post to add categories and tags to my blog posts. I’m also going to add per category-filtered pages, and a per tags-filtered pages for good measure.

Here’s what it’s going to look like when it’s all done, or you can click around my blog to see it for yourself.

Category Link List

Posts filtered by Category

Categories and Tags listed at the top of a post

Why?

As I’ve been focusing more on blogging lately, I’ve amassed enough posts that I started realizing that it’s getting progressively harder to find a blog post the older it gets.

Really the only way to do so currently is to go to the main blog page and scroll or run a page search. Not ideal. I could add a site search but I’ve been dragging my heels on that too, so I’m opting for something a little easier for now.

Time to utilize the built in functionality of Categories and Tags from WordPress!

Adding Categories and Tags to Posts

First things first, we need to make sure to add some categories and tags to blog posts. I hadn’t up until now because I wasn’t using them, so I spent some time coming up with a list of categories and tags I’d like to use and then using “Quick Edit” to apply them to posts quickly. Check out this Categories and tags article for more details.

Once we have that data set up in WordPress, we need to make sure we’re gathering it in Eleventy when performing a build. We need to have a list of categories and tags attributed to the post in order to link to them in the blog post template.

These are collectively what WordPress refers to as terms. The details (slug, title, etc.) of terms are not surfaced in the default REST API response, instead we’re only going to see references to their IDs in the main data object like this:

"categories": [7],
"tags": [34],

We’ll also see RESTful links inside _links (which would return these details separately) like the following:

"wp:term": [
  {
    "taxonomy": "category",
    "embeddable": true,
    "href": "https://mysite.com/wp-json/wp/v2/categories?post=1"
  },
  {
    "taxonomy": "post_tag",
    "embeddable": true,
    "href": "https://mysite.com/wp-json/wp/v2/tags?post=1"
  }
],

Getting terms in the REST API response

Instead of performing multiple queries to get the category and tag data, we can add them to the embed section of the same query we’re already using.

As noted in the previous post about pulling content from WordPress, I’m splitting out the posts method getAllPosts from the post details method requestPosts.

To add the terms details, we add &_embed=wp:term to the API request in requestPosts. So in our previous code _embed: "wp:featuredmedia", turns into _embed: "wp:featuredmedia,wp:term",.

Next, we need to make sense of that data and add it to the blogpost data object we’re using to generate the blog pages.

Organizing the term data

WordPress doesn’t discern between a “category” and a “tag” in the embedded JSON, all terms are stored together with an associated taxonomy. Categories are in the category taxonomy, and tags are in the post_tag taxonomy.

For the same example as above where there’s one category whose ID is 7 and one tag with an ID of 34, here’s a slightly trimmed version of what that raw data ends up looking like:

"wp:term": [
  [
    {
      "id": 7,
      "link": "https://mysite.com/category/webdev/",
      "name": "Web Dev",
      "slug": "webdev",
      "taxonomy": "category",
      
    }
  ],
  [
    {
      "id": 34,
      "link": "https://mysite.com/tag/eleventy/",
      "name": "eleventy",
      "slug": "eleventy",
      "taxonomy": "post_tag",
    }
  ]
]

So, we’re going to need to separate categories and tags ourselves to be able to use them in those separate contexts. Here’s how I’m doing it.

Before

metaDescription: metaDescription,
slug: post.slug,
title: post.title.rendered,

After

metaDescription: metaDescription,
slug: post.slug,
title: post.title.rendered,
terms: post._embedded["wp:term"] ? post._embedded["wp:term"] : null,
categories: post.categories,
tags: post.tags,
categoriesDetail:
  post._embedded["wp:term"]?.length > 0
    ? post._embedded["wp:term"].filter(
        (term) => term[0]?.taxonomy == "category"
      )[0]
    : null,
tagsDetail:
  post._embedded["wp:term"]?.length > 0
    ? post._embedded["wp:term"].filter(
        (term) => term[0]?.taxonomy == "post_tag"
      )[0]
    : null,

It’s a little gnarly looking, but we don’t want our code to break if there aren’t any categories or tags defined so the checks are all squished in there too. If tags are found, I’m then filtering out categories and tags separately in the returned post data.

You’ll notice I’m also passing along the array of categories and tags IDs in categories and tags too, this is for more easily filtering blog posts by these terms in the individual category and tag pages.

Blog Post Updates

Now that I have post categories and tags, time to add them to the blog post pages!

New Pages

These additions are all looking great, but if you’re following along you may notice that the links I’ve added to the blog post template are all going to 404 pages. Of course, that’s because they don’t exist yet so let’s get on that.

Gathering Categories and Tags Data

I’ve not figured out a way to compile all the categories and tags into their own collections by using the data we’ve already gathered in blog posts. Instead, I had to run separate REST API calls for them. If you know of a better way to do this please do let me know!

In setting up these two new REST API calls, I noticed quite a bit of duplication between them, so I opted to do some cleanup and isolate the API calls and data manipulation needed for them all. I called it /utils/wp-json.js. Here’s the code for that:

const { AssetCache } = require("@11ty/eleventy-fetch");
const axios = require("axios");
const jsdom = require("jsdom");

// Config
const ITEMS_PER_REQUEST = 10;

/**
 * WordPress API call by page
 *
 * @param {Int} page - Page number to fetch, defaults to 1
 * @return {Object} - Total, Pages, and full API data
 */
async function requestPage(apiBase, page = 1) {
  try {
    // https://developer.wordpress.org/rest-api/using-the-rest-api/pagination/
    const url = apiBase;
    const params = {
      params: {
        page: page,
        per_page: ITEMS_PER_REQUEST,
        _embed: "wp:featuredmedia,wp:term",
        order: "desc",
      },
    };
    const response = await axios.get(url, params);

    return {
      total: parseInt(response.headers["x-wp-total"], 10),
      pages: parseInt(response.headers["x-wp-totalpages"], 10),
      data: response.data,
    };
  } catch (err) {
    console.error("API not responding, no data returned", err);
    return {
      total: 0,
      pages: 0,
      data: [],
    };
  }
}

/**
 * Get all data from a WordPress API endpoint
 * Use cached values if available, pull from API if not.
 *
 * @return {Array} - array of data objects
 */
async function getAllContent(API_BASE, ASSET_CACHENAME) {
  const cache = new AssetCache(ASSET_CACHENAME);
  let requests = [];
  let apiData = [];

  if (cache.isCacheValid("2h")) {
    console.log("Using cached " + ASSET_CACHENAME);
    return cache.getCachedValue();
  }

  // make first request and marge results with array
  const request = await requestPage(API_BASE);
  console.log(
    "Using API " +
      ASSET_CACHENAME +
      ", retrieving " +
      request.pages +
      " pages, " +
      request.total +
      " total records."
  );
  apiData.push(...request.data);

  if (request.pages > 1) {
    // create additional requests
    for (let page = 2; page <= request.pages; page++) {
      const request = requestPage(API_BASE, page);
      requests.push(request);
    }

    // resolve all additional requests in parallel
    const allResponses = await Promise.all(requests);
    allResponses.map((response) => {
      apiData.push(...response.data);
    });
  }

  // return data
  await cache.save(apiData, "json");
  return apiData;
}

/**
 * Clean up and convert the API response for our needs
 */
async function processContent(content) {
  return Promise.all(
    content.map(async (post) => {
      // remove HTML-Tags from the excerpt for meta description
      let metaDescription = post.excerpt.rendered.replace(/(<([^>]+)>)/gi, "");
      metaDescription = metaDescription.replace("\n", "");

      // Code highlighting with Eleventy Syntax Highlighting
      // https://www.11ty.dev/docs/plugins/syntaxhighlight/
      const formattedContent = highlightCode(prepared.content);

      // Return only the data that is needed for the actual output
      return await {
        content: post.content.rendered,
        formattedContent: formattedContent,
        custom_fields: post.custom_fields ? post.custom_fields : null,
        date: post.date,
        dateRFC3339: new Date(post.date).toISOString(),
        modifiedDate: post.modified,
        modifiedDateRFC3339: new Date(post.modified).toISOString(),
        excerpt: post.excerpt.rendered,
        formattedDate: new Date(post.date).toLocaleDateString("en-US", {
          year: "numeric",
          month: "long",
          day: "numeric",
        }),
        formattedModifiedDate: new Date(post.modified).toLocaleDateString(
          "en-US",
          {
            year: "numeric",
            month: "long",
            day: "numeric",
          }
        ),
        heroImageFull:
          post._embedded["wp:featuredmedia"] &&
          post._embedded["wp:featuredmedia"].length > 0
            ? post._embedded["wp:featuredmedia"][0].media_details.sizes.full
                .source_url
            : null,
        heroImageThumb:
          post._embedded["wp:featuredmedia"] &&
          post._embedded["wp:featuredmedia"].length > 0
            ? post._embedded["wp:featuredmedia"][0].media_details.sizes
                .medium_large
              ? post._embedded["wp:featuredmedia"][0].media_details.sizes
                  .medium_large.source_url
              : post._embedded["wp:featuredmedia"][0].media_details.sizes.full
                  .source_url
            : null,
        metaDescription: metaDescription,
        slug: post.slug,
        title: post.title.rendered,
        terms: post._embedded["wp:term"] ? post._embedded["wp:term"] : null,
        categories: post.categories,
        tags: post.tags,
        categoriesDetail:
          post._embedded["wp:term"]?.length > 0
            ? post._embedded["wp:term"].filter(
                (term) => term[0]?.taxonomy == "category"
              )[0]
            : null,
        tagsDetail:
          post._embedded["wp:term"]?.length > 0
            ? post._embedded["wp:term"].filter(
                (term) => term[0]?.taxonomy == "post_tag"
              )[0]
            : null,
      };
    })
  );
}

function sortNameAlpha(content) {
  return content.sort((a, b) => {
    if (a.name < b.name) return -1;
    else if (a.name > b.name) return 1;
    else return 0;
  });
}

module.exports = {
  requestPage: requestPage,
  getAllContent: getAllContent,
  processContent: processContent,
  sortNameAlpha: sortNameAlpha,
};

With this new set of utilities, the actual data JS files are super small. Here are the blogposts.js, blogcategories.js. and blogtags.js files.

blogposts.js

const { getAllContent, processContent } = require("../utils/wp-json");

const API_BASE =
  "https://mysite.com/wp-json/wp/v2/posts";
const ASSET_CACHENAME = "blogposts";

// export for 11ty
module.exports = async () => {
  const blogposts = await getAllContent(API_BASE, ASSET_CACHENAME);
  const processedPosts = await processContent(blogposts);
  return processedPosts;
};

blogcategories.js

const { getAllContent, sortNameAlpha } = require("../utils/wp-json");

const API_BASE =
  "https://mysite.com/wp-json/wp/v2/categories";
const ASSET_CACHENAME = "blogcategories";

// export for 11ty
module.exports = async () => {
  const blogcategories = await getAllContent(API_BASE, ASSET_CACHENAME);
  return sortNameAlpha(blogcategories);
};

blogtags.js

const { getAllContent, sortNameAlpha } = require("../utils/wp-json");

const API_BASE =
  "https://mysite.com/wp-json/wp/v2/tags";
const ASSET_CACHENAME = "blogtags";

// export for 11ty
module.exports = async () => {
  const blogtags = await getAllContent(API_BASE, ASSET_CACHENAME);
  return sortNameAlpha(blogtags);
};

Creating a Blog Post Term Filter

Great, we have data now! The next step is to set up a filter so we can show category and tag pages with just the posts that contain them. Because both are ID based, I opted to create one filter that’d work for either. Here’s the code

  // Get the elements of a collection that contains the provided ID for the provided taxonomy
  eleventyConfig.addFilter("blogTermFilter", (items, taxonomy, termID) => {
    return items.filter((post) => {
      return post[taxonomy].includes(termID);
    });
  });

Now I can pass the taxonomy (categories or tags) and its ID to get a filtered list of posts with that category or tag.

Creating the Category and Tag Pages

We’re getting really close now!

The final step is to create the tags and categories filtered pages. For me, they both have basically the same structure so I’m just going to share the categories one here.

---
layout: layouts/base.njk
pagination:
  data: blogcategories
  size: 1
  alias: blogcategory
permalink: blog/category/{{ blogcategory.slug }}/
---
{% set blogslist = blogposts | blogTermFilter("categories", blogcategory.id) %}

<section class="l-container h-feed hfeed">
  <header class="feature-list__header">
    <h1 class="p-name">Blog Posts categorized under "{{ blogcategory.name }}"</h1>
    <a href="{{ metadata.feed.path }}">RSS Feed</a>
  </header>
  <p>
    <a href="{{ '/blog/' | url }}" class="btn btn--secondary btn--small">back to all blog posts</a>
  </p>

  <div class="grid-3-wide feature-list">
    {% for post in blogslist %}
      <div class="card z-depth-1 h-entry hentry">
        <div class="img-16-9-aspect">
          {%- if  post.heroImageThumb %}
            <img src="{{  post.heroImageThumb }}" alt="" loading="lazy">
          {% else %}
            <img src="/assets/images/posts/post-hero-placeholder.png" alt="" loading="lazy">
          {% endif %}
        </div>

        <div class="card__content">
          <{{itemheader}} class="headline4 p-name entry-title">
            <a href="/blog/{{post.slug}}" class="u-url" rel="bookmark">
              {% if post.title %}{{ post.title | safe }}
              {% endif %}
            </a>
          </{{itemheader}}>
          <div class="l-post__meta">
            <p>
              <strong>
                <span aria-hidden="true" class="fe fe-calendar"></span>
                <time class="postlist-date" datetime="{{ post.date }}">{{ post.formattedDate }}</time>
              </strong>
            </p>
          </div>
          <div class="p-summary entry-summary">
            {%- if post.excerpt %}{{ post.excerpt | safe }}
            {% endif %}
          </div>
        </div>
      </div>
    {% endfor %}
  </div>
</section>

You can copy this file and replace the references to categories over to tags instead for the Tags version. For example {% set blogslist = blogposts | blogTermFilter("tags",blogtag.id) %}

Potential Further Enhancements

This ended up being a bit more to figure out than I anticipated going into it, and I’m pretty happy with where it is now.

I do, however, have some ideas for future further enhancements:

In addition to Previous and Next posts at the bottom of a blog post page, it’d be really great to have a “Related posts” section. That’s a fairly common feature of blogs and would help with discoverability.
Advanced filtering from within the main Blog page would be nice, rather than just separate pages per category and tag. This would open up further options like filtering by category and tag together.

I may make time for these soon, let me know if you’d be interested in reading more about that!

Eleventy Style Guide Generator with WebC Component Support

2023-08-03T17:27:17.000Z

TL;DR

I created an Eleventy style guide generator, features include:

Automatically itemized JSON-formatted design tokens like colors, fonts, and fluid scale and sizing.
Automatically itemized components and their variations based on a simple configuration file format
Eleventy WebC Component support and examples
Supports standalone documentation pages, perfect for displaying foundational HTML elements and explaining design system details in a more curated way.

Source is on GitHub, here’s the demo site it generates, and an intro video from the September Eleventy meetup.

For more detail about how to add it to your own Eleventy site, check out the Step by Step guide adding to an existing site follow up post.

Impetus

I recently had the opportunity to create a new fairly simple Eleventy site and found myself wanting to also document some of the visual language and components therein.

I didn’t want to go overboard and install something like Storybook for this because – while I love Storybook – it can be a lot and this site definitely didn’t need all that.

So, in true developer fashion, rather than manually create a few static style guide pages and move on, I decided to make a design system generator!

I love the simplicity and speed of 11ty, and I love the organization of a good self documenting design system, so I combined the excellent work of several really smart people to pull these two together in a way that acts as a pretty nice starting point for a fluid, responsive, and blazing fast 11ty powered website.

Read on if you’re interested in the pieces that make up the whole, including the inspiration behind them.

Design Tokens

What better place to start than the at the smallest building blocks of a design system, right?

Design tokens are vital to the overall look and feel and are (ideally) used everywhere to promote consistency with spacing, fonts, colors, etc.

All tokens are stored in the /src/_data/designTokens/ directory, I did this purposefully because having the JSON in the Eleventy Data folder gives me these values to manipulate and use for free. Making the visual itemizing noted below really simple.

Token Definition

Here’s the structure I used for the token files themselves, they all came with a title, description, and an array of items. I also optionally added a meta object to store additional info, for example the sizes and spacing ones link to the Utopia calculator where it was generated.

{
  "title": "Name for these Tokens",
  "description": "Longform description of what these tokens define.",
  "meta": {},
  "items": []
}

I used the excellent tools James and Trys created called Utopia for the sizes and spacing tokens. Here’s the breakdown:

The Type Calculator defines the sizes.json tokens
The Space Calculator defines the spacing.json tokens

I also added a colors.json and fonts.json token JSON file to itemize those for consistency as well.

I now have a solid foundation for fluid typography and spacing, and consistent fonts and colors, so the applications I build will look wonderful regardless of the available space and will be consistent from page to page with minimal effort.

Converting to CSS Variables

Now that I have my tokens beautifully organized, I also needed a way to convert them into usable CSS variables.

There are some great well established tools out there that do this, such as Theo and Style Dictionary but for this I turned to the sage advice of Andy Bell via buildexcellentwebsit.es and used Tailwind to run through the token JSON files and generate the CSS variables I can use in my styling.

I went this route because it seemed to fit how I like to organize things, already had concepts inherent to Utopia (including clamp), and was already working in an Eleventy site.

These are defined in the /_utilities/css-utils folder and used in the tailwind.config.js configuration.

Here’s a truncated example of what it generates:

:root {
    --color-bg: #fff;
    --color-bg-alt: #fffaeb;
    ...
    --space-2xs: clamp(0.5rem,0.46rem + 0.19vw,0.625rem);
    --space-xs: clamp(0.75rem,0.69rem + 0.29vw,0.9375rem);
    ...
    --space-xs-s: clamp(0.75rem,0.59rem + 0.78vw,1.25rem);
    --space-s-m: clamp(1rem,0.53rem + 2.33vw,2.5rem);
    ...
    --size-step-n2: clamp(0.6875rem,0.65rem + 0.19vw,0.8125rem);
    ...
    --font-base: Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif;
    --font-serif: Georgia,sans-serif;
    --font-code: Lucida Console,Monaco,monospace;
}

Visually Itemizing the Tokens

Being so vitally important to a successful product, I wanted a seamless and automated way to itemize these tokens for easy visual reference.

I’m still shocked at how easy this part ended up being once I decided to store the design tokens in the Eleventy data directory.

Because that data was automatically surfaced to page templates, all I needed to do here was to create an 11ty Nunjucks-based page that loops through the design token values and applies the tokens to some placeholder elements. You can see how this comes together at /src/design-system/Atoms/tokens.njk and a screenshot of it in action below.

Some overlapping screenshots of the tokens style guide page to illustrate how it itemizes the tokens visually

Style Guide Generator

With design tokens defined, accessible via CSS, and visually itemized in a page. I thought “wouldn’t it be great to have individual components automatically itemized in a similar way?”.

Foundation

After some searching for existing solutions I found this Eleventy Design System gem by Trys Mudford. It’s truly a wonderful foundation for exactly what I was hoping to achieve with this project.

While integrating that into what I was building, I noticed a few things that I wanted to expand upon to make it more versatile. Here’s the highlights of what I added:

Moved to a subfolder so it can be in the same codebase as the rest of the site
Ability to define components in subfolders of the _includes/components directory
WebC components support and examples

WebC Support

It just so happened that I was reading more about WebC while iterating on this idea. WebC is a new 11ty file extension that brings first-class components to Eleventy. An obvious addition to a style guide generator that itemizes components!

I will caution that WebC is still fairly new, there’s some things that work great with other file extensions that just don’t yet for WebC. I’ve itemized some of these as TODO items in the readme.

To see some WebC component examples, check out the Sidebar and Stack composition components courtesy of Every Layout, and the Card component utilizing some style inspiration from SmolCSS.

Other Conventions

Standalone Documentation Pages

Rather than having to create a “component” for foundational HTML elements and long form documentation within the style guide, I’ve built it so that you can define standard pages in the style guide as you would any other page.

It will automatically merge these static pages with the generated ones for components too!

For some examples of static pages, check out the src/design-system/Atoms folder. That’s where I’ve added block, form, inline, and preformatted HTML tags to quickly be able to preview how changes to the design tokens and styles affect these critical native tags.

Styling Methodology

I’ve quickly become a big fan of CubeCSS and have tried to adhere to those guidelines as best I can here. If you haven’t read about it yet I highly recommend you check that site out and give it a try.

Admittedly, in some cases it gets a little weird but I have my reasons! For example, I have web component styles sitting in the same folder as the web component itself (Sidebar for example) and I have others (Card for example) that have styles in the assets folder (card.css in this case) instead.

I did this because I wanted to adhere to the HTML-only Components rule where it renders native HTML and ignores the host component tag. Adding and referencing the styles in the component definition would have turned the Card example into a true web component instead.

Live Site Example

I’ve actually been sitting on this for a little while, before releasing something for general use I wanted to make sure to put it through a real site build process first. Happy to share the first such site has just been pushed live for the best (and most patient) client a guy could ask for – my dad!

His site at dannywoodson.org and the style guide for it is here.

Pretty neat to be able to compare the demo site with this live site and see the similarities, but also the differences!

Plans for the Future

I think there’s a lot of potential here, a couple of the bigger things I’d love to do with this are:

Continue to add foundational web components that can be reused across any kind of tech stack. Im considering adding some more baseline WebC components to this project as well, especially those found in Tugboat.
I’d ideally like this to be an Eleventy plugin that can be installed on an Eleventy site, rather than a full Eleventy site in itself. As far as I can tell there’s not a way to do so until Virtual Templates are made available.

Have any ideas? Are you going to give it a try?

I’d love to hear from you, reach out on the socials or start up an issue on GitHub.

Resources

Design Systems, Fluid Typography, Styling Methodologies oh my!

Fluid type, space, and grid calculations via Utopia
CSS methodology based on Cube CSS
Eleventy Design System by Trys Mudford & the companion explanatory blog post.
Some of the base components and styles are based on SmolCSS and Every Layout

Getting Started with WebC

Eleventy WebC Components main documentation
Crash Course in Eleventy’s new WebC Plugin video
Interactive Progressively-enhanced Web Components with WebC video
Introduction to WebC & Understanding WebC Features and Concepts from 11ty Rocks
11ty & WebC by W. Evan Sheehan

Going Independent – Week Four & Five Check in

2023-07-31T13:43:02.000Z

Wow, five weeks already? I missed one so this is a roundup of the last two weeks. Here’s week 1, week 2, and week 3 if you’re interested. Let’s dive in!

What Happened the Last Two Weeks

I agonized over a potential opportunity to take on a long term contract at a fairly large financial services platform, even pulled out the old pro/con list trick to help me decide. After days of mulling it over I decided not to apply. I knew that the benefits of regular income and some project stability were going to be overshadowed by my lack of time making my own consulting practice a reality and I’m still deeply committed to making this work.
Four virtual meetings, two were follow-ups from prior chats with other freelancers/entrepreneurs, one was with a branding and copywriter that helped me with some wonderful ideas, and the last was a potential lead with a really nice small web dev agency.
Several (sorry, I didn’t keep detailed track of how many) follow up emails with connections, potential leads, and ongoing opportunities.
Took a few weekdays off right in the middle of these two weeks for a family road trip (part of the reason this is a two week roundup). I’ll admit it was difficult at first as I was concerned about losing any momentum I’ve built up, but it really did me some good to unplug for a while and just be.
I teased last time about some progress on the 11ty style guide generator, I was able to get a first iteration of it complete enough to mark off my list. Before releasing, however, I wanted to use it on a real project of my own to work out any initial bugs so…
First semi-complete iteration for my dad’s website was pushed online using the style guide generator, sent it over for initial feedback. I did end up finding a few things that needed to be adjusted in that generator so I’m glad I did this first. Sorry that took so long dad!
I spent half a day working with a trusted friend, we shared some things that we’ve been working on and looking for ways to help each other. One big takeaway for me is to put more effort towards analyzing data from my outreach efforts, basically a sales retro.

What’s Coming Up This Week

I’m going to set up a homemade CRM to keep myself more organized. I’m not ready to purchase one yet so I’m going to use Google Sheets for now. The sales retro conversation last week made me realize that, while I have some pretty good notes and a little system for reminding myself to follow up with folks, I have missed some opportunities to follow up with people and don’t want to continue that trend.
Finishing touches on the 11ty style guide generator and share it in another post, if you’re interested stay tuned!
Finalize the website for my dad and hopefully launching it this week.
Collect all the actionable bits from my personal musings, ideas, and meeting notes. Then parse through it all and prioritize. I haven’t done this in a few weeks and am already noticing I’ve become less focused and more confused about what’s important now. When that happens, I tend to fixate on one or two things that catch my attention instead.

I have a feeling there’s going to be a lot more added to this list, especially after I’ve completed that last line item, so stay tuned for the update next week to see how far I get with all this.

Should I keep going?

I’m starting to think the weekly check ins have run its course and am considering stopping after week 8, two full months feels like as good a place as any.

If you have strong feelings about me keeping this going, any feedback, or good vibes, reach out and let me know.

Thanks again for reading, onward and upward! 🚀

Going Independent – Week Three Check in

2023-07-17T15:00:39.000Z

Keeping the weekly check in train rolling! Here’s week 1 and week 2 in case you’re looking to catch up.

What Happened Last Week

I got a response back about that big project proposal I mentioned last week, they’re still interested but we decided on a few foundational changes that necessitated updates to that proposal. Happy to report these updates didn’t end up taking a whole day like it did for the first iteration.
- Later in the week I heard back about that proposal, they had decided not to move forward. I decided to share this on social and realized how tough that actually is, to admit when things aren’t going as planned.
I sent 15 follow up emails and two follow up calls for leads and other networking and collaborator outreach. Couple meetings scheduled from these (noted below).
I’ve been picking back up on some cold-ish outreach for Be Inclusive too, still trying to build up a user base for that accessibility auditing tracking app. Feedback from users has been overwhelmingly positive, but getting users in there to try it out has been a struggle.
Dev time! I had been away from code for a while as I’ve been busy with outreach, content authoring, and other operations setup. I found that I needed that zone-in time with some code to boost my happy.
- I got into a great flow on Wednesday & Thursday and made a whole lot of progress towards the foundation of an 11ty style guide generator. More to come on this as soon as it’s ready!
- I purposefully started with that foundational project so I can use it for the first time on a website for my dad (who has been really patient with me in getting it rolling!).
- I’ve been using both of these goals as an opportunity to brush up on some trends that I’ve not been able to put enough time into yet, like fluid typography and web components. The plan is to level up on those new-to-me things and also to have a better starting point for base styling new projects.

What’s Coming Up This Week

So far, I have three meetings booked this week. Three more in the works but not scheduled.
- Two are follow up calls with potential collaborators, to catch up and chat some more. Both were a result of my earlier outreach efforts, and I’m so glad to have made these connections!
- The third is with a branding and copywriter for some help with my personal branding. Really excited for this one!
I have a really nice project lead from a prior co-worker in early discussions, would be really fun working with them so I’m keeping my fingers crossed!
Going to keep iterating on that 11ty style guide generator project and hopefully release it for others to try out soon.
I have a list of about a dozen more potential collaborator and networking contacts to reach out to, going to split them up and do a few a day.
I’m taking a couple days off at the end of this week, so I’m trying to keep this list limited so it’s more achievable. Looking forward to some time to unplug and come back refreshed next week!

Thanks again for reading, onward and upward! 🚀

I Want To Be Known For… – Freelance Introspection

2023-07-14T19:24:17.000Z

This is a follow up post from The Ideal Client and Project – Freelance Introspection, continuing my introspective journey as I iterate on my various online presences that I’d roughly call my “personal brand”.

Taking a Step Back

In writing that previous post I realized that before I can think deeply about an “ideal” client or project I needed to work on who I want to be as a freelance web developer some more first.

Some new questions emerged:

How can I quantify an ideal project without first determining what I’d professionally like to focus on?
How do I quantify an ideal client? Then, how do I make myself discoverable to them?
Conversely, how can I position myself as an ideal candidate for them?

Compiling Feedback

I’ve had the pleasure of speaking with several people from all over the world these past few weeks. Because most of these conversations centered around consulting, they naturally touched on all these topics.

In order to make sense of all those meeting notes, I’ve compiled people’s suggestions under three general topics, each relating to one of the questions above.

Professional Focus

I think this is similar to the common phrase Go to Market Strategy, having a solid understanding of what client size, industry, project types, and focus areas I’m best suited for (and most interested in) pursuing. Only then will I effectively be able to craft a message that reaches and resonates with them.

Set a Focus Area

Being a generalist is often a great quality to have, but just about every topic noted below gets harder without a particular focus point to start with.

“What are you known for?” Ideally, you’re marketing yourself for the work you enjoy most and are known for.
Leto Papadopoulos, Career Coach with the Muse

Be focused and niche down, be specific about “here’s what I do”
Jim Gianoglio, Cauzle Analytics

Make it Memorable

This is all about the messaging of that focus area so it’s memorable to potential clients. Even if they’re not looking now, they have a greater chance of remembering me later when they are.

Let them picture you doing the work – share an example of how you’ve done this.
Leto Papadopoulos

“Why are you doing this?” Need to be able to explain quickly and succinctly.

Get better at explaining what you enjoy most and how that benefits them and their company
Dan Donald, Here In The Hive

What’s the one sentence tagline? “I want you to think of this when you think of me“
Jim Gianoglio

Discoverability

I could have the most perfect website and LinkedIn profile the world has ever seen, but it wouldn’t mean much if no one is looking at it.

Blog Posts

It’s no secret that regular blogging has a huge impact on SEO, and searching is a great way to get more serendipitous connections from people that need exactly what I can provide.

Consider using [blog post] titles that are things non-tech people would search for, could lead to projects.
Leto Papadopoulos

Networking

There’s no substitute for good ol’ fashioned networking. Lately I’ve been finding some success especially with LinkedIn, less so with other platforms. Here’s some advice from Leto about other networking avenues to explore.

Think locally: who can you meet with? Get in front of people!

Givers gain: come out of every meeting with something. (idea, lead, introduction), but also see how you can help others. Be a resource.

Set regular meetings with people you connect with

Reach out to old colleagues from previous roles. Let them know you would like to help with project work – share a couple areas you can help with.

Leto Papadopoulos

Entrepreneurship Through Acquisition (ETA)

Essentially, purchasing an established company and using that existing network to hit the ground running more quickly. While I’m on the fence about whether I’d be interested in this personally, it does seem a great way to quickly ramp up in the discoverability department.

Thanks to Jim Gianoglio for introducing me to this topic. Jim also shared a couple resources to start with if there’s interest in learning more:

Buy Then Build: How Acquisition Entrepreneurs Outsmart the Startup Game book by Walker Deibel
Models of Entrepreneurship Through Acquisition Stanford Research Study by R. Ellis, Lacey Wismer

Positioning as an Ideal Candidate

I think this is often referred to as Value Proposition. As a freelance web developer, it’s important that my expertise, personality, and availability are front and center when potential clients come across my website or social profiles.

Speak in Outcomes

It’s great to list technologies I’m proficient in and places I’ve worked, but those don’t speak to what I can offer in terms of outcomes. It’s an understanding of the potential outcomes that people really need in order to see me as an ideal candidate.

“What is the outcome for them?” “I do [x] so you get [y]” – What would a business leader need to hear to help them understand the benefit of what you’re offering?
Dan Donald

References

While it’s difficult sometimes to speak freely about past projects, there’s no substitute for a strong case study. As Razvan points out below, even if you need to anonymize some of it.

may be even with work you did for previous employers though as those deliverables are not your IPR anymore [you] won’t be able to name, but you can still reference the client problem, solution, and benefits.
Razvan Popescu

Testimonials

Quotes from peers and past clients can go a long way towards demonstrating expertise. They can highlight personal qualities better than case studies, and gives a little window into what it’s like to work with me.

Work in Progress

Just like I mentioned in the last post, I’m still figuring this all out and don’t have great answers yet. But I think I’m getting closer!

Writing about my progress has helped me make sense of all my thoughts, compile the great feedback from others, and get myself on the right track.

In the past weeks I’ve

Added a testimonials section, as well as a couple randomized on some key pages.
Tweaked some copy on Services, added a dedicated Resume page, and shared my personal & professional Mission Statement.
Compiled a list of blog post ideas, some more (like this) about my freelance process and several others that deep dive into technical web development topics like Eleventy and Web Components

A sincere and enthusiastic thank you for reading all the way to the end. While I have your attention, I’m still looking for freelance web development opportunities so if you have something coming up I’d love to hear more about how I can help bring it to life!

Going Independent – Week Two Check in

2023-07-10T20:35:46.000Z

I’m following the same format I did in last weeks check in, it’s the simplest way to jot things down quickly and seemed to be well received as “easily parsable”.

What Happened Last Week

I spent a whole day this week on one proposal draft, I know it’s going to get easier as I build up my process but I still was surprised at how much effort was involved!
Had a few scheduled calls with folks. One was with someone interested in hearing more about what services I can provide to potentially collaborate together, one with another person who decided to start their own company after being laid off as well. Some really nice chats!
Based on some recommendations, I’ve finally joined the modern social world and have been giving some Discord servers a try. So far I’ve joined a few freelance and frontend web development related servers, I need to manage the notifications from them but so far it’s been nice!
I also finally got an invite to BlueSky, and am going to give that a try for a while.
Blogged about The Ideal Client and Project after bringing it up on some social media platforms, I received some great feedback on that and wanted to share that as well.
Started a new weekly plan and have used it once so far, it feels better now that it focuses on some of my new (and renewed) professional goals around my freelance business and Be Inclusive.
I took Tuesday off to enjoy time with family for the 4th of July holiday. Also my dad arrived in town Friday so I took that day and the whole weekend away from the keyboard and enjoying that time too. Time away is so important to recharge and come back rested and ready to go.

What’s Coming Up This Week

I heard back about that proposal for a lead that came in the week before last, need to get that updated and back out to them early this week.
I’m a terrible son and didn’t get any work in on rebuilding that site for my dad, prioritizing it this week!
I’ve done some work on strengthening and refining my message, that’s what led to the ideal client and project blog post. I do, however, feel like I’m just getting started and need to give this some more time and attention before making content changes.
Besides this one, I’ve got one other freelance introspection blog post in a draft and scheduled later this week. I’ve really been leaning into sharing more of my process. It’s been serving multiple goals, I think best when I write stuff down so I get more clarity, and I also need to keep up some content authoring so I can periodically mention that I’m still open to freelance projects.
Continue iterating on that weekly plan I restarted, and I plan on getting back into daily gratitude journaling and more in-depth review now that I have a weekly plan back in place.

Thanks for reading, onward and upward!

If you’re enjoying this format, why not have a read of the Week Three Check In?

The Ideal Client and Project – Freelance Introspection

2023-07-06T14:19:25.000Z

I’ve realized there’s a surprising amount of introspection required when you decide to go freelance. One is to figure out “the ideal” client and project.

When working at a company we don’t get the luxury of considering these ideals, you’re assigned a project and that’s that.

Getting Started

Now that I’m actively looking for opportunities, it’s important to have those ideals in mind so I can try to target those companies and projects that would be the best fit for me.

I’m gonna be honest, I still don’t have a great answer to this yet. Since I committed to sharing more of my process of going freelance, I’m posting my process now and hope to have an update soon with a clearer answer.

Here’s some questions I’m mulling over so far, I feel like the answers of these will help me get there:

What are some recent projects that made me feel the most proud when it was completed?
What kind of project teams did I tend to gel with the best?
What technologies were in use that made me the most fulfilled as a developer?
What kinds of clients inspired me to give my all every day?

Taking it Social

An earlier draft of this went out on LinkedIn, Twitter, and Mastodon. I got a couple of very interesting replies that I’m going to add to my own process, sharing them below so you can give them a go as well.

Alistair Shepherd

Many thanks to Alistair for sharing this gem via Mastodon.

It really makes sense to focus on the people and industries that resonate and provide more satisfaction. Something I’ll be keeping in mind in the work ahead.

Jon Gibbins

I’ve certainly found the focus that comes from such introspection to be beneficial to also focussing my marketing efforts and value proposition.

One exercise I did a few years back was to put a line down the middle of a piece of paper, then write the things / values that matter most to me personally on one side, and the things I think matter most in my work or even the main kinds of projects / clients I’ve worked on / with. Then draw lines from one side to another to connect items that are linked to find common ground. These are areas of focus. Anything else should show where your work is not meeting your personal values.

You can do something similar with Ikigai exercises.
Jon Gibbins via LinkedIn comment

I really like this mentality of starting with my own values and letting that guide the process of finding common ground for clients and projects.

I had recently shared my personal and professional mission statement that I’ve been iterating on for over 5 years, I’m going to try this suggestion with that as my starting point.

How About You?

Have you done an exercise like this before? If you have some ideas to help me bring this more into focus I’d love to hear it!

By the way, I’m still looking for freelance web dev opportunities so if you have something coming up I’d love to hear more about how I can help bring it to life!

Going Independent – Week One Check in

2023-07-02T15:59:55.000Z

It’s been a week since I shared I’m focusing on full time freelance web dev, which was about a week after being let go from my previous full time position.

Thanks to so many of you that expressed appreciation for the openness, and those that interest in hearing more about my process to going full time freelance, I thought I may try to keep that weekly cadence for a bit as I continue to figure things out.

So, here’s a quick bulleted check in after one week!

What Happened Last Week

Operations setup

I’ve got an LLC, business insurance, a PO Box, and business checking account ready to go.
Opted for an all-in-one project management SaaS called Plutio that will allow me to handle scheduling meetings (like Calendly) as well as manage proposals, contracts, projects, and invoices. I tried several others first and this was the one that clicked best with how I like to stay organized, and offered all the features I need right now.
I set up a Google Workspace too, I wanted to have some separation between my personal email and files and those for my business. I also had trouble with emails arriving slowly when set up using POP3 fetching as part of my personal account.
I have a fairly detailed spreadsheet that helped me figure out what my rates should be in order to cover expenses and replace my salary. I’ve figured out how that translates within a few popular billing models (like flat rate, retainer, etc.) too.
I’ve been working on some templates for proposals, contracts, and generally getting myself organized to keep track of leads and conversations. I’m thinking this may be a good topic for a future post. Let me know if you’re interested in hearing more!
I’ve scrapped all my old weekly planning, and whole sections of my todo app. It’s amazing how much of ones life is dictated by their job!

Networking & Outreach

I’ve only posted once on LinkedIn, Twitter, and Mastodon this past week, I’m honestly not sure how often I want to post moving forward, but I know I’m never going to be a once-a-day content generating machine that I’ve seen on these platforms. It takes a lot of effort and I just can’t get past the feeling like I’m repeating myself too much.
I’ve had a few great chats with other folks looking for their next adventure too. It’s been nice to work through some feelings, share a bit about ourselves, and help each other get excited for the future. I’m still open to chat if you’re in this situation as well, reach out so we can set up some time!
Either via email or social messaging I’ve reached out to about 10 individuals or agencies that I wanted to network with and chat about freelancing in general. I’ve had a really nice conversation with two (thank you both!) and hopefully more coming soon. If you’re interested in talking shop about freelance, consulting, and otherwise working solo please do reach out as well!
I’ve started some more targeted outreach for my digital accessibility auditing SaaS app Be Inclusive too, another 10 or so went out last week and two have responded back so far!
Also, happy to report I’ve had a few project leads come up, waiting on a meeting for one and need to work on a proposal for another. The third ended up being too expensive so we agreed to not move forward – a great reminder to insist on a budget upfront so you know what constraints you’re working under.

What’s Coming Up This Week

I’m going to put some time into a proposal for a lead that came in last week.
I’ve received several great pieces of advice from a few of the outreach conversations with other freelancers. I will be working on strengthening and refining my message, in particular around the services I provide. I’ve been so used to moulding myself to the project as I never had control over what I was assigned, now that I do I need to put more thought into the ideal projects for my skillset.
I’m shooting for at least one blog post a week, I don’t want to go overboard right away and feel like one a week should be manageable for a while. This one may count for this week, though I have some drafts I could put some time into as well.
I’ve got to get going on rebuilding a site for my dad, looking forward to trying out a couple new things and learning in that process as well.
I mentioned above that I scrapped my weekly planning, now that I’ve hit the reset button I’m going to build up a weekly plan that focuses more on my freelance business and Be Inclusive in addition to the personal and life stuff I had previously. Excited to get that started and iterate over time based on what works for me.

I’m rather new to “working in the open” so I’m just doing what feels right. What do you think, do you like this format? Got any tips for an old dev trying new things?

If you’re enjoying this format, why not have a read of the Week Two Check In?

Steve Woodson – Independent Web Development Consultant

2023-06-26T11:14:57.000Z

TL;DR

I’m terrible at burying the lede (as it’s the title of this post) so I’m starting with the TL;DR. I’m venturing out on my own offering freelance web development consulting!

Check out:

Services for my core values, how I’m different, and what web development services I can offer.
Testimonials for some kind words folks have recently shared about me, my work, and my leadership.
Project Inquiry to get in contact about an upcoming project I can help you bring to life!

The rest of this post shares some reflections on the past week, and goes into more detail about how I got to the point where I’m ready to go independent, and what else I have planned for the near future.

Reflecting on the Last Week

One week ago today I shared that I was laid off. I didn’t realize at the time how much this would resonate with people and am deeply humbled by the response.

Hundreds of reactions, dozens of comments, and just as many direct messages and emails. I’ve even got a few meetings scheduled with folks just to chat about our experiences and talk about what gets us excited about the future.

The offer made last week about being open to chat still stands. If you were recently affected by workforce reductions, are struggling to find the next adventure, or just want to chat about the difficulties we’ve all been facing these past few years.

Feel free to DM me on a social platform or send me an email. We can even book a half hour chat if you prefer to talk face to face. Let’s make some lemonade from these lemons!

The Dream

A few years into my web development career, somewhere around 2005, I started to dream about venturing out on my own. I would even go so far as to take on the odd freelance job when the opportunity would arise.

But I was a long way from taking a chance on full time freelance web development consulting.

I knew there was so much I could accomplish but also that the work itself is only one (albeit very important) part. I recognized that there’s marketing, sales, and business management that goes into it as well. Frankly, I was terrified of all three.

The most visceral reaction, however, was the scarcity mindset. The fear that I’d get everything set up, put myself out there, and nothing happened. I wouldn’t make any digital marketing connections, wouldn’t find clients that saw my potential as a web application developer, wouldn’t land any web dev projects.

It was enough to deter me from even giving it a try. So, for over 15 years this dream sat there in the back of my mind.

Why Now?

It’s amazing how much time one has to sit and think when not engrossed in day to day work. I spent a lot of that time this past week thinking about

what I’ve yet to accomplish
what I want my days to look like
and what is going to get me excited to get up out of bed every morning

I knew right away, there’s still that one big goal that checks all three of these boxes. Maybe losing my job is the universe telling me to just go for it already?

I had shared that thought privately with several colleagues, friends, and family and every single one had something positive to say. Here are some of them that really resonated with me:

“What you water will grow”
“Sometimes many of us need that kick in the ass.”
“This is definitely a sign from the universe for the push you needed […] everything happens for a reason!”
“That would be so great! One door closes, another opens”
“That’s great to hear on independent consulting. I’m big on universal signals, too!”

I’ve grown a lot in the last handful of years, not only as a developer but as a more confident leader, empathetic collaborator, and accessibility focused technologist. I’ve worked hard building a personal brand and now I feel ready to share all that experience directly with client teams as an independent consultant.

Making it a Reality

I’ve spent a considerable amount of time working through details and getting everything set up. In addition to the site updates noted at the beginning of this post I’ve also secured

a registered LLC, in partnership with my wife
business insurance, including cyber coverage
operations details including communications workfows, project management, and contract templates

I’m sure there’s countless more things that I need to do, but I’ve got the fundamental aspects ready and am officially open for business!

What’s Next?

Thought Leadership

Expect to see more “thought leadership” from me, even though I am not altogether fond of that term it does serve as a useful shortcut to what I mean. I have a dozen or so blog posts in draft ranging from technology leadership, productivity, and specific solutions to some of the day to day struggles of web developers.

I’m still learning when it comes to marketing, but one thing that always resonated with me is the simple fact that sharing what I’ve learned and helping others builds awareness and connections. That awareness and those connections can often lead to surprising and unexpected things.

Be Inclusive

I’m also working on more roadmap items for my SaaS accessibility auditing app Be Inclusive too. I’ve often lamented not having as much time as I would have liked to keep breathing more life into that app, make it faster, more compelling, and easier to use for the people that work so hard every day to push accessibility forward.

Got ideas?

What else would you like to see more of from me? If you’ve got some thoughts and ideas I’m certainly interested in hearing more about it.

I have some time now, and I’m so excited to be able to start spending more of it contributing to the web development, application development, and digital accessibility communities that have helped me learn and grow so much these past 20 years.

If you have a project coming up that could use an experienced web developer to help bring it to life, get in touch! I’d love to hear more about what you have planned, and how I can help.

Onward and upward! 🎉

I Was Laid Off, Now What?

2023-06-19T14:33:37.000Z

If you’ve been following the news lately, it’s been a rather tough time in technology this year. Not a week goes by without news of several major companies letting go of significant percentages of their workforce, so much so that many organizations are keeping track of 2023 tech layoffs.

Well, as of last week I’m now one of the tens of thousands affected by these ongoing tech workforce reductions.

Facing The Feelings

Grief, Stress, Guilt

A few months ago, because of how pervasive layoffs have been industry-wide lately – including multiple rounds at my previous employer – I had done some reading on how to best support those affected. This article about Job Loss Grief and this one about Unemployment Stress struck a chord with me and I appreciate their advice even more as I read them again now. I highly recommend them, for folks recently laid off as well as for those interested in helping them.

Some of the most common advice in these and many other articles was to write about your feelings, share your story, and talk about it. That was the impetus for this post.

My Immediate Reactions

My first thoughts mid-call as I realized what was happening were “what about my coachees? what about my project team?” These people are going to be affected by this as well, now needing to carry on with less help and likely more anxiety about their own futures.

I’ve come to realize how much of a daily routine and sense of self gets tied up in a job after nearly 8 years. The more difficult realization is how quickly it can all disappear. Get the call and minutes later you’re locked out. I understand the precaution of it, and I know it’s never easy for those on the other side too, but there’s an abrupt coldness to it that still stings.

As strange as it may sound, I also felt a bit of guilt. Thinking of the tasks I postponed til later. That client project ticket I was actively working on. I should have committed that code, I should have written out some notes about my thought process, I should have been more diligent about taking notes about future plans.

Reflections

I had jotted down some reflections as they came to mind, here’s some of them.

Several times I’ve found myself in the Slack app on my phone, my autopilot taking me there to check out the latest messages only to be reminded that it’s gone.

I was blown away by the dozen or so folks who reached out to me immediately in these first days, that kind of support is not something I expected nor take for granted. I appreciate each and every one of them.

I have grown so much as a developer, a mentor, and a person in these past 8 years. I had the privilege of being a career coach to 10 wonderful people, worked on dozens of client projects, and had a small part in bringing accessibility to the forefront company-wide.

I’m going to miss so so much.

The little things. The everyday chatter with colleagues, shared pet pictures and music recommendations, opinions about industry news and latest goings on in web development.

The big things. The years-long collective accessibility documentation I had helped to curate in the company wiki. The client project I had spent the past year and a half guiding towards less technical debt, better accessibility, improved performance, and more efficient process. The team I was fortunate enough to work with, help guide, and learn from every day.

Self Care

In the same articles I had mentioned in the section above, another key point they all share is that you need to be intentional about taking care of yourself. Try to eat well and get good exercise and rest, seek good company, and practice mindfulness. It’s critical to do these things to balance against the grief, stress, and guilt.

Here’s some of my self care items these first few days.

I watched some guilty pleasure shows I don’t often make the time for, especially in those moments where any deep work or thought doesn’t come so easily. I gave myself permission to slow down and just enjoy something a little mindless.

Went on an hour and a half walk with my wife, including through a forest preserve. Time outdoors and in nature is never wasted.

A couple close friends took time out and set up an outing for all of us. It was a great time, I didn’t realize until later how much that lifted me up. I absolutely needed it and am so grateful.

Being the organization and productivity nerd that I am, I got some strange sense of enjoyment cleaning up my note taking apps, updating a bunch of my contacts with photos, and ironically enough in capturing the thoughts that led to this blog post.

I finally reorganized the living room entertainment center, wire management and all.

Today, I’m about to get to some yard work while listening to an audiobook.

Wrapping up

It was cathartic to jot down these thoughts and then compile them to share openly. I do feel like it’s helping me process things and start to look optimistically at the future.

Open Invitation to Chat

I’m sharing all this here in the hopes that it helps others going through this too to know you’re not alone, and whatever you’re feeling is a normal part of the process. Maybe it helps you make sense of your own experiences too.

Open invitation to you as well to chat via email, social media DMs, whatever you like. Let’s talk about it, share some reflections and process things together, then we can move on to talk about what has us excited for the future.

Speaking of, I’m some combination of excited and nervous about what I’m planning next. Working on some details and will be sharing more about that very soon. Stay tuned!

Intentional Attention – My Organization Strategy for Interesting Reads

2023-05-21T15:00:15.000Z

I’m trying to be more intentional about reading through the backlog of cool projects, articles, and newsletters I collect throughout the day. Be it from colleagues, social media, my blog feed reader, or from emailed newsletters and link roundups, there’s a lot of great stuff out there!

I’ve come to terms with the fact that there’s always going to be more to see and do than there is time for them, and there’s no better example of that than this constant stream of great content.

This is why I regularly refine my organization and time management strategies, I want to be more intentional about what I put attention towards. In this article I’ll share how I moved from ad hoc and rushed parsing to a more sustainable and intentional way of giving this great content the time they deserve.

“Not Right Now” Ad Hoc Attention

Before, when I found an interesting article I’d tell myself “not right now”. So it sits in a tab or quickly added to a reader app. A great newsletter arrives but “I can’t today” so it sits unread in my email until I have more time.

But, more time doesn’t materialize. So I’d parse through as best I can. Skim some articles over lunch or in between meetings. Click through some newsletters as I mindlessly check emails. I knew I was missing out but tried to rationalize that I got the gist of it.

I’m sure you’ve been there too.

Intentional Attention

I came to realize I was getting overwhelmed with it all and the ad hoc parsing wasn’t really working. I always felt rushed and knew I was missing out on some great ideas, projects, and sales.

Getting organized

Here’s what I’ve been doing about it:

Mark emails as “BAC’N“
It’s not spam but also not urgent, so I remove from the inbox but leave it unread
Articles and links go to a Todoist to do list
If it’s more urgent I may set a due date, then I close the tab
Set time aside to get to as much as I can
Timeboxed and go in date order so I don’t miss time-sensitive items like sales or world events

I move them so they don’t take brain space, they all go to the same place so I stay organized, and I can mentally let them go because I know I’ll get back to them later.

Time to read!

I chose a weekend day where I’m more relaxed and able to concentrate, and I timebox myself so I don’t end up going down too deep a spiral to the detriment of other things I’d like to get to in the day. This is definitely the hardest part and something I still struggle with.

When I do get to reading through this backlog of content, I do a few additional things to help me parse quicker, remember important things, and plan ahead:

Something I want to save long term?
Great ideas, methodologies, and projects I may want to refer back to, for example. I add it as a clip to Evernote, it captures the content in the page so I can more easily search for it later.
Something I need to act on?
A great sale coming up, something I want to participate in, or share with others. I either do it right then and there, or I make a todo to address it at a future time.
Something I realize I’m not interested in?
Especially for longer lists or articles I start by skimming through, if I realize it’s not something I want to spend time on I give myself permission to let it go and move on.

It’s Working

No more unreads in my inbox.

No more tabs slowing down my browser.

I feel a bit more connected and a bit less overwhelmed.

It’s been a handful of weeks and I’m fairly certain if I didn’t have this organization in place I wouldn’t have made the time to discover some really interesting projects, thought provoking articles, and a couple good sales. I’m so glad I did.

As I finished drafting this, I realized it’s an unintentional follow up to Email Newsletters – My Emotional Response Spectrum and Organization Strategy. If this article resonates with you, you may enjoy that one as well, it’s a deeper dive on how I tackle the onslaught of daily emails.

What do you do about the constant stream of articles, links, and emails? I’d like to hear about it, always on the lookout to keep refining my process!

Plaid Swatch Generator

2023-04-23T19:50:40.000Z

Sometimes you’ve gotta make time to build something fun, today I whipped up a Plaid Swatch Generator!

Background

I built up my personal branding centered around the use of various plaid color combinations. I wanted all my projects to have unique color palettes but a distinctive style that was immediately apparent. For example, below are four of the logos I’ve created.

Some examples of my personal/professional branding

Early on, I was able to figure out how to get this to render as an SVG so I had more options for manipulating and so the plaid was always as performant and crisp as possible. I built a quick CodePen of it and moved on.

Impetus

I had a laundry list of things to do today, but I didn’t have much motivation so I was looking around CodePen (as you do) and came across the plaid Pen I had noted above. It sparked a thought “hey this could pretty easily become a cool plaid generator, I’d just need to figure out how to change the colors dynamically.”

Build

The dynamic color updates ended up being the main chunk of work here. Once I got color input elements added to the page and wired up with a bit of JavaScript, changing the fill of the related SVG rectangles was pretty straightforward.

I figured out how to get the colors to reflect in the example as you pan through the color wheel too, making choosing colors pretty intuitive as long as your browser supports more modern color picker options.

Easy Sharing

Check out some of the ones I generated as I was testing!

Since the main chunk of work wasn’t too bad, I set my sights on making this as easy as possible to grab and share. So I’ve added:

a download button, so you can get an SVG of your creation straight away
a URL auto-update to match your choices, making it easy to bookmark or share too

Feedback?

I have some other ideas for this, but wanted to make sure I kept it to an afternoon of hacking away. I do want to revisit it and refine with more, so give the Plaid Swatch Generator a try and let me know what you’d like to see added!

How I Hacked My Brain to Let Myself Relax in the Evenings

2023-03-28T12:27:44.000Z

Do you ever find yourself constantly on the go, always trying to be productive? I’ve struggled with this for most of my adult life, spending evenings checking off tasks on my to-do list, a blur of writing code and responding to emails. But after a while, I realized that this wasn’t sustainable. I was regularly anxious, tired, and felt like I couldn’t just relax and recharge. I also didn’t like the feeling that family and friends were getting the leftover time not otherwise spent in this productivity cycle.

The Impetus

I’ve been reading a whole lot of self help and productivity books the past few years. Largely as a shot of motivation to keep up the few “tricks” that have started to help me control that anxiety while still pursuing goals, but also out of a desire to find new or different tricks to try.

One concept that came up often in these books is around being intentional with your time, be it making time for what you consider important, removing what you don’t consider to be essential, or building resilience to distractions.

They all come down to taking charge of your time.

“You only waste time if you’re not intentional about how you spend it.”
Jake Knapp & John Zeratsky, Make Time: How to Focus on What Matters Every Day

How I took charge of my time

First, I had to come to terms with the fact that I have a strong need to feel productive. I’ve come to realize I can only really relax when I feel a sense of accomplishment, and know that I have a plan for continuing that into the future. So, instead of fighting against this part of myself, I decided to work with it.

“Remember that if you don’t prioritize your life someone else will.”
Greg Mckeown, Essentialism: The Disciplined Pursuit of Less

I started by time-boxing my productive time in the early morning before work. I found that I was most focused and least distracted in the morning, so I dedicate a couple of hours each morning to tackling my most important goal for that day.

“something magic happens when you start the day with one high-priority goal.”
Jake Knapp & John Zeratsky, Make Time: How to Focus on What Matters Every Day

Next, I started setting a daily “theme” for myself. This meant that each day, I would focus on one particular goal. For example, Monday might be dedicated to building a feature on Be Inclusive, Tuesday focuses on a blog post (like I am today), Wednesday towards reading a backlog of blog posts I’ve let pile up, etc. This helped me to avoid spending too much time on one particular area and ensured that I was making progress on all fronts.

I come up with these daily goals during my weekly planning every Sunday, so I’ve got the whole week mapped out in advance. This gave me peace of mind in the evening knowing I had time set aside and a plan for it the next day.

Permission to Relax

The end result? I can now relax in the evenings without feeling guilty or anxious about all the things I need to do. And, because I made it a habit to go to bed at the same time every night and wake up at the same time every morning, I’ve noticed that I’m sleeping better and have more energy throughout the day.

“The people we love most should not be content getting whatever time is left over. Everyone benefits when we hold time on our schedule to live up to our values and do our share.”
Nir Eyal, Indistractable

If you’re someone who always needs to be productive, I encourage you to give this approach a try. It might take some time to get used to, but trust me, it’s worth it.

Email Newsletters – My Emotional Response Spectrum and Organization Strategy

2023-03-13T11:43:08.000Z

How’s that for a title? Basically, this is all about how I personally categorize newsletters, how that categorization has influenced how they’re organized, and how much attention they get as a result.

I don’t think it’s a controversial statement to say that email newsletters fall on a spectrum of emotional response between “awww yeah!” to “please, no.” I’m sure I’m not the first to frame it this way, though I’ve yet to see anyone else act on that emotional response in how they organize and read through these incoming messages.

Emotional Response Spectrum

Awww yeah!

These are the newsletters that help me stay in touch with the world, my industries of interest, and people I admire. The emotional response for me is one of excited anticipation, I know I’m going to spend a good deal of time on these and will generally enjoy them.

The vast majority of these tend to be of a link roundup variety. People go through quite a bit of trouble sifting through the endless stream of information and share the gold, and I really appreciate that. Some others are deeper dives into current events or a particular topic that I find interesting.

Some of my current favorites:

Alright, thanks.

These are the newsletters that are only occasionally relevant to me, have a certain quality that I appreciate, or otherwise are “okay” enough to open and scan in batches.

Nearly all of these are the daily-ish emails from brands, I regret to admit that most haven’t been unsubscribed because of the occasional emailed coupon. Some select few (like those noted below) I mostly keep around because I enjoy their messaging or find the information useful enough to scan when I can.

Some Examples:

Who Gives a Crap – Great brand that puts a lot of effort into making their mailers enjoyable
USPS Informed Delivery

Please, no.

Basically any mass-email sent to me without my asking for it.

Some examples:

Any newsletters I get auto-added to when I create an account, bonus 👎 points for those that don’t even make it a checkbox option in the sign up form.
Unsolicited messages for products or services past the first three. I give many a pass on a few cold emails when done tactfully, can’t fault someone trying to grow their business.
Extra rage bonus points to any I can’t easily unsubscribe from. One big example was the Ozy Media company, which I continued to get spammed daily until they finally shut down.

Email Organization Strategy

I get an unbelievable amount of emails every day, most I don’t need to spend mental cycles on anywhere remotely near daily. I am – for better or worse – an inbox zero kind of guy, so I’ve honed this strategy over the years to balance the need for a tidy inbox with the need to not be sifting through emails for hours every day.

My Newsletter Rules

I have a few strongly held rules to help maintain a reasonable number of emails coming through:

If I’ve not opened any messages from a particular sender in the last week or last 5 emails, whichever comes first, then I unsubscribe. This one is occasionally hard because I _want_ to like it, but actions speak louder than intentions. Time to go.
If you send more than 2 emails a day, I’m looking for ways to adjust my preferences. If I can’t adjust email frequency I’m out. I can barely count on one hand the reasons I’d be okay with this frequency of messaging.
If you send the same email multiple times, I seriously consider unsubscribing. I’m really sorry, I know email marketing is hard, but it’s not like Twitter where we’re trying to stay fresh in the ongoing stream of posts. Multiples of the same email still need to be handled separately and my patience for that is long gone.

Automated Categorization

Now that I’ve level set on the messages I’m willing to keep, I need to keep that list of messages organized. I use Gmail, though I’m sure this would work with any email organization system worth using. I set up rules for individual sender email addresses to go into one of a few newsletter specific labels:

BAC’N – Anything that doesn’t fit in the below two categories. I call it bac’n because, like spam, bacon is best enjoyed only occasionally.
Daily News – All the world events, financial, and other general daily news I try to consume to stay informed
Industry – All the web development, accessibility, design system, technology, etc. news that keeps me up to date on what’s trending around me professionally.

My newsletter inboxes

These emails are set to skip the inbox and go directly to the selected folder. This way I don’t get notifications of new messages, and I’m able to ignore them until I’m ready. Which brings me to…

Managing my Attention

Great, now I’ve got stacks of organized emails by category. Now, what do I do with them?

BAC’N emails are scanned as quickly as I can manage, I tend to do this about once a week. I take note of sales and any links to articles I may want to read in more detail.
Daily News I try (and often fail) to keep up with every morning. If I miss a few I read the latest and then scan the older ones for any info I may have missed. Given that they tend to be daily news, it’s often updates on ongoing stories so this has worked out pretty well.
Industry emails tend to take me the longest to get through because there are a lot of collections of links to long form articles. I try to chip away at these as I have some time but honestly this is the hardest one to manage because I wanna read _it all_ but it takes a lot of time.

Overthinking it?

Sometimes I do think “this is a lot of consideration for email newsletters”. But I’ve come to the conclusion that the occasional time I put into curating saves me a whole lot more in the long run. Besides, if you don’t control where your attention goes someone else will.

CloudFront Function for basic auth, redirect, and serving from S3

2023-03-09T14:08:28.000Z

I recently had the opportunity to rethink how some CDN customizations were happening within an Amazon AWS managed project. Previously, we had used a couple Lambda@Edge functions to perform some light modifications during the Viewer request and Origin request cache behaviors. We had largely inherited the setup so hitting the reset button with some needed changes seemed a good idea.

Initial CloudFront Function Research

Enter CloudFront Functions, I had actually not heard of them previously but apparently they’ve been around since 2021. After getting up to speed reading up on the use case it seemed an ideal evolution from Lambda@Edge. The parts I was most excited about was reading the following:

offers submillisecond startup times, scales immediately to handle millions of requests per second, and is highly secure

Our use case needed the following:

Basic Authentication for all lower environments, because we don’t want public access to content that’s still a work in progress
More control over redirects, because we’re using a JavaScript framework we weren’t able to control the response status as well as we would have liked (301 instead of 302 for example)
Add index.html to request URLs that don’t include a file name, also because we’re using a statically generated site based on a JavaScript framework.

Gotchas

I was initially surprised – coming from the Lambda functions mentality – that I wasn’t able to use a couple of the JavaScript niceties like the Nullish coalescing operator (??), Optional chaining operator (?.), and Conditional (ternary) operator. Found out that that’s because CloudFront functions only support ES 5.1.

I was also pleasantly surprised to see a high focus on optimization and utilization, you even get a handy “Compute Utilization” score every time you test so you can keep tabs on ensuring it’s comfortably within the max allowed time.

While much of these weren’t an issue for me, I also found out that:

Dynamic code evaluation (eval for example) and Timers are not supported.
The maximum memory assigned to CloudFront Functions is 2MB
CloudFront Functions only respond to Viewer triggers whereas Lambda@Edge can work with both Viewer and Origin triggers. In my case I was able to merge the code we were using in both situations without any issue, but your mileage may vary.
CloudFront Functions only support JavaScript (ES 5.1 as noted above), Lambda@Edge supports Node.js and Python too.
CloudFront Functions do not have access to the network or filesystem.
CloudFront Functions can only manipulate HTTP headers.

Benefits

Overall cheaper, and there’s a free tier available too.
Building & testing are so much faster because you can do so directly within CloudFront, no more saving, creating a version, attributing that to the CloudFront cache behavior and deploying to test!
Speed and scalability are amazing, you can support 10,000,000 requests per _second_ or more compared to up to 10,000 requests per second per Region for Lambda@Edge.

If you’re interested in more notes to help you choose which way to go, this Choosing between CloudFront Functions and Lambda@Edge section was really helpful for me.

The Code

Let’s get to work!

Final source

var authRedirect = {
  statusCode: 401,
  statusDescription: "Unauthorized",
  headers: {
    "www-authenticate": {
      value: 'Basic realm="Enter credentials to access this secure site"',
    },
  },
};

/**
 * Basic Authentication
 *
 * On all lower environment (dev & qa) we need basic authentication so general
 * public cannot access these sites. Bypass on prod and if authentication is
 * already secured.
 *
 * @param authorization - Incoming request authorization value
 * @param host - Incoming request host value
 * @returns boolean - Whether this request is authenticated
 */
function authCheck(authorization, host) {
  var productionHosts = ["mywebsite.com", "www.mywebsite.com", "blog.mywebsite.com"];

  // The Base64-encoded Auth string `secretuser:secretpass` that should be present.
  var expected = "Basic c2VjcmV0dXNlcjpzZWNyZXRwYXNz";

  // If this is a production website, we do not want to force any authentication
  if (productionHosts.indexOf(host) > -1) {
    return true;
  }

  // If an Authorization header is supplied and it's an exact match
  if (authorization && authorization.value === expected) {
    return true;
  }

  //Not production, auth header is either missing or failed to match
  return false;
}

/**
 * Redirect Check
 *
 * @param host - Incoming request host value
 * @param requestURI - Incoming request URI
 * @returns object|false - Returns an object containing the redirect details or false if no redirect necessary
 */
function redirectCheck(host, requestURI) {
  redirectPaths = {
    // '[FROM]': {'Location': '[TO]', 'status': [301|302]}},
    "/old-page-1": { Location: "/new-page-1/", status: 301 },
    "/old-page-2": { Location: "/new-page-2/", status: 301 },
    "/old-page-3": { Location: "/new-page-3/", status: 302 },
  };

  if (Object.keys(redirectPaths).indexOf(requestURI) >= 0) {
    var redirectTo = redirectPaths[requestURI];
    return redirectTo;
  }

  return false;
}

/**
 * Redirect Response
 *
 * @param redirectTo - object containing the redirect location and status details
 * @returns object - response object with redirect details
 */
function redirectResponse(redirectTo) {
  return {
    statusCode: redirectTo.status,
    statusDescription: "Moved",
    headers: {
      location: { value: redirectTo.Location },
    },
  };
}

/**
 * URL Rewrite
 *
 * Appends the /index.html to requests that don’t include a file name or extension
 * in the URL. Useful for single page applications or statically generated websites
 * that are hosted in an Amazon S3 bucket.
 *
 * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/example-function-add-index.html
 * @param uri - Incoming request URI
 * @returns
 */
function uriRewrite(uri) {
  // Check whether the URI is missing a file name.
  if (uri.endsWith("/")) {
    return (uri += "index.html");
  }
  // Check whether the URI is missing a file extension.
  else if (!uri.includes(".")) {
    return (uri += "/index.html");
  } else {
    return uri;
  }
}

/**
 * Primary Handler
 *
 * Checks for authentication, then redirect, then URL rewriting
 *
 * @param event
 * @returns
 */
function handler(event) {
  var authorization = event.request.headers.authorization;
  var host =
    event.request.headers.host && event.request.headers.host.value
      ? event.request.headers.host.value.toLowerCase()
      : "";
  var requestURI = event.request.uri.replace(/\/$/, "");

  if (authCheck(authorization, host) === false) {
    return authRedirect;
  }

  var redirect = redirectCheck(host, requestURI);
  if (redirect !== false) {
    return redirectResponse(redirect);
  }

  event.request.uri = uriRewrite(requestURI);

  return event.request;
}

Conserving Sentry Transactions by Ignoring Laravel Routes

2023-02-27T13:35:27.000Z

Yet another case of trying to find an answer to a very particular problem, coming up empty, solving it myself, and posting about it for future generations.

Update 2023-04-01

Thanks to Michi Hoffmann, this is now even easier to manage with a built in ignore_transactions configuration option now available as of release 3.17.0 of sentry-php!

Now, instead of using the before_send_transaction config I swapped to using ignore_transactions and my code changed to the following:

'ignore_transactions' => ['/_debugbar', '/monitoring', '/pleaseignoreme'],

Below is the original post for posterity, but with the addition above that solution is no longer necessary.

The Problem

I have a couple Laravel PHP routes that are triggered quite often, both are very specific to other site monitoring (is the site down?) and session management (am I still logged in?). These being utility routes that don’t serve a user-facing purpose, I don’t need any additional logging details about them from Sentry.

Can I prevent the transaction from being sent to Sentry before it even leaves my server? I tried searching terms like “sentry laravel ignore route” and “sentry control transactions from PHP” to no avail so I got to work.

The Solution

In my searches, I did find this helpful documentation for before_send_transaction specifically for Laravel. It’s an optional addition to the /config/sentry.php configuration. In it, you can define any logic you want to return null in preferred situations. This null return will lead to the event being discarded. Bingo!

Here’s the code I worked up.

'before_send_transaction' => function (
    \Sentry\Event $transaction
): ?\Sentry\Event {
    $ignore = ['_debugbar', 'monitoring', 'pleaseignoreme'];
    $request = $transaction->getRequest();
    $check = array_filter($ignore, function ($url) use ($request) {
        if (stripos($request['url'], $url) !== false) {
            return true;
        }
    });

    if (count($check) > 0) {
        return null;
    }

    return $transaction;
},

Here’s what it’s doing:

$ignore is the array of URL key terms I want to ignore, this is all you need to edit. Add any URL segments that you’d prefer not to be logged by Sentry and you good to go
$request is the request details coming from the packaged $transaction generated by Sentry. In it is the full URL that we use to test against
$check was my method of iterating through the ignore list and checking for a match. This filters the $ignore array down to just matches.
We then see if the count of $check is greater than zero, if so then one of the routes matched and we want to return null to ignore this transaction. Otherwise, return as normal.

Closure Alternative

Shout out to Alex Bouma for also noting in this Github Gist how to avoid using a closure (as I had in the solution above) because it makes php artisan config:cache no longer work. Something I hadn’t noticed until after I had the above solution in place.

If you choose to continue using before_send_transaction and need config caching, give a class a try!

That’s it!

Pretty simple, but it took a bit of digging through documentation to find before_send_transaction and through the Sentry package to see what $transaction contained so I’m hoping to spare the next dev that bit of trouble.

Onward and upward! 🚀

Joining the IndieWeb with Webmentions and Microformats

2023-02-19T17:18:05.000Z

I’ve finally spent some time setting up Webmentions and adding some Microformats formatting to this site!

These technologies have been around for quite a while but it’s taken me a handful of attempts (and a whole lot of help) to understand them enough to actually move forward. I’ve tried occasionally to wrap my mind around them but I kept getting confused about what to do and would give up for a while. I feel a little better admitting these troubles when I see folks I consider among the best in the industry – like Chris Coyier and Miriam Suzanne – having similar tough times with it.

Resources

Rather than rehashing all the details of getting my setup working, I think it’s better to list all the resources that helped me understand and/or integrate Webmentions here. Perhaps it’ll help you on your path to understanding and integrating them into your sites too.

IndieWeb & Personal Blogging

Thoughts from others on this topic that really helped me understand and get excited about putting some time into implementation.

Own your content on Social Media using the IndieWeb by Zach Leatherman
Into the Personal-Website-Verse by Matthias Ott
Am I on the IndieWeb Yet? by Miriam Suzanne
Bring back personal blogging by Monique Judge

Tutorials & How-tos

Adding Webmention Support to a Static Site by Keith J. Grant
Using Webmentions in Eleventy by Max Böck
An In-Depth Tutorial of Webmentions + Eleventy by Sia Karamalegos
Clientside Webmentions by swyx

Documentation & Services

IndieWeb – specifically IndieWeb Webmention for an intro on what they are and how to implement
Microformats – a simple way to markup structured information in HTML
Webmention.io – a hosted service created to easily receive webmentions on any web page
Brid.gy – connects your web site to social media

Great Implementation Examples

Work in Progress

There’s still more that I want to do with this, I’d love to find a good/automated way to capture syndication links for example. But I’m happy enough with what I’ve built so far to launch it and try to iterate over time. Check it out at the bottom of blog posts on my site!

What opinion, tutorial, or other reference would you add to this list? I’d love to hear about it so I can continue to learn more about this fascinating topic. I’ll try to keep this list updated over time as I discover more great resources too. Thanks for reading!

Adding a Table of Contents to dynamic content in 11ty

2023-02-12T17:47:03.000Z

This is a follow up post to Pulling WordPress Content into Eleventy, I’ve also written about how to make use of WordPress post categories and tags too. If you haven’t already I’d suggest giving those a read too!

As part of that transition to using dynamic data, I had lost the automated anchor links that were applied to all h2-h6 headlines. I’m a huge fan of deep links like this because:

it makes it easier to share specific sections of an article
you can then create a table of contents section, helpful especially for long form content
it provides another option for quick scanning and navigation

Well, I finally made some time to re-introduce them! Here’s how I did it.

Preparing the Headlines with Anchor Tags

In my blogposts.js data file I added the following function (utilizing jsdom) that

Finds all H2 thru H6 headlines
Uses the headline text to create a slug that has stripped out all code, spaces, and special characters
Appends an anchor link to each headline
Compiles a JavaScript array of all headlines and the generated slugs for the next part

Here’s the code

function prepareHeadlines(content) {
  const dom = new JSDOM(content);
  let headerElements = dom.window.document.querySelectorAll("h2,h3,h4,h5,h6");
  let headers = [];

  if (headerElements.length) {
    headerElements.forEach((header) => {
      const slug = header.innerHTML
        .replace(/(<([^>]+)>)/gi, "")
        .replace(/&nbsp;|&amp;/gi, " ")
        .replace(/[^a-zA-Z0-9 ]/gi, "")
        .replace(/ /gi, "-")
        .replace(/-+/gi, "-")
        .toLowerCase();

      const title = header.innerHTML.replace(/(<([^>]+)>)/gi, "");

      header.innerHTML =
        header.innerHTML +
        '<a href="#' +
        slug +
        '" class="anchor"><span aria-hidden="true">#</span><span>anchor</span></a>';
      header.id = slug;

      headers.push({
        slug: slug,
        title: title,
        tagName: header.tagName,
      });
    });

    content = dom.window.document.body.innerHTML;
  }
  return { content: content, headers: headers };
}

There’s very likely a cleaner way to do all this, but I got it to “good enough” and called it a day. If you’ve got ideas for improvements please use the links at the bottom of this page to let me know!

Constructing the Page Outline

With the headers compiled in the function above, I then wanted to be able to show the headlines in a page outline where sub-headlines were nested under the parent. For example all H3 headlines below an H2.

Here’s a recursive function to handle that part.

function tableOfContentsNesting(headers, currentLevel = 2) {
  const nestedSection = {};

  if (headers.length > 0) {
    for (let index = 0; index < headers.length; index++) {
      const header = headers[index];
      const headerLevel = parseInt(header.tagName.substring(1, 2));

      if (headerLevel < currentLevel) {
        break;
      }

      if (headerLevel == currentLevel) {
        header.children = tableOfContentsNesting(
          headers.slice(index + 1),
          headerLevel + 1
        );
        nestedSection[header.slug] = header;
      }
    }
  }

  return nestedSection;
}

This will create a multidimensional object where each top-level item will optionally have a children property that contains its child headings, and can go all the way down to H6.

Pulling it all together

Those two functions defined above do the heavy lifting, but they still need to be applied to the processContent function so the data that the site uses will have this new content available.

Here’s the relevant changes:

// Applying ID anchors to headlines and returning a flat list of headers for an outline
const prepared = prepareHeadlines(post.content.rendered);

// Code highlighting with Eleventy Syntax Highlighting
// https://www.11ty.dev/docs/plugins/syntaxhighlight/
const formattedContent = highlightCode(prepared.content);

// Create a multidimensional outline using the flat outline provided by prepareHeadlines
const tableOfContents = tableOfContentsNesting(prepared.headers);


// Return only the data that is needed for the actual output
return await {
  content: post.content.rendered,
  formattedContent: formattedContent,
  tableOfContents: tableOfContents,
  custom_fields: post.custom_fields ? post.custom_fields : null,

I opted to save the formattedContent separate from the content so I could have the unformatted content to use in my XML Feed that doesn’t really need all that extra HTML. I then also added tableOfContents so I can use it in my template. Speaking of, that brings us to the next section.

Creating a Table of Contents Macro

Because the tableOfContents is a multidimensional object that can be (theoretically) 5 levels deep, I wanted to make sure the table of contents I’m adding to the page would be able to handle all that too.

So, I turned to the handy dandy Nunjucks Macros to do the job. I chose macros because I can pass just the data I want it to be concerned with and not have to mess around with global data in standard templates. I’ll admit I tried a template first and ended up in some infinite loop situations, lesson learned!

Here’s the Table of Contents macro I created, saved at site/_includes/macros/tableofcontents.njk.

{% macro tableOfContents(items) %}
<ul>
  {% for key, item in items %}
    <li><a href="#{{ item.slug }}">{{ item.title | safe }}</a>
      {%- if item.children | length %}
        {{ tableOfContents(item.children) }}
      {% endif %}
    </li>
  {% endfor %}
</ul>
{% endmacro %}

Pretty simple right? That’s because it’s set up to run recursively, so it’s calling itself to create the nested lists that we’re going to render on the page.

Adding to the Blogpost Template

Alright it’s the moment of truth, let’s get all that into the page template!

I chose to put this list inside a <details> element so it can be collapsed by default, though you can also update to include open as a property of <details> to have it collapsible but open by default. Up to you!

<nav aria-label="Article">
  <details>
    <summary>In This Article</summary>
    {{ tableOfContents(blogpost.tableOfContents) }}
  </details>
</nav>

Wrapping Up

That’s all there was to it. It’s not a lot of code but I’ll admit the recursive aspects took me a bit of head scratching to figure out initially. Hoping it saves you a bit of that struggle.

If you end up using this, or improving upon it, please reach out and let me know!

Solving Animation Layout Flickering Caused by CSS Transitions

2023-02-04T17:12:58.000Z

I recently had the opportunity to redo the header section of an inherited codebase. Everything was going great, my version was nearly 30% less code, more accessible with larger clickable targets and focus handling, and life was good.

But then it happened…

The Layout Flickering Problem

As I’m testing in a few browsers I noticed the mobile version of the header menu was flickering closed when resizing from the desktop to the mobile breakpoint. A quick debug later and I realized it was because of the transition CSS property I have set on the menu so it’ll slide out and fade in when opened.

Specifically, that transition is triggered when going from desktop to mobile because I’m visually hiding it once it gets to a point where it needs to be opened with a button. When those styles are applied, the transition animation triggers.

Before Example

Here’s a live example of the CSS animation flashing I’m talking about:

See the Pen Flashing Mobile Only Slide Out Menu Example by Steve Woodson (@stevenwoodson) on CodePen.

I didn’t want to remove the CSS transition, but I also didn’t want this weird animation flashing on resize, so what do I do?

The Prevent Animation Transition Solution

I wasn’t very happy with any of the solutions I found out there, they were some variation of:

really heavy-handed, like removing all transitions while the browser is resized
relied on fragile solutions like setTimeout
“just don’t use animation 🤷‍♀️”

So I got to work. The obvious problem was the transition applying when adding the mobile-only styles so there’s gotta be a way to prevent just that one use case, right? You bet there is, and it’s only two small changes!

Isolate `transition` Into a Unique Class

First, we need to isolate the transition separately from the styles that are applied when the menu is opened. In my case it was a new class called nav-opening:

.nav-opening {
  transition: all 0.5s ease;
}

Add & Remove the Transition

Second, we need to add the transition-only nav-opening class when adding the open class nav-opened. This happens on click of the mobile menu button:

this.el.classList.add('nav-opening');
this.el.classList.add('nav-opened');

And then we need to remove nav-opening when the animation is done closing, for this I turned to transitionend. That way I don’t have to guess with something like setTimeout, I trigger the removal of that class when I know the animation is done. Like this:

this.el.addEventListener('transitionend', this.setFocus.bind(this));

SlideOutMenu.prototype.setFocus = function (e) {
  if (e.target == this.el && e.propertyName == 'opacity') {
    const compStyles = window.getComputedStyle(this.el);
    if (compStyles.opacity == 1) {
      this.firstTabStop.focus();
    } else {
      this.openButton.focus();
      this.el.classList.remove('nav-opening');
    }
  }
};

The setFocus function here is checking that the animation transitionend happened on the element we care about, and only triggering for the opacity transition. The latter is just in case you have multiple transitions happening (opacity, left, visibility, etc.), you don’t want this running for all of them every time.

After Example

Here’s the same example with the above modifications applied, no more layout flickering on resize!

See the Pen Flashing Mobile Only Slide Out Menu Example by Steve Woodson (@stevenwoodson) on CodePen.

Wrapping Up

The code examples in CodePen were intentionally kept lean on styles and uses vanilla JavaScript in the hopes that you can more easily make use of it in your project. Be sure to copy from the After example, otherwise I wrote this whole blog post for nothing!

I wanted to also note that, while a bit too much for my use case, I do really like this Stop Animations During Window Resizing example that Chris worked up. If you have a lot going on transitions-wise this may be a cleaner solution for you than having to manage each piece individually.

A Step-by-Step Guide to Sorting Eleventy Global Data Files by Date

2023-02-02T13:26:55.000Z

In Eleventy, there’s a lot of helpful built in methods to manage content sorting by date. But if you wanted to manage your static (or API-driven?) data files by date then you’ve got a bit of manual work to do. In this post I’m going to share two date sorting options, automated by file last modified and manually via another data property. Let’s see some code!

The Setup

Both of the following sorting options assume that you have a data folder set up in your Eleventy codebase full of files of individual records. A data collection object of objects will then be made available to you at build time.

For example, with this folder structure:

_data
└─ widgets
   │  Algorithm Ace.json
   │  Binary Buddy.json
   │  Debugging Dynamo.json
   │  Function Friend.json
   │  Loop Leader.json
   │  Statement Strategist.json
   │  Syntax Savior.json

You’ll get something like the following collection when referencing widgets in your templates, where intro is some example data inside the individual JSON files:

{
  'Algorithm Ace': {
    intro: 'The expert in all things algorithm, helping you optimize your code like a pro.'
  },
  'Binary Buddy': {
    intro: 'The ultimate sidekick for your digital adventures, always there to convert and calculate.'
  },
  'Debugging Dynamo': {
    intro: 'Helping you solve your coding problems with lightning speed, making debugging a breeze.'
  },
  'Function Friend': {
    intro: 'A trusty organized companion whose motto is "A place for everything and everything in its place"'
  },
  'Loop Leader': {
    intro: 'The master at managing loops, ensuring your code runs smoothly and efficiently every time.'
  },
  'Statement Strategist': {
    intro: 'Fearlessly guiding you through even the toughest if/else statements'
  },
  'Syntax Savior': {
    intro: 'Never fear whether you need a color or a semicolon again!'
  }
}

Automated Date Sorting by Last Modified

I wanted to document this one for posterity because, alas, it ended up not being the solution we wanted for the problem we were solving. But it works great if you have a need to sort by modified date, less control but more automated. Here’s how it works

Create a filter in your 11ty config file at .eleventy.js like the following.

  eleventyConfig.addFilter("sortDataByDate", (obj) => {
    const fs = require("fs");
    const directory_name = "data/members";
    const filenames = fs.readdirSync(directory_name);
    const sorted = {};

    filenames
      .map((fileName) => ({
        name: fileName,
        time: fs.statSync(`${directory_name}/${fileName}`).mtime.getTime(),
      }))
      .sort((a, b) => b.time - a.time) // Latest first, swap a & b for opposite
      .map((file) => file.name.split(".")[0])
      .forEach((name) => (sorted[name] = obj[name]));
    return sorted;
  });

Note that the above code sorts by latest first, if you need to swap that then reverse a and b in line 12.

Manual Date Sorting by Data Property

This is going to take a bit more work, but you’ll have the most control over how the sorting happens. So if you don’t want the order of sorting to change as you change your files, this is the one for you.

First, you’ll need to add dates to the data in each file. The format is up to you, as long as it’s parsable by JavaScript. I’d recommend either a plain date like 2023-12-25 if you don’t need to get too granular, or date and time like `2023-12-25T12:30 if you also need time. You can get into seconds too, if you need.

Here’s an updated example of good ol’ Binary Buddy

{
  date: '2023-12-25T12:30',
  intro: 'The ultimate sidekick for your digital adventures, always there to convert and calculate.'
}

And here’s a new filter to add to the Eleventy config:

  /**
   * Sort by data files `date` field
   */
  eleventyConfig.addFilter("sortDataByDate", (obj) => {
    const sorted = {};
    Object.keys(obj)
      .sort((a, b) => {
        return obj[a].date > obj[b].date ? 1 : -1;
      })
      .forEach((name) => (sorted[name] = obj[name]));
    return sorted;
  });

Using the filtered data in your template

Regardless of whether you chose manual or automated date sorting, the resulting usage in a template is the same. Here’s an example of the for loop you’ll need, with the sorting filter applied to it:

<ul class="widgets">
{% for key, widget in widgets | sortDataByDate %}
  <li>{{ key }} - {{ widget.intro }}</li>
{% endfor %}
</ul>

That’s it! Now that list will be sorted by the last modified date of the files within your _data/widgets folder.

Some Background

Adding this at the end here for folks that are interested in how this came about, as I realize it’s a rather interesting use case. I heard about a11y-webring.club that Eric Bailey started and – of course – jumped at the chance to get this site added to it.

To get added, you have to start a pull request adding your details to a single members.json file in the 11ty-based site code. As you can imagine, once more than one person edited that file to add their details a merge conflict ensued. So I started this discussion to bring up the idea of file-based additions instead of everyone editing one file, which led to this PR.

In working through a solution to ensure folks were added chronologically, I came up with both methods outlined in this post. We ended up going with the latter.

Have you tackled date-based data sorting another way? We’d love to hear more perspectives and insights on this!

Getting Started in Technical Leadership

2023-01-18T01:08:59.000Z

I’ve been given the immense privilege of leading projects and teams of various sizes over the years, and an equally immense amount of grace as I inevitably messed something up in each of them. It’s part of the natural progression of shifting from an individual contributor to a leader.

I’m very much still learning myself, but I get asked “how do I get started” enough that I decided to draft this post to share a bit of what has helped me grow over the years. In addition to lived experiences, there are a whole lot of resources I’ve devoured that helped me frame my thoughts, get clarity, and armed me with templates that helped me make sense of this weird, hectic, beautiful, nebulous, and deeply rewarding responsibility.

I’ve split this up into the major concepts that I rely on day to day, at the bottom of each I’ve linked to several resources that have helped me in some way. They explain these topics with the depth they deserve, all have left a lasting impression.

The Many Types of Leadership

There’s countless types of leadership out there, and it is all going to depend on your industry and the size and structure of your organization. But I find it easier to think in terms of what is most often in focus, and for that I break it down into leadership of people, of projects, and of operations.

People Leadership

Coming from a technical background, our analytical brains are celebrated and our skills honed specifically to break down tasks in ways that computers can interpret. We don’t tend to be as naturally adept at doing the same for people, it takes a different kind of mindset and a whole lot more effort in collaboration and understanding.

However, there truly is no greater joy than those opportunities to help someone achieve something that’s important to them.

Project Leadership

Not necessarily project management, think more like technical team leads, architects, and staff engineers. These are technical leaders that are stepping out – at least in part – of the day to day code to do other things that support the team.

These are the people that translate project goals into technical milestones, make high level architectural decisions, helps with defining and grooming epics, creating tickets, identifying risk, and otherwise supports the rest of the engineering team.

Operational Leadership

These are the Engineering Managers, Developer Relations, and Director level roles that are less in the day to day leadership of individuals and projects but are still technical in nature.

This one is admittedly a bit broad in scope, I apologize to folks in any of these roles who may feel I’m over-generalizing.

How do I choose?

While many (most?) roles are likely going to span two or even all three of these types of leadership, it’s likely that one of them is going to be of higher interest to you. My suggestion would be to lean into that one initially.

Leadership duties can be emotionally draining, especially as you’re just starting out. Focusing on the parts that are of greater interest to you will hopefully give you some extra energy to offset some of the drain as you work on building your resiliency.

Standout Skills

In my attempt to maintain some semblance of brevity with this post, I’m focusing on the top three skills that I’ve turned to most in my technical leadership journey. For each I’ll give a quick what and why, some of my must have notes, and then recommended books that fundamentally changed how I approach that skill.

Organization

The more leadership you take on, the less things are going to come to you organized and ready to go. More often than not you’re going to be the one that becomes that organizing filter for others. Embracing nebulous requests, context switching, and acting as a mentor to others all require some level of personal and professional organization.

Organization Must Haves

Create a todo list that never leaves your side, offload as much as you can to it so you can focus on thinking instead of remembering
Documentation is a superpower, take some time to set up a place you can quickly turn to for realtime notes and use it – especially during meetings
Strive for context and clarity in everything
Follow up when you say you’re going to

Communication

Being a leader means a whole lot of communication, both in terms of clearly articulating what you’re trying to say as well as active listening when others are speaking. It takes a great deal of empathy and emotional intelligence to communicate effectively.

Communication Must Haves

Assume best intentions from everyone, start with empathy
Psychological safety is paramount to an effective and happy team
Listen with the intent to understand, not to respond
Learn how to recognize burnout and boredom in others, and how to recognize what drains and what recharges you too

Interpersonal Relationships

Building and maintaining relationships will take significantly more time, but it’s worthwhile and necessary groundwork. Those relationships are crucial to knowing what and when to delegate, how to manage challenging situations, and when to shift from mentor to coach and from coach to sponsor.

Interpersonal Relationship Must Haves

We are much more than the sum of our parts
Take all the blame, share all the praise, lead by example
Get comfortable with delegating and measuring productivity as a team rather than as an individual
Have a support network to turn to when you need advice, need to brainstorm something particularly tricky, and to get honest feedback

Additional Resources

Here’s a few more resources that really helped me that I couldn’t neatly fit into one of the skill categories above.

The Foundation of Technical Leadership by Brandon Gregory
The Three Speeds of Collaboration by Erin ‘Folletto’ Casali
‘Give Away Your Legos’ and Other Commandments for Scaling Startups by Molly Graham
Leadership: Practical Leadership Skills course by Chris Croft

What Would You Add?

As I had mentioned at the beginning of this post, I’m still learning and am very interested to hear your thoughts on the types of leadership, standout skills, and especially any additional resources you’d like to share. Use the links below to get a conversation started about it!

Thought Experiment – Greatest Superpower and Biggest Weakness

2023-01-02T12:38:19.000Z

It could be the nostalgic reflection that seems to come on at the end of the calendar year but I’m giving this some thought to see if it affects my goals going into 2023. I asked myself two questions:

What’s your Greatest Superpower and how are you going to leverage it?
What’s your Biggest Weakness and how are you going to work on it?

As I started to consider these questions, I realized that each of them could be answered differently based on the role areas of my life. This is something I’ve put a lot of thought into after reading books like The 7 Habits of Highly Effective People and Getting Things Done. Habit 2 in The 7 Habits has a whole section on identifying role areas of your life and the goals you want to accomplish in each area, I highly recommend giving it a try!

So I’ve decided to answer these questions from two different role perspectives that each loosely combine a few roles I try to be mindful of each week, personal and professional.

Greatest Superpower

Professional

My greatest superpower professionally has been patient persistence, I don’t easily give up on something I believe in and will keep chipping away at it until it’s done. For the most part, this has revolved around making progress towards something tangible. For example coding a web application, or completing the coursework and training to become CPACC certified.

This year, I plan on leveraging this superpower more for progress towards the important but less urgent intangibles to which I often don’t give enough attention. Thinking areas like thought leadership and outreach.

Personal

My greatest superpower personally has been organization, everything I want to accomplish is in a list on Todoist, long form notes are all compiled together in Evernote, and I generally am able to find what I need when I need it.

This year, I plan on leveraging this superpower to do more self reflection. I want to put more effort into figuring out what’s working for me and what isn’t. Finding a sustainable balance in my personal productivity is often rather elusive, I’m hopeful that this intentional reflection will help clarify what I’ve been missing.

Biggest Weakness

Professional

My biggest weakness professionally has been analysis paralysis, I tend to get pretty far into the weeds on things that – in the moment – seem to matter a great deal but end up not being so important in the grand scheme of things.

This year, I’m going to work on it by approaching challenges with a more structured plan. I’ve used many tools over the years that have helped me calm the paralysis but I’ve not been consistent and fall back into bad habits. Tools like pomodoro timers, time blocking, and OKRs all help clarify “what is important now?” but they all take a level of advance effort and planning that I need to work on.

Personal

My biggest weakness personally has been procrastination, I’m sure this is a familiar one to many but the aspect of it that I’m still trying to determine is if I’m really procrastinating too much or if I’ve set expectations on myself too high.

This year, I’m going to work on it by making sure I’m setting the right goals for the right time. I’ll continue to try following the mantra of “Less but Better”. When I’m planning out my week, I’m going to make sure to prioritize some down time to recharge and do things that I enjoy. Rest is vitally important to maintain the energy to tackle all my goals.

Final Thoughts

This was a really nice thought experiment, I’m feeling pretty optimistic about these plans and about the tools I’ve compiled to leverage my strengths and improve on my weaknesses. Here’s my action plan:

Prioritize progress in thought leadership and outreach.
More self reflection by way of weekly planning and daily journaling.
Structure the week ahead with more clarity and purpose, utilize pomodoro and time blocking when appropriate.
“Less but Better”. Prioritize some down time to recharge and do things that I enjoy.

If this sparked a similar thought experiment for you I’d really like to hear about it!

Pulling WordPress Content into Eleventy

2022-12-17T17:46:09.000Z

This is a follow up on my previous post Composable Architecture Powered by WordPress, focused specifically on how to pull content from WordPress via the built-in RESTful API into an Eleventy-based static site. If you still need to get WordPress set up and ready to act as a composable content source I’d recommend reading that one first.

Interested in deeper dives on using WordPress data in Eleventy? I have a follow up post about how to create a table of contents based on WordPress Rest API data as well as one on how to utilize WordPress categories and tags within Eleventy too!

Getting Started

There are some initial hurdles to pulling dynamic content into a static site generator like Eleventy, but the performance and portability of the end result is so worth it. I do believe – now that I’m a few posts in with this new setup – that this is going to be an easier authoring experience (WordPress GUI vs Markdown files) without sacrificing the user experience (more performant and portable static pages vs dynamic) I had curated previously.

Here’s an overview of the most critical parts transitioning from Markdown-based Eleventy collections to dynamic data pulled from WordPress, I go into further detail in dedicated sections below:

Pulling data using Fetch – This is the real bulk of the work, getting data dynamically from an outside source.
Computed Data rather than Collections – There’s some setup and changes needed to go from one content paradigm to the other. Including rebuilding the blog pages, updating the sitemap and meta, and some style modifications.
Triggering a new build on publish – Now that content is separated from the Eleventy codebase, we need a new way to trigger a rebuild when new content is published.

Pulling data using Fetch

To get all the benefits of a static site build, you need to collect and process as much content at build time as possible so that it can be served as static content. Sounds pretty straightforward, and it is when all your content is local files in your repo, but when you start loading dynamic data it gets a bit tricky.

By far the biggest paradigm shift is in moving from a collection of posts to computed data from a dynamic data source using a JavaScript data file. That necessitates pulling and processing all of the content at build time.

When pulling content from WordPress you need to be mindful of the 100 items per page limit imposed by the API. There are ways around this by resetting that limit but in my opinion that’s not necessary because we can accommodate in how we fetch the data instead. This makes our method of gathering all data more resilient to change, and we can reuse these concepts to pull content from other data sources that may not let you change the limits. That was the architectural decision behind getAllPosts and requestPosts in the code below, I’m using the former to coordinate pulling any number of pages of content in parallel using the latter method.

Finally, some code!

I’m going to start with the full source code of the JavaScript data file I’m using first, and then will explain each section/method within it afterwards and in the same order. This file is in my \site\_data directory saved as blogposts.js

const { AssetCache } = require("@11ty/eleventy-fetch");
const axios = require("axios");
const jsdom = require("jsdom");
const loadLanguages = require("prismjs/components/");
const Prism = require("prismjs");

const { JSDOM } = jsdom;
loadLanguages(["php"]);

// Config
const ITEMS_PER_REQUEST = 10;
const API_BASE = "https://mysite.com/wp-json/wp/v2/posts";

/**
 * Blog post API call by page
 *
 * @param {Int} page - Page number to fetch, defaults to 1
 * @return {Object} - Total, Pages, and full API data
 */
async function requestPosts(page = 1) {
  try {
    // https://developer.wordpress.org/rest-api/using-the-rest-api/pagination/
    const url = API_BASE;
    const params = {
      params: {
        page: page,
        per_page: ITEMS_PER_REQUEST,
        _embed: "wp:featuredmedia",
        order: "desc",
      },
    };
    const response = await axios.get(url, params);

    return {
      total: parseInt(response.headers["x-wp-total"], 10),
      pages: parseInt(response.headers["x-wp-totalpages"], 10),
      data: response.data,
    };
  } catch (err) {
    console.error("API not responding, no data returned", err);
    return {
      total: 0,
      pages: 0,
      data: [],
    };
  }
}

/**
 * Get all blog posts from the API
 * Use cached values if available, pull from API if not.
 *
 * @return {Array} - array of blog posts
 */
async function getAllPosts() {
  const cache = new AssetCache("blogposts");
  let requests = [];
  let apiData = [];

  if (cache.isCacheValid("2h")) {
    console.log("Using cached blogposts");
    return cache.getCachedValue();
  }

  // make first request and marge results with array
  const request = await requestPosts();
  console.log(
    "Using API blogposts, retrieving " +
      request.pages +
      " pages, " +
      request.total +
      " total posts."
  );
  apiData.push(...request.data);

  if (request.pages > 1) {
    // create additional requests
    for (let page = 2; page <= request.pages; page++) {
      const request = requestPosts(page);
      requests.push(request);
    }

    // resolve all additional requests in parallel
    const allResponses = await Promise.all(requests);
    allResponses.map((response) => {
      apiData.push(...response.data);
    });
  }

  // return data
  await cache.save(apiData, "json");
  return apiData;
}

/**
 * Clean up and convert the API response for our needs
 */
async function processPosts(blogposts) {
  return Promise.all(
    blogposts.map(async (post) => {
      // remove HTML-Tags from the excerpt for meta description
      let metaDescription = post.excerpt.rendered.replace(/(<([^>]+)>)/gi, "");
      metaDescription = metaDescription.replace("\n", "");

      // Code highlighting with Eleventy Syntax Highlighting
      // https://www.11ty.dev/docs/plugins/syntaxhighlight/
      let content = highlightCode(post.content.rendered);

      // Return only the data that is needed for the actual output
      return {
        content: content,
        date: post.date,
        modifiedDate: post.modified,
        excerpt: post.excerpt.rendered,
        formattedDate: new Date(post.date).toLocaleDateString("en-US", {
          year: "numeric",
          month: "long",
          day: "numeric",
        }),
        heroImageFull:
          post._embedded && post._embedded["wp:featuredmedia"].length > 0
            ? post._embedded["wp:featuredmedia"][0].media_details.sizes.full
                .source_url
            : null,
        heroImageThumb:
          post._embedded && post._embedded["wp:featuredmedia"].length > 0
            ? post._embedded["wp:featuredmedia"][0].media_details.sizes
                .medium_large.source_url
            : null,

        metaDescription: metaDescription,
        slug: post.slug,
        title: post.title.rendered,
      };
    })
  );
}

/**
 * Use Prism.js to highlight embedded code
 */
function highlightCode(content) {
  // since Prism.js works on the DOM,
  // we need an instance of JSDOM in the build
  const dom = new JSDOM(content);

  let preElements = dom.window.document.querySelectorAll("pre");

  // WordPress delivers a `code`-tag that is wrapped in a `pre`
  // the used language is specified by a CSS class
  if (preElements.length) {
    preElements.forEach((pre) => {
      let code = pre.querySelector("code");

      if (code) {
        // get specified language from css-classname
        let codeLanguage = "html";
        const preClass = pre.className;

        var matches = preClass.match(/language-(.*)/);
        if (matches != null) {
          codeLanguage = matches[1];
        }

        // save the language for later use in CSS
        pre.dataset.language = codeLanguage;

        // set grammar that prism should use for highlighting
        let prismGrammar = Prism.languages.html;

        if (
          codeLanguage === "javascript" ||
          codeLanguage === "js" ||
          codeLanguage === "json"
        ) {
          prismGrammar = Prism.languages.javascript;
        }

        if (codeLanguage === "css") {
          prismGrammar = Prism.languages.css;
        }

        if (codeLanguage === "php") {
          prismGrammar = Prism.languages.php;
        }
        // highlight code
        code.innerHTML = Prism.highlight(
          code.textContent,
          prismGrammar,
          codeLanguage
        );

        code.classList.add(`language-${codeLanguage}`);
      }
    });

    content = dom.window.document.body.innerHTML;
  }

  return content;
}

// export for 11ty
module.exports = async () => {
  const blogposts = await getAllPosts();
  const processedPosts = await processPosts(blogposts);
  return processedPosts;
};

I’m using:

Axios – a promise based HTTP client for the browser and node.js – to get the API data
AssetCache from Fetch to cache that response so I don’t have to hit my API quite as often especially when I’m working locally
Prism – a lightweight syntax highlighter built with modern web standards – to preprocess code block formatting
jsdom since Prism works on the DOM

I’m also setting some configuration to load the php Prism language, and setting some defaults for items I want per page and the API base URL.

`requestPosts`

I’ve split out requestPosts as its own method with a page parameter so I can gather individual pages of content at a time. This method will return the resulting data along with the total number of items (total) and the total number of pages (pages) for this post type.

This is where you can customize your request to perform any filtering, including extra embedded data, setting an order, etc. See Using the REST API for more details on these options. I’m setting the page based on the provided page parameter, setting per_page to the config value, and am requesting the wp:featuredmedia data so I can grab the featured image URLs I need.

`getAllPosts`

I also needed a method that could facilitate gathering multiple pages of post content and combining them together, hence getAllPosts. This checks the cache first before kicking off a new API request, if it’s cached that cached response is returned instead. Otherwise it runs one (or more) requestPosts calls in parallel to get all pages of content. The result is then cached and returned.

`processPosts`

Next, I do some light processing of the post content to simplify it for my needs here. This includes things like reducing post.excerpt.rendered to post.excerpt and drilling down into the wp:featuredmedia object to get the full and thumbnail versions of the featured image for each post. I’m also filtering the post content through highlightCode, more on that next.

`highlightCode`

I tend to have a good deal of code blocks in my posts and I want them to be at least somewhat readable with proper formatting and highlighting, that’s what this method does. highlightCode will:

run through the incoming content and find all <pre> tags that denotes a code block
for each code block identified it’ll look for a classname that starts with language- and will set the codeLanguage and prismGrammar accordingly and defaults to HTML.
triggers a Prism.highlight based on what was determined above.

This is where you’d need to add other languages you plan to support, there’s also a Prism autoloader that I opted against using but it may be helpful for you if you regularly post a lot of language types.

Recap

I need to gather all post content, in order to avoid per page limits I’m determining how many pages of content I need to pull and am running those API calls – one per page – in parallel. The results are then combined, processed, and then parsed for code block formatting, before being returned.

Computed Data rather than Collections

Now that we have the computed data ready to go, we now move onto rebuilding the blog section which includes the main paginated blog index as well as the layout of individual posts. Let’s dive right in!

Rebuilding the blog

Rebuilding the blog section of my Eleventy site to use computed data rather than a collection was surprisingly simple, here’s the major steps:

Remove the static folder of blog posts and accompanying images
Update/replace the main blog index page to use computed data
Update/replace the blog post template to use computed data
Other tie ins you may have, for example showing latest posts on the homepage

The biggest change for me was in shifting from a blogpost layout at /site/_includes/layouts/blogpost.nkj to a top level page at /site/blogpost.njk. this new top level page needed some additional front matter data to define where the data is coming from and what the permalink should be. Here’s what I ended up with:

---
layout: layouts/base.njk
templateClass: tmpl-post
pagination:
  data: blogposts
  size: 1
  alias: blogpost
permalink: blog/{{ blogpost.slug }}/
---

This is pulling all blog posts from the /site/_data/blogposts.js computed data and paginating it based on the blog post slug, effectively creating a unique page per post. Now I can go to https://stevenwoodson.com/blog/composable-architecture-powered-by-wordpress/ and see that post.

Sitemap and Metadata adjustments

It’s starting to look like a blog again! But there’s a few other items you’re likely going to need to address that may not be immediately apparent, following are what I had to address.

Meta tag tweaks in the <head> section

Now that we’re dealing with separate data for blog posts, we can’t rely on basic data like title, for example I had to swap from

<title>{{ title or metadata.title }}</title>
<meta name="description" content="{{ description or metadata.description }}">

<title>{{ title or blogpost.title | safe or metadata.title }}</title>
<meta name="description" content="{{ description or blogpost.metaDescription or metadata.description }}">

for the title and description. Note that I had to add that | safe after the blogpost.title because of the potential for HTML special characters. WordPress automatically changes quotes (“…”) into quotation marks (“…”) for example.

Changes to how the sitemap is generated

You can’t rely on collections.all to grab all pages of content anymore, for me I had to add the following to my sitemap in order to ensure the blog posts were still added:

{%- for blog in blogposts %}
  {% set absoluteUrl %}{{ metadata.url }}/blog/{{ blog.slug  }}{% endset %}
  <url>
    <loc>{{ absoluteUrl }}</loc>
    <lastmod>{{ blog.modifiedDate | htmlDateString }}</lastmod>
  </url>
{%- endfor %}

Updates to XML/JSON blog post feeds

Similarly, I had to rebuild the XML- and JSON-based feeds to use the new data. Following is my code update for the XML feed:

{%- for blog in blogposts %}
{% set absoluteUrl %}{{ metadata.url }}/blog/{{ blog.slug  }}{% endset %}
<entry>
	<title>{{ blog.title | safe }}</title>
	<link href="{{ absoluteUrl }}"/>
	<published>{{ blog.date }}</published>
	<updated>{{ blog.modifiedDate }}</updated>
	<id>{{ absoluteUrl }}</id>
    {% if blog.heroImageFull %}<image>{{ blog.heroImageFull }}</image>>{% endif %}
    {% if blog.excerpt %}<summary>{{ blog.excerpt | striptags(true) }}</summary>{% endif %}
	<content type="html">{{ blog.content | htmlToAbsoluteUrls(absoluteUrl) }}</content>
</entry>
{%- endfor %}

Here it is for the JSON version:

"items": [
	{%- for blog in blogposts %}
	{% set absoluteUrl %}{{ metadata.url }}/blog/{{ blog.slug  }}{% endset %}
	{
		"id": "{{ absoluteUrl }}",
		"url": "{{ absoluteUrl }}",
		"title": "{{ blog.title | safe }}",
		{% if blog.excerpt %}"summary": "{{ blog.excerpt | striptags(true) }}",{% endif %}
		{% if blog.heroImageFull %}"image": "{{ blog.heroImageFull }}",{% endif %}
		"content_html": {% if blog.content %}{{ blog.content | dump | safe }}{% else %}""{% endif %},
		"date_published": "{{ blog.date }}",
		"date_modified": "{{ blog.modifiedDate }}"
	}
	{%- if not loop.last -%}
	,
	{%- endif -%}
	{%- endfor %}
]

Rewrite rules added to .htaccess if your blog URLs are changing

This last one is dependent on the changes you’re making, in my case I moved from “/posts” to “/blog” as part of this switch so I made sure to add rewrite rules to 301 redirect users to the right location. Here’s my /site/static/.htaccess file you can start from, the first RewriteRule redirects the main blog page and the second redirects individual blog posts that used to be in subdirectories based on year and month:

Options +FollowSymLinks
RewriteEngine On
RewriteRule ^posts/$ /blog/ [R=301,NC,L]
RewriteRule ^posts/(.*)/(.*)/$ /blog/$2 [R=301,NC,L]

Structure & Style modifications

If you made use of any shortcodes specific to your blog posts, it’s probably a good idea to get rid of those to keep your code clean. For example I had ones for custom blockquotes and asides that are now no longer necessary.

I also found that WordPress wraps content in slightly different ways than I had with my CSS styles, so I needed to adjust my stylesheets to follow suit. This part is going to be rather dependent on how much of the baked-in styles you’re going to want to utilize from WordPress. It might be easiest to import everything wholesale but I opted to keep it cleaner by only defining what I knew for sure I’d need. Here’s my /site/assets/scss/layout/_wordpress.scss file in case you wanted to use that as a starting point for your own. I like having it separate in its own file as a reminder that this is CSS specifically for WordPress-provided content.

/* ==========================================================================
   CSS to support content generated by WordPress
   ========================================================================== */
.cp_embed_wrapper {
  margin: $global-spacing calc($global-spacing * -1);

  @media (min-width: $bp_small_desktop_min) {
    margin: $global-spacing calc($global-spacing-double * -1);
  }
}

/* WordPress Blockquote
   ========================================================================== */
.wp-block-quote {
  @extend .quote;

  cite {
    @extend .font-secondary;
    @extend .quote__attribution;
    display: block;
    font-style: normal;
    font-weight: $fw-bold;
    text-align: center;
  }

  p {
    @extend .quote__content;
  }
}

/* WordPress Column layouts
   ========================================================================== */
.wp-block-columns {
  display: flex;
  margin-bottom: 1.75em;
  box-sizing: border-box;
  flex-wrap: wrap !important;
  align-items: initial !important;
  /**
  * All Columns Alignment
  */
}
@media (min-width: 782px) {
  .wp-block-columns {
    flex-wrap: nowrap !important;
  }
}
.wp-block-columns.are-vertically-aligned-top {
  align-items: flex-start;
}
.wp-block-columns.are-vertically-aligned-center {
  align-items: center;
}
.wp-block-columns.are-vertically-aligned-bottom {
  align-items: flex-end;
}
@media (max-width: 781px) {
  .wp-block-columns:not(.is-not-stacked-on-mobile) > .wp-block-column {
    flex-basis: 100% !important;
  }
}
@media (min-width: 782px) {
  .wp-block-columns:not(.is-not-stacked-on-mobile) > .wp-block-column {
    flex-basis: 0;
    flex-grow: 1;
  }
  .wp-block-columns:not(.is-not-stacked-on-mobile)
    > .wp-block-column[style*="flex-basis"] {
    flex-grow: 0;
  }
}
.wp-block-columns.is-not-stacked-on-mobile {
  flex-wrap: nowrap !important;
}
.wp-block-columns.is-not-stacked-on-mobile > .wp-block-column {
  flex-basis: 0;
  flex-grow: 1;
}
.wp-block-columns.is-not-stacked-on-mobile
  > .wp-block-column[style*="flex-basis"] {
  flex-grow: 0;
}

:where(.wp-block-columns.has-background) {
  padding: 1.25em 2.375em;
}

.wp-block-column {
  flex-grow: 1;
  min-width: 0;
  word-break: break-word;
  overflow-wrap: break-word;
  /**
  * Individual Column Alignment
  */
}
.wp-block-column.is-vertically-aligned-top {
  align-self: flex-start;
}
.wp-block-column.is-vertically-aligned-center {
  align-self: center;
}
.wp-block-column.is-vertically-aligned-bottom {
  align-self: flex-end;
}
.wp-block-column.is-vertically-aligned-top,
.wp-block-column.is-vertically-aligned-center,
.wp-block-column.is-vertically-aligned-bottom {
  width: 100%;
}

Triggering a new build on publish

Last but certainly not least, I needed a way to trigger a fresh build as I published new content. I wanted to make this as easy as possible on myself so I put some time into figuring out how to automate these builds rather than having to do it manually every time. There are two parts to this, a build pipeline that gets triggered and a way to automatically trigger it.

CI/CD Build Pipelines

This is only going to work if you have some sort of build pipeline that you can tap into, if you’re manually triggering new static site builds within your Eleventy setup then you’ll have to continue to do that after publishing new content to your WordPress blog.

Otherwise, there are options for Github Actions, Azure Pipelines, and Bitbucket Pipelines but your unique setup is going to dictate how this works for you. Be sure, as part of this pipeline, that you’re removing the cache so it’s pulling fresh blog content each time. Here’s the NPM part of my pipeline:

rm -rf .cache/
npm ci
npm run build

Triggering a build on publish

After a bit of research I opted for the WP Webhooks WordPress plugin for this, it does a whole lot more than I need right now and is fairly straightforward. Once you’ve got it installed go to the settings and click on the “Send Data” menu item. From there you’ll get a list of available webhook triggers. The two I ended up sticking with were “Post updated” and “Post deleted”, I didn’t keep “Post created” because – as far as I could tell – “Post updated” triggered for that too so it wasn’t necessary.

For both of those triggers, I clicked on the “Add Webhook URL” button and added my unique CI/CD pipeline URL that triggers a new build.

Wrapping up

This post ended up being a lot longer than I anticipated and I hope it doesn’t make this process seem especially daunting, I went into a lot more detail than usual to try to help you avoid some of the mistakes that I made the first time around. I got so excited to launch this that I initially forgot about proper redirects, updating the sitemap, and all the XML/RSS feeds – essentially cutting the site off from feed readers, backlinks, and search engines. Don’t be like me!

If you give this a shot and run into any trouble (or just want to say thanks!) please do feel free to get in touch or start a conversation at one of the links below. Thanks!

SSH “Server Key Changed” Error and How to Fix It

2022-12-14T13:14:54.000Z

I’ve come across the following SSH server key error a handful of times while working within my local environments and every time I’ve had to look up what it is and how to get around it. So naturally I’ve decided to put the answer here so I have it easier the next time this happens.

The Error

Here’s the error I keep getting when trying to open up a local MySQL server using Navicat:

The server key has changed. Either you are under attack or the administrator changed the key.

Similar issues can happen in other programs that utilize SSH like PuTTY or FileZilla (via SFTP) but I’ve only experienced it in Navicat on a Mac recently so that’s what I’m detailing here. If you have more details I could add for other environments or programs, definitely get in touch using the links at the bottom of this post!

Why It’s Happening

When establishing an SSH connection, the server sends its public key to the client to authenticate that it is who it claims to be. When you accept the connection, this public key gets stored in your local ~/.ssh/known_hosts file (there’s also a system-wide file at /etc/ssh/known_hosts). The next time you attempt to connect to that same server, you’ll get a warning if the public key has changed from the one that was stored. This can happen for several valid reasons like server maintenance or IP/hostname changes, you get the warning because it could also be a potential security breach.

For my local server situation, I realized I have more than one server that refers to MySQL at localhost (127.0.0.1). Each server has it’s own unique public key so each time I connect to one and then attempt to connect to the other I get this error because the keys don’t match.

How to Fix It

A reminder to remain vigilant about security, especially if you’re experiencing this with a remote SSH connection. In my case since it’s a local development environment so I know I’m in the clear.
Open up ~/.ssh/known_hosts, each line in that file is an individual known host record. Find the one associated with the server you’re having issues with. If you’re having trouble finding the proper line to remove, the error you get will likely reference the public key that you can then search for in this file.
Remove the public key record that is causing the issue. For me, it’s the one that starts with 127.0.0.1.
A more robust solution to this is to change my local servers to point to unique IP addresses so this doesn’t keep happening, but that’s a problem for future Steve to deal with.

Making Intervention Image Ignore SVGs

2022-11-30T02:38:54.000Z

I recently started seeing a recurring exception pop up on one of my sites related to resizing and caching of images, after a bit of digging I realized what the underlying issue ended up being and figured I should document how I went about fixing it.

This particular site is built with Laravel using Intervention Image, Intervention Image Cache, and utilizing Intervention’s URL based image manipulation. Your mileage may vary if you’re using some other PHP framework but you should still be able to copy the solution _somewhere_ if not in the exact file I’m referencing. If you do I’d love to hear about it!

The Problem

The problem ended up being that some of the images I was trying to resize using Intervention were SVGs, and the default image manipulation Intervention uses is the GD library which only supports JPG, PNG, GIF, BMP or WebP files. When it encounters an SVG (or any other unsupported format) it fails.

Here’s the relevant part of the stack trace (emphasis added to the first line):

Intervention\Image\Exception\NotReadableException: Unsupported image type image/svg+xml. GD driver is only able to decode JPG, PNG, GIF, BMP or WebP files.
#48 /vendor/intervention/image/src/Intervention/Image/Gd/Decoder.php(75): Intervention\Image\Gd\Decoder::initFromPath
#47 /vendor/intervention/image/src/Intervention/Image/AbstractDecoder.php(344): Intervention\Image\AbstractDecoder::init
#46 /vendor/intervention/image/src/Intervention/Image/AbstractDriver.php(66): Intervention\Image\AbstractDriver::init
#45 /vendor/intervention/image/src/Intervention/Image/ImageManager.php(54): Intervention\Image\ImageManager::make
#44 [internal](0): call_user_func_array
#43 /vendor/intervention/imagecache/src/Intervention/Image/ImageCache.php(257): Intervention\Image\ImageCache::processCall
#42 /vendor/intervention/imagecache/src/Intervention/Image/ImageCache.php(273): Intervention\Image\ImageCache::process
#41 /vendor/intervention/imagecache/src/Intervention/Image/ImageCache.php(315): Intervention\Image\ImageCache::get
#40 /vendor/intervention/image/src/Intervention/Image/ImageManager.php(92): Intervention\Image\ImageManager::cache
#39 /vendor/intervention/imagecache/src/Intervention/Image/ImageCacheController.php(58): Intervention\Image\ImageCacheController::getImage
#38 /vendor/intervention/imagecache/src/Intervention/Image/ImageCacheController.php(31): Intervention\Image\ImageCacheController::getResponse

I can’t check for this Intervention\Image\Exception\NotReadableException exception using a try/catch because I’m using URL-based image manipulation. For example, attempting to load mysite.com/imagecache/small/logo.svg was what was throwing this NotReadableException error. There’s no code under my control triggering these image manipulations, it’s all vendor code through Intervention that handles these URLs.

The biggest reason I implemented resizing and caching was for performance reasons. So in my case, its okay for SVG images to not be programmatically resized because they’re already vector and (generally) are already way smaller in filesize.

So, how do I get Intervention Image to ignore SVGs?

The Solution

I’m sure many of you are gonna scroll to this section pretty quickly (I know I would’ve too if it was documented while I was searching) so I’m going to cut to the chase.

In Laravel there’s a global exception handler defined at app/Exceptions/Handler.php, it’s where all uncaught exceptions flow through. You may have had to add some code to this handler for app monitoring service integrations, I’m glad I did because otherwise I wouldn’t have even known about this error in the first place!

Here’s my addition to the render method in that app/Exceptions/Handler.php file:

    /**
     * Render an exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Throwable   $exception
     * @return \Illuminate\Http\Response
     */
    public function render($request, Throwable $exception)
    {
        /**
         * If the error class is `Intervention\Image\Exception\NotReadableException`, 
         * redirect the image URL to the original instead to avoid 500 errors on
         * the frontend. In particular, it has trouble with SVG images as the GD 
         * Library doesn't support anything other than JPG, PNG, GIF, BMP or WebP files.
         * 
         * This RegEx handles all Intervention Image filters defined ('/small/',
         * '/medium/', '/large/', for example) by isolating the URL path after
         * the configured Intervention URL Manipulation route (`imagecache` in 
         * this case) and replaces it with `/original/` which is a built in 
         * Intervention route that sends am HTTP response with the original image file.
         * 
         * @see https://image.intervention.io/v2/usage/url-manipulation
         */
        if ( get_class($exception) == "Intervention\Image\Exception\NotReadableException" ) {
            header('Location: '. preg_replace('/(imagecache\/[^\/]*\/)+/i', 'imagecache/original/', $request->getUri()) );
            exit();
        }

        return parent::render($request, $exception);
    }

The whole description of what this is doing is in the comment block, be sure to change imagecache in there to whatever you defined as your route in config/imagecache.php!

Composable Architecture Powered by WordPress

2022-11-01T13:32:49.000Z

It’s inevitable that – as a developer – I continue to change my mind and feel the urge to tinker again and again. Like a pendulum swinging back and forth I’ve noticed that my tendencies for choosing technologies also oscillates between complexity and simplicity. Always on the hunt for that happy medium where the developer, authoring, and user experiences are all as good as they can be. Inevitably, however, choices made to improve one of these three can become a hindrance on the others. Here’s my journey towards the next evolution of content generation for all my sites, leveraging composable architecture powered by WordPress.

A Focus on Simplicity

A couple years ago I switched this personal site of mine from an over-engineered monstrosity of custom code to a minimalist Eleventy build. It was a liberating experience being able to scrap so much and still have a functional site that was more performant and simple to maintain. After a couple years tinkering with it I came to this conclusion about the three experiences noted above:

Developer Experience – greatly improved due to less code, no databases, and a more straightforward organization
User Experience – greatly improved due to a redeveloped frontend for better accessibility, and 11ty being a static site generator it’s way more performant
Authoring Experience – more cumbersome with markdown files powering page content (including blog posts), no longer having an administration section to manage content from anywhere

Simplicity at What Cost?

As I alluded to in the Authoring Experience note above, the only problem I came across was that I had to be at my computer with an IDE open in order to draft new blog posts. “No problem” I thought, “I’m always at my computer anyway” and off I went.

Well, since that switch I’ve posted all of three new blog posts – just about one per year. I finally admitted to myself that it was due to the barrier of having to start a new markdown file, by the time I sat at my computer the post idea was either gone completely or I lost some of the more compelling aspects of it.

I started dreaming of a happy middle ground, one where I could still have the performance and simplicity of a static site but with the ease of an admin interface for adding content.

Growing Ambitions

Once I had it in my head that I wanted to make some changes for this site, of course I couldn’t help also considering the challenges I was having with content over at my accessibility auditing app Be Inclusive. I had switched to using Twill over there just over a year ago for similar reasons as I had for wanting a change on this site now. I need an easier authoring experience if I have any hope at keeping up with content creation, but from the start it felt like a bolted on solution that didn’t quite fit.

That got me wondering about content authoring for multiple sites, is there a way I could make something work long-term that’d be versatile enough for my shifting priorities across projects?

Enter Composable Architecture

That led to me turning to the concept of composable architecture, while my needs are relatively narrow focused (mostly blog and article-based content) it’s still the best term I can think of. It can be referred to as microservices architecture, modular architecture, and headless architecture. Us technologists aren’t that great at naming things…

Basically, I’m looking to offload the authoring of content to another service entirely and pulling that data as needed into any applications I want. This type of content architecture is very popular nowadays and for good reason, it’s fairly compelling to be able to split the code apart from the content and to have the latter available for multiple kinds of applications. Larger companies have used it effectively to share content across websites, native applications, social, and marketing (often paired with terms like omnichannel or digital transformation).

Choosing WordPress

After some fiddling with SaaS composable architecture content providers and trying a few options out, I settled on ol’ reliable WordPress for my content authoring needs. Here’s a few reasons why:

As a web developer, I’m fortunate enough to be able to do a bit of work upfront in order to self host and not incur fees for an out-of-the-box content provider. Many were great, I just couldn’t justify the cost.
WordPress comes pre-packaged with the ability to set up a multisite installation, so I can have content for this personal site, the Be Inclusive app, and any other sites I need to add into the future.
WordPress comes with a RESTful API already baked in too, so I can run API calls to gather the content I need. If my needs get to be more custom, I can also create my own RESTful API endpoints for full control.
With custom post types, I can also compartmentalize different types of content with a simple plugin. Leaving me with a versatile and extensible framework to grow into.

Getting Started

Setting this up was actually much simpler than I was anticipating, here’s a quick rundown:

I wanted to position the content somewhere reasonable for all my content needs, for me that ended up being as a separately hosted subdomain.
I installed WordPress at the subdomain, and then configured multisite using the instructions in this Create a Network WP support page.
I started a new “site” for both this personal site, and for the Be Inclusive app, from the Network Admin Sites Screen.
I disabled all themes, since this is going to be used solely as a content hub where sites will be pulling content from the API. As far as I know, you can’t have _no theme_ so I created a simplified one used mainly for redirecting traffic. See details and source code below under the “Redirect Theme” headline.
I added a few plugins that defined custom post types I need for my site content (besides standard blog posts). See details and source code below under the “Custom Post Types” headline.

Redirect Theme

I didn’t want folks using this subdomain to see the content I was creating, so the theme I created was called “Redirect” and has three files – functions.php, index.php, and style.css. All three files get added to wp-content/themes/redirect. You then set that as the active theme and you’re all set!

functions.php

I needed to be able to support post thumbnails, that’s really all this one is used for currently.

<?php

if ( ! function_exists( 'redirect_theme_support' ) ) :

	/**
	 * Sets up theme defaults and registers support for various WordPress features.
	 *
	 * @since Twenty Twenty-Two 1.0
	 *
	 * @return void
	 */
	function redirect_theme_support() {
		// Add support for block styles.
		add_theme_support( 'post-thumbnails' );
	}

endif;

add_action( 'after_setup_theme', 'redirect_theme_support' );

index.php

This is where we perform the redirect sitewide, the only downside is that you can’t use the “Preview” link when authoring.

<?php

// We want to run this site as a headless implementation, redirect to the site instead
header("Location: https://yourdomain.com/");

style.css

This is only here to give the meta information we need to see in the WordPress admin

/*
   Theme Name: Redirect
   Description: Redirects the front end to another domain
*/

Custom Post Types

I needed a couple custom post types defined for FAQ and Help Article content separate from the blog posts. Here’s an example of the plugin for FAQs, it’s a single file that gets added to wp-content/plugins

<?php

/**
 * FAQs custom post type plugin
 *
 * @wordpress-plugin
 * Plugin Name:       Custom Post Type - FAQ
 * Description:       Defines a custom FAQ post type for use in the admin editor
 * Version:           1.0.0
 * Author:            Steve Woodson
 * Author URI:        https://stevenwoodson.com/
 */

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
	die;
}


/**
 * Register the FAQ Custom Post Type.
 *
 * @see https://developer.wordpress.org/reference/functions/register_post_type
 */
function faq_post_type() {

	$labels = array(
		'name'           => _x( 'FAQs', 'Post Type General Name' ),
		'singular_name'  => _x( 'FAQ', 'Post Type Singular Name' ),
		'menu_name'      => __( 'FAQs' ),
		'name_admin_bar' => __( 'FAQs' ),
		'archives'       => __( 'FAQ Archives' ),
		'attributes'     => __( 'FAQ Attributes' ),
		'all_items'      => __( 'All FAQs' ),
		'add_new'        => __( 'Add New FAQ' ),
	);
	$args   = array(
		'label'               => __( 'FAQs' ),
		'description'         => __( 'A frequently asked question' ),
		'labels'              => $labels,
		'supports'            => array( 'title', 'editor' ),
		'hierarchical'        => false,
		'public'              => true,
		'publicly_queryable'  => true,
		'show_ui'             => true,
		'show_in_menu'        => true,
		'menu_position'       => 5,
		'exclude_from_search' => false,
		'searchable'          => true,
		'publicly_queryable'  => true,
		'rewrite'             => false,
		'capability_type'     => 'post',
		'show_in_rest'        => true,
		'rest_base'           => 'faqs',
		'has_archive'         => true,
		'taxonomies'          => ['category', 'post_tag']
	);
	register_post_type( 'faq', $args );
}
add_action( 'init', 'faq_post_type' );

Next Steps

So I’ve settled on a composable architecture setup, chose WordPress to facilitate it, and got it all set up as a content hub for all my growing content authoring needs. The next steps are:

Migrating any existing content into it. For me that was a mixture of copy/paste of content, uploading images to WordPress and replacing the pasted version with the uploaded version, and then making sure I reset the publish date to be the same as the original.
Pulling WordPress Posts into Laravel for Be Inclusive
Pulling WordPress Posts into Eleventy for this site
I’m also considering setting this up for Accessibility Solutions too, which is built using Nuxt

This post is getting longer than I planned! I’m going to split out how I approached getting content from WordPress into these sites as separate posts. Each site being built with different languages and frameworks I’m sure they’re all going to have their own surprises.

Following Up

Here are the deeper dives of using WordPress sourced data in other projects, more to come!

IAAP CPACC Exam Preparation and Reflection

2022-03-20T11:57:00.000Z

Happy to say I recently checked off a pretty large goal off my list by achieving my CPACC certification! I sat for the exam in early February 2022 and received notification of my passing it early in March.

Preparation

I participated in a CPACC study cohort at work, four of us worked through the IAAP CPACC Certification Preparation Course course together. I took fairly detailed bulleted notes that I referred back to often. The course is well organized and I got a lot of great detail out of it.
Prior to the cohort I had purchased a year-long license to that course twice and had trouble making the time to get through it on my own. Having others to talk to and hold me accountable was just the kick of motivation I needed, having study buddies is highly recommended!
I read through the whole Body of Knowledge (BoK), outline, and sample questions provided by Accessibility Association as well, outlined in the Prepare for the CPACC Exam section of this page.
In the weeks leading up to my exam, I created approximately 400 flash cards to study from. I ended up using Anki because I wanted an easy way to sync flash cards between devices so I could also study from my phone on the go. That worked out great because every opportunity I had to swipe through a few cards did add up – waiting for a haircut, in line at the grocery store, etc. I think the act of making the flash cards were as helpful as studying them, but if you’re interested in perusing mine here you go.
I had read a few horror stories about poor remote proctored exam experiences so I prepared a bedroom with minimal decoration far away from any noise or distraction. I had my personal computer set up with the Kryterion Sentinel program well in advance too as that is required for the exam. I didn’t bother even trying with my work laptop because of the warnings about avoiding firewalls and admin access requirement.
The exam is 100 multiple choice questions and you get 2 hours to complete, you’re able to have a notepad and pen and nothing else nearby when taking it remotely. That means no phones, devices, smart watches, etc.

Exam Reflection

I was stopped after my second question to take off and show my glasses and confirm I’m not using a notepad (the only other allowed thing in a remote proctored exam).
I took 1 hour 10 minutes, had 15 questions flagged for review after the first pass and probably agonized over these for longer than I should have. I was initially nervous about timing but now I would say the 2 hours they give was more than sufficient. I do appreciate that they offer more time to folks who feel they may need it as well.
It goes way deeper into applying guidelines to real-world situations and often provides at least two reasonable options and forces you to choose the BEST. Makes it very difficult to feel confident in my responses but I do think it does a good job pusing you to apply what you’ve learned rather than relying on memorization.
There were questions about the UN CRPD that I had no idea how to answer, and I felt fairly confident about that and the Marrakesh Treaty in particular. In hindsight I think maybe some extra due diligence reading through the linked materials available through the Deque course as well as the BoK would have helped, but it’s already quite a lot of information.
There was a very specific question about the Japanese Industrial Standard (JIS) X 8341 that I was unprepared for, definitely need to read even further into the international and domain specific laws if you want to get all of these right.
There was some wording that used “social” and “systemic” that led me to different answers than I would have put otherwise. Be mindful of the subtle context they’re adding because it could change your answer.
I studied a lot about the different types of color blindness, didn’t personally get any questions that went deep enough to know all the particular types and names but I’m still glad to have learned that extra information.
Before sitting for the exam I was under the impression that statistics were very important, only got a question about most pervasive type of disability and general percentage of people with disabilities stats.

Wrapping up

In all, I would say this was one of the most difficult exams I’ve had to prepare for mostly due to the sheer volume of information involved. But passing it and having all that important foundational knowledge made the hard work worthwhile in my opinion.

Implementing Dark Mode

2021-03-14T11:52:00.000Z

I love getting feedback from folks using the Be Inclusive app, my favorite feedback by far is actionable suggestions to make the app better. One such wonderful suggestion — and the topic of this post — that I’ve recently taken the time to implement is a Dark Mode theme. It was wrought with tons of twists and turns, and ended up taking a lot more thought and effort than I had anticipated at the start, so I’m documenting the process including initial setup, major necessary changes, and how I worked in support for both the browser native prefers-color-scheme as well as a toggle to choose between the default and dark mode on the user profile page. At the end of this post, I also have a list of resources that were extremely helpful in getting things set up. So let’s dive in!

Why Implement Dark Mode?

First things first, gotta ask the obvious question of why we should take the time to work in dark mode. Other than it being all the rage for at least a few years now, darker themes are also helpful for reducing eye strain and for people with low vision or photosensitive conditions. This alone was reason enough for me to set some time aside for this.

Getting Started

I had mentioned in the intro that I didn’t anticipate this taking very long, that’s because I had already spent a considerable amount of time setting up a color scheme fully defined in SCSS variables. Initially, I naively assumed that swapping these colors would get me most of the way there. Boy was I wrong, let’s take a look at all the issues I came across.

SCSS Variables

The first issue I realized I had was that SCSS variables wouldn’t let me swap colors without having basically all styles duplicated for dark and light modes, yikes. After a bit of research to allay my concerns about browser support, I added another layer to my stylesheet organization that set up CSS Custom Variables with a fallback to the light theme values for browsers that don’t support variables.

This ended up being just one additional SCSS file, but it also necessitated my changing all references to individual SCSS color variables into references to the new Custom Variable instead. As you can imagine, this affected essentially every single stylesheet but was still relatively straightforward. For example $c-primary changed to var(--c-primary).

Once the leg work was done to convert to custom variables, I then adjusted the colors to be more dark mode friendly, it took a lot of adjustments but the image below shows the final comparison between the same named colors between light and dark mode.

Itemized list of all major colors used across the site, left is light mode and the right is the finalized dark mode.

Visual Depth

I rely heavily on drop shadows to give the perception of depth across the whole site, turns out drop shadows for depth on dark mode looks either like absolute garbage or is not visible at all in the first place. Live and learn. After much consideration and reading (check the resources below for some great detailed case studies on depth in dark backgrounds), I replaced the drop shadows with increasingly lighter background colors for higher elevations.

Various levels of depth supported sitewide, left is the default with dropshadow and right is the dark mode relying more heavily on background colors instead.

This reliance on background color changes also led to a great deal more testing in two key areas:

Ensuring a minimum contrast between the background and the content is maintained since the background color is no longer static.
Check across multiple screens including mobile devices with brightness turned down to ensure that the differences in depth are perceptible enough.

Tweaks, Tweaks, Tweaks

Even with the intense adjustments made to the underlying colors, there were still a dozen or so situations where the light mode styling was just not suitable for a dark mode. Generally anywhere that relied on gradients and different colors to visually discern between elements fell flat. Either it became too busy, unreadable, or just plain visually unappealing.

Below is the evolution of alert styles, for example. The light mode version of errors, info, success, and warning alerts is on the left. Center is the same styled alerts with dark mode colors, obviously not ideal as the content won’t be readable on the right half and the gradients took on a weird alternating color that looked odd. After several tweaks, the best result I found was to remove the gradients altogether and instead increase the border thickness to still call attention to these important messages.

Three versions of alert styles, left is the light mode, center is dark mode before any tweaks (not great), right is after several iterations of tweaking to make them look okay on a darker bavckground.

Supporting `prefers-color-scheme` and User Preference

There were two important use cases I wanted to ensure I covered:

Make sure to adhere to prefers-color-scheme first, and especially if JavaScript is disabled.
Give users the option to choose separately from their current prefers-color-scheme setting.

As it turns out, supporting both these situations called for a bit of duplicative styling. Since they were both very important to me, I opted to figure out a way to keep the source code DRY even though the compiled styles have some duplication.

The Problem Supporting Both

To change colors and apply specific styles supporting dark mode with prefers-color-scheme, you can easily use an @media query like this:

--c-primary: #{$c-primary};

@media (prefers-color-scheme: dark) {
  --c-primary: #{$c-darkmode-primary};
}

This works great for that, but doesn’t support user-selected themes. There are many ways to keep track of users theme selections, I opted for storing in localStorage close to how it’s implemented here on this excellent CSS Tricks article. I have a small piece of JavaScript that then grabs that value from localStorage and adds a data attribute to the <html> element. With that setup, we can change styles based on user selection with the same basic code from above, like this:

--c-primary: #{$c-primary};

@media (prefers-color-scheme: dark) {
  --c-primary: #{$c-darkmode-primary};
}

Problem is, there’s no great way to do both of those together because one is a selector on a parent and the other is a media query. My solve was to place all dark mode specific styles in a dedicated _dark-mode.scss partial and then import that into both methods. Here’s a simplified example:

@media (prefers-color-scheme: dark) {
  html.no-js {
    @import "dark-mode";
  }
}

[data-color-scheme="dark"] {
  @import "dark-mode";
}

You might have noticed that the prefers-color-scheme snippet also has another selector inside checking specifically for html.no-js, this is because we don’t want these settings to override the users preference in the case where their operating system is set to dark mode but their preference for this site is for light mode. Since the user preference is applied with JavaScript, we fall back to prefers-color-scheme when JavaScript is disabled instead. Part of the small JavaScript snippet noted above also removes the no-js class from the HTML element as it adds the data-color-scheme attribute.

A bit of a bummer having the contents of _dark-mode.scss in my styles twice but it’s currently just a couple hundred lines of CSS coming in at less than 10kb before being minified, so the overall impact is small enough to be worthwhile for the additional support.

Avoiding Flash of Incorrect Theme (FOIT)

Also referred to as Flash of Default Theme (FODT), this is conceptually similar to the classic Flash of Unstyled Content (FOUC) but specifically referring to the potential for the default (light) theme to be displayed briefly while the user preference has yet to be defined.

With the above JavaScript solution in place I got everything I was looking for, the site theme starts with the prefers-color-scheme value and then persists the users selection when changed. Great! But in testing on some slower machines and mobile devices I started noticing that the lighter default theme was getting applied briefly before the dark mode kicked in. Especially not ideal for the very users I implemented this feature for, people with photosensitivity seeing a flash of the lighter theme first wouldn’t likely appreciate that.

So how’d I fix it? I broke one of the cardinal rules of JavaScript and placed this theme-based script in the <head> before the stylesheets. In this case I felt it was the right thing to do, it’s a very small amount of JavaScript and it completely removed the FOIT in subsequent tests.

Putting it All Together

Because I’ve got a lot going on in my stack for Be Inclusive that complicates the underlying implementation I’ve noted thusfar, I opted to create a bare-bones example for you in a CodePen. I tried to cram everything into one pen so there are some minor deviations, but I hope this gets the point across!

See the Pen Dark Mode Toggle by Steve Woodson (@stevenwoodson) on CodePen.

References

Alternatives for object-fit in IE11

2020-08-30T11:50:00.000Z

The problem

I recently came across an interesting issue where several prerequisites led to my turning to the object-fit CSS property to achieve the desired layout. Here were the prerequisites:

Support multiple image sizes based on browser size (srcset)
Image paths are coming from another location after pageload so CSS-based background images were not feasible
The image is used in the background under a gradient and some text.

Using object-fit alone would have worked great if it weren’t for the absolutely zero support in IE11, which happened to be a requirement for this particular project as well. The final solution ended up not being as straightforward as I had hoped so I’m documenting here hopeing that it helps someone else that came to the same crossroads.

First Attempt

To try to sidestep the use of object-fit for the background image, I opted instead to use absolute positioning and force a width of 100% like the example below. This mostly worked, but there were some cases on smaller breakpoints (depending on the image aspect ratio) that led to visible gaps in the container. I made the background cyan in this example so this gap is more noticeable.

See the Pen IE11 object-fit Alternative – before by Steve Woodson (@stevenwoodson) on CodePen.

Final Solution

In order to prevent gaps on mobile while also ensuring that IE11 desktop users had a reasonable experience, I finally opted to use a combination of the absolutely positioned method above and object-fit. I set the latter to kick in on mobile so I don’t have to try addressing these gaps individually like the revised example below.

See the Pen IE11 object-fit Alternative – after by Steve Woodson (@stevenwoodson) on CodePen.

Rationale

I believe the combination of absolutely positioning on desktop/tablet and object-fit on mobile was a worthwhile tradeoff between supporting an older browser while also ensuring modern browsers get the best experience possible. Going on the assumption that IE11 usage is rather low and that this number drops even lower at a mobile breakpoint size, I felt this was a reasonable solution.

Alternatives

Depending on your particular situation, here are a few other alternatives that could be pursued:

Use a background image instead of an <img>. If you don’t need to support multiple image sizes using srcset or if the paths to the images are static and could be supplied using CSS breakpoints, you could use a background image with background-size: cover.
Use Modernizr. If something like this is just one instance where you need to strike the balance between supporting IE11 while also building to modern standards, you could implement Modernizr to give you more control. Being able to check for support and have solutions for both situations is very powerful.
Defined aspect ratio. Finally, if the image you’re trying to implement needs to fit into a container that has a set aspect ratio and doesn’t need to fit to content placed inside, you could have the images sized to the same aspect ratio as the container. Then the absolute positioning would work across all breakpoints and object-fit wouldn’t be necessary.

References

Soft Skills: Productivity and Goal Setting

2019-01-23T11:48:00.000Z

I wrote an earlier post called “Improving Your Emotional Intelligence,” which introduced the topic of soft skills and practical advice on how to incorporate those skills into your life in measurable ways. In this second installment of soft-skills topics, we’ll explore some practical, high-level productivity techniques including the methodologies from “Getting Things Done,” “The Seven Habits of Highly Effective People,” and “Measure What Matters.”

With an initial investment in organization and goal setting, you can then focus on small periodic routines that help you improve daily productivity. This approach has worked wonders for me, I hope it can for you too!

Getting Started

Setup and Capturing

The single action that I could look back and say “that was where it all started,” was when I took to heart the concept of capturing everything that has my attention and to get it out of my head.

Use your mind to think about things, rather than think of them. You want to be adding value as you think about projects and people, not simply reminding yourself they exist.
David Allen, Getting Things Done

With a bit of time setting up Evernote for long-term notes and Todoist for managing tasks, I now have a quick and easy way to offload things that catch my attention. I’m able to mentally let these thoughts and tasks go safely in the knowledge that they’re in a place where I won’t forget about them, freeing me to focus on the task at hand. There are many note and task tools out there, including good old pen and paper, the ones you choose should fit your organization style and be as easy to use as possible. Any friction in this process will make it difficult to keep it up.

Weekly Review

In order to maintain the momentum and trust in the system I created, I perform a weekly review following the Getting Things Done (GTD) mantra of “get clear, get current, and get creative.” This podcast is a great overview of the GTD Weekly Review, setting aside some time every week to clear all inboxes, thoroughly review all outstanding tasks, and take a bit of time getting creative with new ideas. This weekly review strengthens my resolve to keep it up and reminds me that I can truly mentally let go of tasks once I’ve captured them.

Setting Goals

Personal Mission Statement

I find it’s a lot easier to find the motivation to be productive when I have a plan, beginning with the end in mind as Stephen Covey would say, and the best way to have a plan is to develop a personal mission statement. This is your long-term personal philosophy, what you want to be and to do and on the values or principles upon which being and doing are based. With this personal mission, you have the essence of your own proactivity.

A personal mission statement focuses on what you want to be and to do and on the values or principles upon which being and doing are based.
Stephen Covey, The 7 Habits

It’s well worth the effort to really think this through, there’s no right or wrong way to write your mission statement. A blank page can be pretty daunting, I found the Mission Statement Builder asked some thought-provoking questions and the examples were very helpful in seeing how others were organized.

After seeing how beneficial it was to share my mission statement with others privately as I was coaching them through this process, I decided to put it online publicly to help even more folks out. You can read my personal and professional mission statement here, I hope it helps you structure yours and I’d love to hear about your process when you do!

Long-Term Goals

With a method to stay organized and a deeper understanding of your guiding principles, you have a solid foundation for setting long-term goals. Make these big long-term goals; goals that really stretch you. And make sure they’re your goals, not the goals that you think you should have. They should be goals that get you excited about the future, goals that you can remind yourself of when you’re feeling your motivation starts to wane.

From these goals, identify a small handful of specific goals that are achievable within the next five years. Be sure to be as specific and laser-focused as possible, using present tense and deadline dates. Remember, “Vague goals produce vague results.”

Short-Term Goals

Now that you’ve identified your personal mission and specific long-term goals, it’s time to start planning for the week ahead with these goals in mind. To put first things first, start by identifying all your roles for the upcoming week. You have roles as an individual, a spouse, a parent, manager, developer, etc. These roles aren’t set in stone, just consider the week ahead.

With your roles defined and your long-term goals in mind, think of one or two important results you feel you should accomplish in each role during the next seven days. These are your goals for the week. For example one of my goals for this week in my Bounteous Resource role was to finish this blog post today. This relates to one of my specific goals to contribute as a resource to Bounteous with at least four blog posts and/or presentations this year. Which is a more specific goal based on one of my personal missions to “Be helpful and productive, a resource in more than just coding.”

Let’s Get to Work!

Alright! You’ve got a plan for the week and a cleared mind ready to get to it – now what? More often than not, the bigger items on our to-do lists require a good deal of focus. For knowledge workers like us, that’s especially true. Getting and maintaining focus can be extremely difficult, I’d say without a doubt that’s the hardest thing I struggle with daily. Here are some tips to help get yourself into that state of focus.

Listen to your body. When do you feel like you’re able to focus more easily? Strive to fit the focus tasks into these times and save the rest for more shallow concerns.

Understand that focus is painful at first. “To get into a focused mode, you have to push through the initial pain of contorting your mind to a single task.” – Soft Skills book

Control focus-busting impulses. Identify bad habits by reflecting on parts of your day you feel guilty about. Identify the cue that triggers it, the activity, and the reward. Next, try to figure out if there’s some other routine you can substitute for the one you’re currently doing for that habit. If possible, try to find something that you can do that will carry a similar reward or even the same type of reward. For example, I had recently identified that I would fire up Twitter when I’d start a code build on a larger project that I knew would take a few minutes to run, but many times I’d spend much longer than those few minutes catching up on new content. So my cue was starting a code build, the activity was opening Twitter, and the reward was the temporary reprieve of watching the build progress. Lately, I’ve replaced the activity with checking email. I usually have a very small number of messages built up so it doesn’t take more than a few minutes and I’m able to get something reasonably productive done rather than peeking at social media.

When you lose momentum, try a change of context. Like pausing on writing code to go take care of some code reviews. Get up and stretch your legs, go for a walk, and just get away from the screen for a bit. Set a very small goal and a time limit to complete, sometimes that setting and completing a to-do quickly can build your momentum back up. If nothing seems to be working, honestly assess your current situation and state of mind. Are you preoccupied with something else going on? Did you not get enough rest? Are you feeling overworked? This honest assessment can help you identify an underlying issue that needs to be dealt with. This tip led me to realize that I was trying to push myself too much in the evenings, I wasn’t allowing myself to rest enough to be fresh the next day. I honestly still struggle with this.

Avoid Burnout. Most commonly you’re hitting a wall, starting out with high interest that quickly wanes. Motivation starts low but rises as you make progress, but the slow pace of results wears at motivation until both interest and motivation are gone. Pushing past the wall is difficult but extremely rewarding. Set a schedule and hold yourself accountable.

Overworking is real, it’s horrible, and it should be avoided. Luckily at Bounteous, I’ve seen far less of it than any other company, places where people would brag about the number of hours they put in last week. Know your warning signs and have the personal integrity to back off a bit and let yourself rest.

Recap

For the TL;DR crowd, we’ve outlined three core principles that can open you up to more purposeful productivity:

Getting Started: Offload tasks and long-term notes to a trusted system and free your mind to think about things, rather than think of them.
Setting Goals: Create a personal mission statement that will inform your long-term goals; use these to come up with short-term goals that are then split into actionable items.
Get to work:With your upcoming week’s goals clearly defined, there’s nothing left to do but get started! Be mindful of momentum, and focus and listen to your body for the ideal times to get the most out of your day.

Resources

Books

If you’re looking to add to your reading list, I recommend the following books:

The 7 Habits of Highly Effective People by Stephen R. Covey
Getting Things Done by David Allen

Articles

For the web-friendly, bookmarkable article, here are a few options:

Effective Approaches for Working Deeply and Getting the Most Out of Each Day by Owen Berry
Leveling up from Nerd to Geek and Fast-Tracking Your Career by Brett Birschbach
Craft the Life You Want by Brett McKay
Staying Motivated by Kevin Cornell

Empathy in Web Accessibility

2018-05-17T11:47:00.000Z

Today we celebrate Global Accessibility Awareness Day with an exploration into how building empathy is fundamental to improving our approach to web accessibility. We’ve touched on cognitive empathy as part of an introduction to emotional intelligence, now we’re going to look at it from the perspective of accessibility. We’ll describe what kinds of empathy are needed, why it’s so important, and how to fit it into our everyday routines.

What Kind of Empathy is Needed?

First and foremost, we need strong empathy towards all users of the interfaces and applications we build regardless of handicap. We wouldn’t knowingly release a new feature that couldn’t be accessed by screen-reading software. The first step in ensuring that doesn’t happen is empathy towards users that rely on such software to navigate the web.

Following closely is empathy towards our clients, who also have the best intentions for the projects they entrust us to build. As the subject matter experts, we need to ensure we educate our clients on what it means to be accessible and to work as partners with them towards that goal.

Last but not least, we need to be empathetic towards each other. To all our fellow designers, developers, QA analysts, and the myriad others we work with every day because we’re all at different points in our journeys with web accessibility and can benefit from each other’s unique perspectives.

Why is Empathy Important to Accessibility?

Despite all the legislation and technical documentation urging for a more accessible Internet, the bottom line is it’s just the right thing to do. Understanding and awareness are two of the biggest roadblocks to getting product engineers to consider issues of accessibility. Awareness to include small course corrections at the early stages of a project could have a significant impact, and the kinds of empathy mentioned above can help build that awareness.

The Internet has the unique ability to connect people to a world they may otherwise have never known. Where people can experience a type of unrestricted liberty. Take Jessie Lorenz for example. She is executive director of the Independent Living Resource Center San Francisco. Having been blind since birth, she says, “A lot of people are afraid of the blind. Facebook lets me control the narrative and break down some of the stigmas and show people who I am.” We, as the builders of the web, have the power to connect these people!

How Do I Incorporate Empathy?

It’s one thing to read about empathy, but it’s important to move from education into action. The following steps outline ways to make accessibility part of our routine.

Experience It For Yourself

To build cognitive empathy for accessibility we need to understand how disabled users navigate the web. Two great places to start building that understanding is by reading about those with disabilities and attempting to experience the web as they do first-hand. The GAAD website has some great ideas you can try today and check out the Resources section below for some great books and online resources.

Become A Resource

As you strengthen your own empathy and understanding, you can take steps to become a resource to others in helping them on their journey. You don’t have to be an accessibility expert to be an advocate. Start by viewing your work with this new perspective and share this knowledge with your organization wherever you can. Consider the following tips:

Bring up accessibility concerns in meetings
Add an accessibility section to your company’s knowledge base
Host a lunch-and-learn or informational session (and record for future viewing!)
Build an ‘Accessibility Review’ stage into standard project templates
Start an #accessibility channel in your company’s messaging app (Slack, Hipchat, Yammer, etc.)

Make it Personal

In all situations mentioned thus far in this section, I find that it’s best to speak in terms of real-world situations because compliance doesn’t inspire action, people do. For example “this text color doesn’t meet WCAG 2.0 AA success criterion 1.4.3″ doesn’t have quite the same impact as “People with red-green color blindness will have trouble reading this text.” Both describe the same issue, but humanizing the issue makes all the difference.

In Closing

Accessibility is a large and multifaceted topic; it’s easy to become intimidated and overwhelmed. Remember the old adage that “Rome wasn’t built in a day,” small steps towards inclusion in our designs and code can still affect a large amount of people. And those small steps will become more and more clear as we develop our empathy for those that benefit from it.

Resources

Books

If you’re looking to add to your reading list, I recommend the following books:

A Web for Everyone: Designing Accessible User Experiences by Sarah Horton & Whitney Quesenbery
Design for Real Life by Sara Wachter-Boettcher and Eric Meyer
Practical Empathy by Indi Young

Articles

For the web-friendly, bookmarkable article, here are a few options:

What the Font are Vertical Rhythm and Modular Scale?

2018-03-26T11:33:00.000Z

Anyone that’s been in earshot of me has likely heard my ramblings about style guides, and a big part of that lately has been establishing a vertical rhythm and using a modular scale. But what the font am I talking about? In this article I’m going to walk you through why you should care about vertical rhythm and modular scale, define them, and finish up with a demonstration on how to integrate them into your next project.

Why Should I Care?

I wanted to start with this first because I feel it’s beneficial to understand the problem we’re trying to solve and the importance of both vertical rhythm and modular scale as parts of an overall solution. The whole reason this article is on both vertical rhythm and modular scale is because they both contribute to the visual harmony of a page. Vertical rhythm engages and guides the reader down the page, good vertical rhythm makes a layout more balanced and beautiful, and its content more readable. Modular scale provides resonant numbers using culturally relevant, historically pleasing ratios and encourages thoughtful repetition. Repetition breeds familiarity and reinforces a pattern that helps the user make sense of the content and layout. The Before example below is using the browser default font sizes and line heights, while the After example shows how this same content changed when applying the concepts I’m introducing below.

Before and After applying the concepts of vertical rhythm and modular scale

Vertical Rhythm

Vertical rhythm is the spacing and arrangement of text as the user descends the page. Vertical [ ↕ ] Rhythm [ a repeated pattern ]. It’s contributed by three factors; font size, line height, and vertical margins or padding. The basic unit of vertical space is line height – typically the line height of the body copy, as that will be the dominant content on any given page. To illustrate, I’m going to take examples from a recent site I’ve been working on. At the beginning of the project, we were provided designs that use Open Sans 15px font with a line height of 25px. So in this example below the vertical rhythm base unit would be 25px.

Vertical Rhythm Line Height example

With our base unit figured out, we need to now ensure that it’s maintained throughout the body copy. A common place to lose the rhythm is in the margin gaps set between block level elements. The default browser treatment of paragraphs is to insert a top and bottom margin of 1em and call it a day. This is not ideal if the rhythm is to be maintained, in our example below that’d mean the margins would be 15px instead of the 25px we need. It’s also worth noting that different fonts have different line heights built into them further causing visually inconsistent spacing. So margins and line heights need to be reset.

An example showing the gaps from margins between block level elements

This is common practice nowadays but I wanted to note that it’s always best to start things out on a level playing field, we need to make sure all vertical measurements including line height, padding, and margins are reset in a cross-browser compatible way. With this level playing field we’ll be able to then set these values as needed while maintaining the rhythm. I’ve used the Normalize.css, good ol’ Reset CSS from Eric Meyer, and even the following block with success. Whichever you choose will depend on your projects needs.

body,
pre,
div,
dl,
dt,
dd,
ul,
ol,
li,
h1,
h2,
h3,
h4,
h5,
h6,
form,
fieldset,
p,
blockquote,
th,
td {
  margin: 0;
  padding: 0;
}

With any site there are bound to be quite a few variations in text sizes for elements such as headlines and block quotes, all these differing text sizes should also take up multiples of the base unit. Continuing our example, that’d mean that every diversion from the paragraph text size should still take multiples of 25px. This is where the real fun begins, adjusting the line height and margin of these elements accordingly. We’ll dive into more details on this in the last section on how to integrate these concepts into your projects.

Illustration of multiple variations in text size

Modular Scale

Modular scale is a sequence of numbers that relate to one another in a meaningful way.

A modular scale, like a musical scale, is a prearranged set of harmonious proportions.
Robert Bringhurst

You start with a ratio and a number. Like Vertical Rhythm, the best way to ensure the effectiveness of your starting number is to use the body copy. Since this is setting the scale, we want to use its font size rather than its line height. Continuing with the same example from before, we’d use 15px as our base number. The ratio is more difficult to find, most common are the Golden Ratio (1.618) and Perfect Fourth (1.333). Both are culturally relevant; the former being a favorite in classical Greek and Renaissance math, architecture and art, and also found in nature; the latter was popular in early 20th-century music. One good rule of thumb is to consider how much typographical and layout variety you need. If you require steps for all six headers you’ll likely want to choose a ratio that allows for more subtlety between steps.

On the web, using a modular scale means choosing numbers from the scale for type sizes, line heights, line length (the width of a line of copy), margins, column width, and more.

With a ratio and number chosen, you can then multiply and divide them to get many resonant numbers. Below is a list of resonant numbers we’d get from using the 15px base and the “golden ratio” of 1:1.618 for the multiplication/division, I’m using the super helpful modularscale.com site to do these calculations for me and show me visually what the resulting sequence looks like.

An example of modular scale applied with the Golden Ratio from modularscale.com

What this did was take the starting number of 15 and

Multiply it by the golden ratio of 1.618 to get 24.27
Then it multiplied that by 1.618 to get 39.269, and so on
It also divided 15 by 1.618 to get 9.271
Then divided that by 1.618 to get 5.73 and so on

For comparison, below is the same 15px base and the “Perfect Fourth” ratio of 1 to 1.333 mentioned previously. As you can see, this ratio has mor subtlety between steps in the new set of calculations. Because the ratio is smaller, the steps between scale are closer together and more subtle.

An example of modular scale applied with the Perfect Fourth Ratio

You also have the option of defining a second base number and ratio to generate what’s called a double-stranded modular scale. This combines two sets of resonant numbers to give you more measurement options that fill in the gaps of the first scale. For the second base number, I’ve seen people use smaller caption text and larger numbers like the width of a column in the 12-column grid they’re implementing. So long as it’s an “important” number to the layout, there is no wrong answer. Here’s what adding a scond base of 95px (the size of one column in a 1140px wide layout) would look like.

An example of modular scale applied with the Golden Ratio and two base numbers

Great! Now we have a lot more options to work with!

History Lesson

The origin of establishing a typographic scale came as much from practical need as aesthetic judgement. Back when printing was done via letterpress, movable type was composed by hand for each page using cast metal sorts (upper right). It was impractical to manufacture and store whole character sets of each typeface in all possible sizes. Over time, typesetters settled on a usable range of sizes that worked harmoniously together.

Bonus – letters were organized and stored in small compartments of drawers (lower right) in a type case. Capital letters were traditionally stored in a separate drawer, or case placed above the case holding the other letters. This is the origin of the terms “upper case” and “lower case.”

Similarities and Differences

Now let’s quickly go over some similarities and differences between Vertical Rhythm and Modular Scale

As mentioned at the beginning, this article includes both vertical rhythm and modular scale because both are interrelated and contribute to the visual harmony of a page. Both vertical rhythm and modular scale most often use the primary body copy for their starting base numbers.

Where they differ most is in their application – vertical rhythm is only concerned with typography where modular scale provides a set of resonant numbers to use for typography, columns, line lengths, etc. Another key difference is how strict they’re intended to be followed. With vertical rhythm the more consistently you follow the pattern the better the rhythm will be. On the other hand, modular scale is more of a tool that can be improvised as necessary. The quote below is in reference to the math involved with Modular Scale.

Math is no substitute for an experienced designer’s eye, but it can provide both hints and constraints for decision making.
Tim Brown

Integration

Hopefully, by now I’ve convinced you that these methodologies are beneficial and worth your time to implement because I’ve got two bits of bad news.

First, a pervasive assumption is, “I can plug a couple of numbers into a generator and it all just works!” While there are online tools that help with a lot of the math and guesswork,there’s still going to be some trial and error. Every project is different, so
a perfectly viable solution for one isn’t necessarily going to fit for another.

Second, all materials I’ve found online related to these topics have come from the design or design-dev mindset where the person determining the modular scale and vertical rhythm is the one ultimately in charge of making those typographic decisions. In our case more often than not we’re handed designs that need to be converted from Sketch/PSD to web.

But there’s hope! On my most recent projects, I’ve successfully taken what was provided by a design team and was able to work them into a rhythm and scale that fit the guidelines mentioned thus far while also maintaining the integrity of the design. The trick is in getting the calculations as close as possible and setting up an example page that clearly illustrates the benefits before reaching out to the design team for the OK to move forward with the changes. In my experience, they’ve been even bigger type nerds than me and appreciated the extra effort involved.

Soft Skills: Improving Your Emotional Intelligence

2017-12-04T11:21:00.000Z

Who doesn’t want to make a difference in other people’s lives while also maintaining productivity? Proven soft skill techniques can make this seemingly impossible feat a reality! The term “Soft Skills” covers a broad spectrum of topics in interpersonal, communication, leadership, and personal skills. These are arguably the most important skills for your career, but by definition, they are also difficult to measure. This is the first in a series of articles meant to introduce you to some soft skill topics, providing some background information and practical advice on how to incorporate it into your life in measurable ways. In this article we’ll focus on introducing Emotional Intelligence (EI) before diving into the what, why, and how of perceiving, using, and managing emotion to improve your EI.

An Introduction

EI is a relatively new field of study (scientific articles on EI first began to appear in the early ’90s) that focuses on reasoning about emotions and the use of emotions to enhance thought. A model of EI pioneered by Dr. Daniel Goleman often referred to as the “Mixed Model” breaks EI down into the following five traits:

Self Awareness

Knowing what you’re feeling and using your feelings as a guide.
Self Management

Handling distressing emotions in effective ways, marshaling positive emotions, and aligning our actions with our passions.
Empathy

Discerning how someone else is feeling without them telling you in words.
Social Skill

Handling relationships and conflict, and being the type of person people enjoy being around.
Motivation

The drive to work towards your goals despite setbacks.

Goleman developed this model while covering neuroscience and psychology for the New York Times, based on the discovery that the emotional centers of the brain (a more primitive part that rose earlier in evolution), are involved in every thought and every decision.

I saw there was a critical mass of new understanding of how our brain is designed and what that means for understanding our emotional lives and the relationship to cognition, to thought.

Continuing his research, Goleman was able to interview and analyze over 500 corporations in search of what they’re looking for in different skill sets. He found that emotional intelligence was twice as important as IQ plus technical skill combined in distinguishing star performers from the average. In other words, learning how to perceive, use, and manage emotions helps develop a greater understanding of yourself and those around you. Using this as a foundation, we can focus on the what, why, and how of perceiving, using, and managing emotion.

Perceiving Emotions

For real influence we need to go from our here to their there.
How to Really Understand Someone Else’s Point of View

A big part of emotional perception is empathy, which itself is split into two major components. Emotional empathy is when someone’s emotion causes you similar feelings and memories. Cognitive empathy is the capacity to understand someone’s emotion and acknowledging that their reasoning and emotions as valid even if they differ from your own. We’re going to focus on the latter, on adopting an empathetic mindset that can be applied with the people you work with and the projects on which you work.

At first, most people seem to think that empathy is about showing warmth and kindness, or at least tolerance, toward another person. People think empathy is “to walk in someone else’s shoes,” to put themselves in that person’s place and embrace or excuse his behavior. This is not what empathy is about. Not exactly. Empathy is a noun—a thing. Empathy is an understanding you develop about another person. Empathizing is the use of that under-standing—an action.
Practical Empathy

Why?

Stereotypically, developers are portrayed as apathetic to the needs of the end user, but it has been my experience that this perception is at least partially due to circumstance. “You don’t know what you don’t know,” as the saying goes. If we’re not aware of the difficulties that users have with the applications we build, it’s not apathy, but rather lack of information that we fall prey to. In truth, web development lends itself very well to the empathetic. Since our jobs are centered around building things for others, empathy for these users can only make us better.

Remember that we’re talking about cognitive empathy rather than emotional: We’re trying to understand our users and use that understanding to improve what we’re building for them. Imagine developing a feature that you ensured remained accessible to those with disabilities, or a particularly timely and helpful user experience for a focus group. These could be the reason an end user sticks with your solutions over the competition’s. The understanding we gain from an empathetic mindset leads to a desire to help and makes the act of helping that much more rewarding. So developing an empathetic mindset isn’t just the right thing to do, it enhances your strategic thinking, your creative process, and transforms your ability to work together with others.

How?

Empathy is built by dropping into a certain mindset when the opportunity arises to gather knowledge. If someone you want to understand has the time, you take it. You drop into a neutral frame of mind, try to discover the deeper reasons behind what they are saying, and shut down your own thinking and emotions.

Empathy is not always about revelation, it consists of stuff you already know, but possibly didn’t pay a lot of attention to or maybe misremembered. The best part about listening is that you don’t have to be “a good facilitator” or a “skilled interviewer” to develop empathy. It’s more about just being yourself, in curiosity mode. Kids can do it. What it takes is the ability to let go of your own thoughts and really absorb what you hear.

Using Emotions

Happiness is a conscious choice, not an automatic response.
Mildred Barthel

First and foremost, you can’t go into this process with the intent of understanding someone else only to induce a change in their beliefs or behavior. The application of empathy that has impact on your work is to use it in support of someone. Empathy in support is being willing to acknowledge another person’s intent and work with it, morphing your own intent because of the empathy you developed for the other person.

Why?

Your improved understanding changes the way you see things and the way you speak to people. It raises your awareness and subconsciously shifts your own thinking and expanding your horizon.

How?

Here’s a list of ideas to keep in mind, because everyone loves a good short list!

Assume best intentions from those around you. If your understanding is negative, ask for clarification.
Show appreciation for even the small things people do for you.
Compliment people on their efforts: It’s easy to lose sight of the hard work involved.
Give of your time freely and be a resource.
When you feel the urge to respond with “well, actually,” first try to perceive the situation from their perspective. Force yourself to think “well, maybe…” instead. You may be surprised with how you finish that sentence.
Inject humor into your day-to-day interactions, within reason. Humor is associated with close interpersonal relationships and effective in reducing stress, which in turn enhances empathy.

Providing code review feedback is a good opportunity to effectively use emotion. An empathetic mindset along with the goodwill you’ve built using the suggestions thus far will help you adjust what you say and how you collaborate. Here’s another list of ideas to consider when providing feedback:

Take your time and ensure you understand the context of the code that’s being reviewed. You can’t provide meaningful feedback to code without proper context.
Provide positive feedback, too. No one benefits from only actionable and potentially negative review feedback.
Ask questions and be careful about suggesting specific solutions. Often your suggestions are taken at face value and implemented without further discussion, missing a potential learning opportunity and a better solution for both parties.
Be pragmatic. It’s okay to change your mindset based on the circumstances. For example, reviewing a time-sensitive small hotfix versus a brand new feature with far-reaching implications.

For more tips from the reviewee’s perspective, I highly recommend reading Brett Birschbach’s blog post Mentality Drives Technical Competency.

Managing Emotions

I’d like to end this article with some thoughts on managing emotions, both from a personal and an interpersonal perspective. I think Stephanie Noble had a great analogy for personal emotions when she described them as “Honored Guests” in your home. Identify the emotion, but don’t identify with the emotion. Explore this emotion-guest with loving curiosity. Allow it to come and go. Neither cling to it nor hold it hostage.

Always honor your guest, but if its company makes you uncomfortable, you can develop techniques to shorten the visits. Your guest has certain needs as well as certain information for you. The quicker you get to the needs/information exchange the less time you have to spend with an emotion. The more time you spend ‘suffering’ its company, the longer it will be before it leaves. So, cut to the chase.
Emotions as Honored Guests

Reactions during a knowledge-gathering, neutral-listening session are normal. Don’t feel embarrassed that you actually felt the emotion for a while first. You can’t prevent emotions from occurring, but you can recognize and then ignore them. When you have a reaction during a listening session, you don’t want to betray the fact to the speaker, because you do not want to cause them to have a reaction of their own, or let your reaction influence what they are telling you.

Recognizing your own reactions and assumptions—before they distract you—leaves your mind open to considering foreign possibilities. You will be able to recognize when you condemn an idea or a reaction, be able to stop yourself, and then be able to spend some time investigating it instead.
Practical Empathy

Resources

Books

If you’re looking to add to your reading list, I recommend the following books:

Design for Real Life by Sara Wachter-Boettcher and Eric Meyer
Emotional Intelligence 2.0 by Travis Bradberry & Jean Greaves
Losing Our Minds by Lucy Foulkes, PhD
Practical Empathy by Indi Young
Quiet: The Power of Introverts in a World That Can’t Stop Talking by Susan Cain

Articles

For the web-friendly, bookmarkable article, here are a few options:

Mentality Drives Technical Competency by Brett Birschbach
Human Abilities: Emotional Intelligence
How to Really Understand Someone Else’s Point of View by Mark Goulston and John Ullmen
Is Giving the Secret to Getting Ahead? by Art Streiber
Giving Better Code Reviews by Joel Kemp
You are Valued by Erica Joy
Daniel Goleman Explains Emotional Intelligence

The Four Levels of Mobile Browser Testing

2017-03-30T11:19:00.000Z

If there’s one item that doesn’t change from project to project, it’s timelines and budgets. So how do we manage the growing complexity of development and testing within the constraints of time and budget? In this article, I’m going to share some tips that will help you embrace the constraints of your projects while testing in mobile browsers.

Four Questions

We have sophisticated build tools, automated testing, design systems, and an unending onslaught of acronym-named projects at our disposal, but there’s no replacing manual testing. Planning out your testing strategy is crucial. But first, you need a general understanding of the project. Ask yourself:

What’s the lifecycle?
Is this going to be a one-off promotional project that will disappear in a couple months? An evergreen application critical to business success?
What’s the scale and complexity?
A small promotional site or a large multi-site system? It’s also a good idea to factor in the inherent complexity of a CMS if one will be used.
Who is your user?
Do you have any analytics or insight into your audience and browsing behavior? Ideally, what are your priority devices?
What’s the timeline and budget?
This sets the clearest constraints that we need to work within.

Depending on the answers to the questions above, I concede that compromises may be necessary, but you will still need to do some mobile browser testing. There’s no timeline short enough, no site simple enough, and no budget small enough to completely cut testing out of the process altogether. So let’s talk about the four levels of mobile browser testing and how each can fit into your workflow.

Four Levels

Level 1: Resizing a standard desktop browser

Trust me. In theory, it should work. Resizing a desktop browser down to mobile sizes is useful as a real-time sanity check during initial development. When you’re still working out your breakpoints and how page components will react to different screen sizes, it’s nice to see how it stacks across them all.

Pros – Quickest and easiest, readily available all the time.

Cons – Not indicative of the mobile user experience, browser bugs, or touch events.

Level 2: Desktop browser mobile emulators

Trust others; they say it should work. Chrome’s Dev Tools Device Toolbar and Firefox’s Responsive Design Mode are great options here, useful for deeper dives when special consideration is needed for mobile features like touch events. They also have advanced options to throttle connection speeds and simulate mobile device sensors like Geolocation and Device orientation.

Pros – Great for initial checks on basic mobile functionality, constraining to more realistic device screen sizes.

Cons – While better than simple browser resizing, this method still fails to reveal browser/device bugs and overall performance issues.

Level 3: iOS/Android simulator with stock browsers

Trust me (really this time). With actual device simulators, you’re able to test in a full mobile device environment in the native stock browser. Useful for identifying real mobile browser bugs and for getting a better sense for the page layout within the chrome of the device. Unfortunately, the list of browsers available is limited because you can’t install apps as you would normally on a physical device. On Android, you have access to the Android Browser, the Chromium Content Shell and Firefox. On iOS, you really only have access to mobile Safari. Special shout out to cloud-based emulator providers like BrowserStack and SauceLabs that offer further options that are not available or practical through OOTB simulators.

Pros – Using the actual mobile browser and surrounding chrome, better for finding layout bugs.

Cons – Limited browsers available for use in emulators, often takes a lot of system resources so not realistic to leave open all day, still not indicative of performance and touch optimization.

Level 4: Actual devices

The real deal. There is no comparison to testing on a physical device in your hands, it’s the only way to test mobile-specific details like touch target sizes and placement of controls. The time needed to test on all the mobile devices you have access to will increase as you continue to add devices. Luckily there are tools like GhostLab and Browser-Sync that can help speed up simultaneous testing on all devices.

Pros – Real performance and user experience of your project on a mobile device

Cons – A queue of devices that cover a reasonable subset of the mobile landscape can be expensive and time to set-up and test is higher.

Wrapping Up

Mobile browser testing is a delicate balance of the ideal test-everything-everywhere and the practicality of limited time and budget. Frame it in the scope of your project and use the strengths of the various levels defined above to your advantage.

Managing Multi-Tenant Component Styles

2016-06-22T11:07:00.000Z

In this article, we’re going to trace the path we took to accomplish a unique, cohesive design system for multiple sites within a single Content Management System (CMS) platform installation. While some of the details in the Workflow section are specific to the CMS platform we’re using (Adobe Experience Manager or AEM), the concepts are platform agnostic. Along with defining multitenancy and its structure, we’ll explore the importance of a dynamic style guide, the necessity of a theming tool for better collaboration, and the efficiencies we achieved by introducing both into our workflow.

Multitenancy

Multitenancy is a software architecture in which a single instance of a software application serves multiple tenants. As an analogy, that single instance is like an apartment building: Each ‘tenant’ in that building shares common infrastructure like electricity and gas, but are otherwise their own unique entity. From a CMS perspective, the software application, AEM in our case, powers multiple tenant websites that share components and image assets while each has its own structure, content, and assets.

The more that needs to be shared between sites, the more ideal it becomes to utilize a multi-tenant system. This shared structure allows us to rapidly create new feature-rich tenant sites, reinforces a common nomenclature across all teams, and reduces development effort.

Benefits and Pitfalls

There are several practical benefits to a multi-tenant system (including cost savings from a shared infrastructure), but let’s primarily focus on the design and development benefits. Designing for the responsive web is extremely difficult because there are no guarantees to the size and capability of the browser being used. This difficulty is amplified in a CMS platform because the content itself can no longer be guaranteed. Breaking content down into logical components shared between all tenants creates a common nomenclature shared between design and development. It’s easier to think and design in terms of the components that make up a page than trying to consider all possibilities at once. From a development perspective, building a component once and having that functionality available to all tenants is a powerful abstraction.

There are, however, inherent complexities involved when trying to design and build for a multi-tenant CMS. Developing a component that’s configurable enough and with a layout malleable enough to be useful across all tenants, present and future, is a tall order. The value of shared components is reduced if they need to be completely restyled for each tenant, so if efficiencies are to be gained in the design process, layout constraints must be set and standardized. The next two sections detail tools we’ve used to mitigate these complexities.

Dynamic Style Guide

A style guide is basically a table of contents for all the elements and components that make up a website, consolidates all the available options, and documents the visual language.

Why do we need one?

Having a style guide:

Ensures brand and code consistency;
Creates a reference that informs future additions and enhancements;
Helps with code reviews and QA;
Helps identify where styling attention is needed before it’s needed;
Reinforces a system of reusable modular components independent of pages.

What makes it dynamic?

A style guide can be made dynamic by including its code within the website codebase so they share the same stylesheets. Within a CMS environment we can build the style guide using the elements and components that it defines, making the style guide itself a dynamic representation of them. Any style or script changes are immediately reflected in both the site and the style guide, which further enhances its value to help with QA and maintain brand and code consistency.

A style guide is a great substitute for little to no available content when starting a new tenant site—it already includes all the same building blocks that are used to add content.

(So many great articles, tools, and references are available regarding the concepts of style guides and pattern libraries. I’d recommend checking out Website Style Guide Resources for more information.)

Theming Tool

With each tenant site that is added to a multi-tenant CMS, it becomes increasingly important to enforce as much consistency between them as possible. Unwilling to build cookie-cutter sites that all look the same, we developed the concept of standardized variables for colors and fonts and created a tool that could act as the bridge between design and development when building each new tenant site. The theming tool is a single HTML page that itemizes these variables and illustrates basic page elements in common situations (default, on a dark background, in a sidebar) and looks like a simplified, single page style guide.

Why do we need one?

This theming tool may appear to be an unnecessary overlap with the style guide, but there are two important reasons why it has to be separate. First, taking the tool out of the CMS means that it has no external dependencies and can be shared and updated with as little barrier as possible. This gives the design team free rein to incorporate new styles in this tool before development kicks off. Second, including only the site-wide standardized variables and basic page elements encourages a laser focus on nailing these fundamental details first. This is especially important because these fundamentals are the foundation that everything else, including all our custom components, is built on.

Our Workflow

We knew from the beginning that our AEM instance would be multi-tenant, so we started with a base content project that contains all shared components and their default styles and scripts. Each tenant site’s content project inherits and extends the styles and scripts of the base content project to support the branding and unique needs of the site. Because each site also needs to support i18n, the root of each tenant site contains language-based homepages with all other pages as their children.

Style Guide

This tenant site root is also an ideal location for the style guide because it’s unique to the site but does not need to be publicly accessible or specific to a language. This way, each site has its own implementation of the style guide to illustrate its unique styles and components.

Each site’s style guide is split into three sections that loosely match its LESS folder structure: Base, Layout, and Component. These sections are then further split into subpages:

The Base section itemizes all the color and font variables, as well as displays all the styles and variations of basic page elements, links, buttons, forms, images, and icons.
The Layout pages illustrate the grid system, header, footer, sidebar, and mobile navigation styles.
The Component section contains a page for each custom component that is developed and shared. These pages contain an instance of the component for each possible configuration variation. For example, we include an instance of a component with and without an optional background color or alternate content positioning. The ability to see all the possible ways a component can be rendered is extremely helpful in QA after code changes are made. It’s very easy to neglect styling an optional sub-headline that accounts for no images or missing calls to action.

Because the style guide content is not authored and updated for public viewing, it’s stored and deployed from the codebase. We do this both to maintain version control of the style guide content over time and to automatically keep developers’ local copies of the style guide in sync. With AEM, we use FileVault to sync any changes made in authoring back to the codebase so we are still able to use the authoring UI.

Theming Tool

The underlying goal of our multi-tenant AEM instance was to build a library of shared components and styles that each tenant site could benefit from while also maintaining a unique visual language and site structure. By the time we completed the second site, we had amassed dozens of shared components and the sites were so visually unique that it was difficult to tell they came from the same instance. Mission accomplished… sort of.

We received PSDs from the design team that outwardly appeared to mirror existing components and required little development effort to create, but in actuality, the minor functional and visual changes took considerably longer than expected. The time dedicated to these changes negated the time saved utilizing the shared components. We didn’t want to sacrifice the unique designs but needed a way to enforce some consistency.

To simplify common style changes, we started with the concept of standardized variables representing common colors and fonts, then introduced a default font size to which all set font sizes were made relative. The theming tool is a combination of these variables and basic page element styles. We were also able to use the same LESS stylesheets that each tenant site shares and left them largely unchanged so any modifications in the theming tool can easily be added back into the site.

Illustrating the changes to default typography in the theming tool after changing the font and color variables.

To combat the design limitations imposed by this standardization, we gave our components multiple configuration options that can change their appearance dramatically.

Process

To further expedite the process, we created a generic template tenant site and a script to generate a new maven project that copies it. This template site is complete with its own style guide and the standardized variables mentioned above.

When we start a new tenant site, we first share the theming tool with the design team. While they’re working on that, we use the script mentioned above to create the new site. Once the theming tool is ready, we copy the handful of stylesheets from it into this new site. With these two steps, we have a new site and its foundational styling complete and ready to preview in the style guide.

Results

While this is still very much an active work in progress, we’ve already noticed significant improvements in workflow and a reduction in development time. Because the style guide is synced with the codebase, as it was introduced into our workflow and populated with content, we started to have a common point of reference to use for code reviews and QA. Being able to test new components or code modifications here meant we didn’t have to spend additional time building a new page for testing. This was especially true in the early stages of a site when content authoring was just beginning.

The most striking improvement, however, can be seen when comparing the first tenant site developed with the theming tool and the one before it. Jira issues were reduced from 95 to eight and development time was reduced from three developers logging 710 hours collectively down to one developer logging 70 hours. That’s what we call efficient!

Thanks to Catrina Ahlbach, Brett Birschbach, Seth Dobbs, Robbie Forer, Paul Foster, Heather Gantz, Brian Langeland, Dan McClain, Ericka Seastrand, John Telford, Jamie Vonk, Brendan Walsh, and Leah Weyandt!

Off-canvas Menu + Fixed Navbar = Buggy iOS Safari

2013-10-04T11:04:00.000Z

While working on a responsive refresh of the Upshot website I came across some buggy behavior when mixing an off-canvas menu with a fixed position element on the page. I realize that fixed elements have had a history of bugginess in iOS and detailed articles have already been written. However, I hadn’t seen what was occurring for me discussed anywhere yet. In this case the fixed position element contained the “hamburger” menu link and the logo so we wanted that to stay fixed to the top of the page, but interacting with the off-canvas menu was problematic.

The Issue

In the screenshots to the right you can see what the page looks like on load (left image) and what it looked like occasionally after sliding the off-canvas menu out and back (right image). Sometimes it was fine and others were even worse than this screenshot, very random.

The Fix

To fix (so far it appears to be fixed in iOS7 Safari from my tests) I added a left: inherit; to the fixed menu. Easy fix but figuring it out took longer than I care to admit.

Avoiding Career Stagnation

2013-07-13T11:03:00.000Z

As a web developer the potential for career stagnation – feeling stuck, idle, and lacking progression – is higher than average. With technology constantly being improved and reinvented it’s amazingly easy to find yourself falling behind. I’ve felt this way several times over the years, to the point where I’ve started to also notice what led me out of the rut and back on track. I want to share some of these in the hope that it’ll help someone else out there, but also as a reminder to myself that conscious effort in these four areas goes a long way in avoiding stagnation.

Surround yourself with people you admire

The web design and development community is second to none, there are countless creatives out there that are genuine and extremely giving people. From lending a hand in IRC or forums to contributing to frameworks and open source code, in terms of resources and community we want for nothing.

Getting out to conferences, meeting people in your field, and if you’re lucky enough to work with people you admire is helpful on many levels but the key especially when considering this topic is that they keep that fire burning in you to take yourself to the next level.

I’ll admit I’m not the most proactive when it comes to going out to meetups, but I’m fortunate enough to work and chat with extraordinarily talented people that I turn to regularly for advice and conversation. Keeping up with the blogs and tweets of people I admire also helps. Find people that inspire you.

Work on projects you really care about

I know, this sounds obvious. But when you inevitably get sucked into the daily grind you can quickly lose sight of the forest for the trees. In my experience this has been most common in marketing and advertising projects. There have been times I’ve worked on one promotion after another meant to only live for a few months, all seemingly sharing the same concepts. It’s hard to stay motivated when you’re not challenging yourself and have no personal connection to the project.

So if you find the work you’re doing is just ‘paying the bills’ and doesn’t spark your creative interests then try injecting some yourself. Think about what could be changed/added that would make you more interested, chances are it’ll have the same effect in others – including the target audience.

You could also look into freelance or pro bono side work with organizations that you truly care about. This is great for getting outside the daily norm and is a perfect segue into the next topic…

Learn something new, change it up

Everyone remembers the excitement and curiosity they felt when they were just starting out, you can get that back by trying something outside your core competency. Designers can try learning more about programming and vice versa, get into project management, take on some UX, there’s always more out there to explore. I tried my hand at Ruby on Rails for a bit, and grew to not only appreciate it as a programming language but also saw myself incorporating more RoR organizational concepts into my PHP programming.

Take a break

All work and no play make Steve… something something. It’s scary how easy it is to burn yourself out, you can tell you’re burning out when you start to get frustrated easily and have a hard time concentrating. Take a break once in a while, go for a walk and have a good laugh, keep some hobbies, and for cryin’ out loud get enough sleep! It really does do wonders.

Filtering and Sorting a Table with PHP

2012-11-16T10:50:00.000Z

I had a friend ask me earlier this week if I knew of any resources that could point him in the right direction on how to create a PHP page of tabular data that had the ability to be both filtered and sorted. We both weren’t able to find anything suitably simplified so the underlying concepts are easily understandable. This article attempts to fill that gap.

Getting Started

I want to start out with a bit of a description of what the following code is meant to do and how it’s accomplished. This is — by design — an extremely bare-bones example, meant to be understood rather than duplicated verbatim. I went with a no JavaScript solution here but the act of filtering and sorting would likely feel quicker and more natural if JavaScript was used. If you want to follow along at home I’d suggest downloading this zip of all the (three) files necessary to get started. In that zip you’ll find a SQL file of the single table that holds all the data we’ll be using, an include with a single function where most of the magic happens, and a small index file to see the resulting magic unfold.

The Data

No tricks here, just some simple data to illustrate our purposes. The example is of a fictional three day seminar that has scheduled sessions at set times throughout the three days. Each session is meant for a specific skill level and covers one of several categories. It’s a straight SQL dump so you can use PHPMyAdmin/Navicat/etc. to create and upload the data so you can play along as you read. Here’s a couple sample rows of that data:

SESSION	DATE	START TIME	END TIME	LEVEL	CATEGORY
Cras faucibus velit in ligula feugiat eu consectetur arcu aliquam.	2013-06-11	12:00:00	13:30:00	Beginner	Healthcare
Donec et odio est, sed vulputate ligula.	2013-06-12	14:00:00	15:30:00	Beginner	Management

2013 Sessions

The Magic Function

This is where we get to the real meat ‘n’ potatoes, I’m introducing it early because it’s necessary to know how this works before discussing the next couple sections. The function below is located in the zip in the filtersort.inc.php file.

<?php

/**
 * Function to gather and return the appropriate results based on the filters received
 * @param type $filter - Array of filters to apply to the query
 * @param type $sort - Array of sorts to apply to the query
 * @return array $return - An array of filtered results
 */
function filtersort_query ( $filter = array(), $sort = array() ) {

	// Starter Variables
	$filter_sql_array = array();
	$return = array();
	$sort_sql_array = array();

	// Default Filter and Sort query additions, if the parameters are empty these will be the fallbacks that are used.
	$filter_sql = '';
	$sort_sql = 'category ASC';

	// Organize the filter additions to the query
	if ( isset($filter) && count( $filter ) > 0 ) {
		foreach ( $filter AS $filter_key => $filter_item ) {
			$filter_sql_array[] = '`'. $filter_key .'` = "'. $filter_item .'"';
		}
	}
	// Organize the sort additions to the query
	if ( isset($sort) && count( $sort ) > 0 ) {
		foreach ( $sort AS $sort_key => $sort_item ) {
			$sort_sql_array[] = '`'. $sort_key .'` '. $sort_item;
		}
	}

	// Build the query, add the filters and sorts to their proper places
	$query = mysql_query('
		SELECT
			*
		FROM
			sessions
			'. ( count( $filter_sql_array ) > 0 ? 'WHERE '. implode( ' AND ', $filter_sql_array ) : $filter_sql ) .
		 	( count( $sort_sql_array ) > 0 ? 'ORDER BY '. implode( ', ', $sort_sql_array ) : $sort_sql )
	);

	while ( $row = mysql_fetch_array($query, MYSQL_ASSOC) ) {
	    $return[] = $row;
	}

	return $return;
}

?>

This filtersort_query function accepts two associative arrays as parameters for filtering and sorting respectively. The $filter array keys are the table columns to filter and the values are the values we want to keep while filtering all others out. The $sort array keys are the table columns to sort and the values can be ‘ASC’ or ‘DESC’ to sort either in ascending or descending order. The function takes each of these arrays and converts each key/value pair into what will be their parts of the MySQL query.

Note: It’s recommended that if your table data is expected to be long that you also add some sort of pagination to the query/page to maintain a decent page load.

The query itself starts as a select of the whole table, so on initial page load all results are displayed. The filters and sorts are added if they’re present in the function parameters explained above. I’ve also added a default filter and sort in case you want to have some defaults to fall back on if the arrays are empty. These are the two variables called $filter_sql and $sort_sql.

Filtering

The filtering is done by a form located at the top of the index page, in my example they’re all select boxes but this could be extended to incorporate radio buttons and text inputs to suit your needs.

When the form is submitted, the index.php example will iterate through the returned form fields and set up an associative array for filtering. The array holds the same key/value pairs as is provided by the form and any with an empty value are weeded out and not sent.

// Starter Variables
$filter = array();
$sort = array();

// If we have GET variables, try to filter/sort
if ( isset($_GET) && count($_GET) > 0 ) {

	if ( isset($_GET['sort']) && strlen($_GET['sort']) > 0 ) {
		$sort[ $_GET['sort'] ] = 'ASC';
	}

	foreach ( $_GET AS $getkey => $getvar ) {
		if ( $getvar != "" ) {
			$filter[$getkey] = stripslashes($getvar);
		}
	}
	unset($filter['sort'], $filter['submit']);
}

Sorting

I believe that sorting is meant for after filters are set, as a way to more easily find the filtered result for which you’re searching. Going with this assumption, sorting takes the previously set key/values of the filters (explained above) and tacks on one more variable ‘sort’. This is all added to the href of a link tag on each of the headlines, so clicking on a headline sorts by that column. In this example I’m only sorting in ascending order so that’s the only thing added, if you wanted to add some sort of cycling between sorting in ascending and descending orders this would be where you’d put it. You can see the code that adds the sort to the Magic Query in lines 19-21 of the snippet directly above this section. This is where the order (set as ‘ASC’) is hard coded for all columns.

Putting it All Together

The table starts as a full list of all records in the table, selecting any value in the filter dropdowns filters to records that have only that value in that column, after submitting a filter you can click on a headline to sort the filtered data by that column in ascending order.

As mentioned above, adding some JavaScript to help with the filtering and sorting without page reload isn’t a bad idea. Pagination is another common addition especially for tables that can span thousands or more records. Also, building up the sort method might be helpful as well. For example adding the ability to sort by multiple columns and/or allowing for sorting in descending order. Finally, this could be updated to also include a keyword search, giving the end user even more flexibility on narrowing the results to find what they need. Sky’s the limit with an application like this, so I’d recommend spending some time determining your requirements early on and plan accordingly.

PHP Functions – Part 2

2012-10-11T10:49:00.000Z

Pad, Reduce, Chunk

I lumped these three functions together because I doubt I could count on one hand the number of times I’ve used any of them. Though once you understand what they do there are several applications for them that would make development cleaner if not also just plain easier. Here they are in the order I’m using them in the forthcoming example:

array_pad – Pads an array to the specified size with the specified value
array_reduce – Applies a function iteratively to the elements of the array so as to reduce the array to a single value.
array_chunk – Splits an array into chunks of the specified size

For a semi-useful example, we’re going to run through these three functions in a script that gathers the top 20 scores for display on a page. Find the full example at the bottom of this post, I’m going to explain all the parts individually first.

array_pad

// Pad the resulting array up to 20
$top_20 = array_pad( $db_result, 20, FALSE );

In our example we need to be able to display 20 results, it’s not much of a top 20 without 20 results right? So we’re going to use array_pad, this will fill the array with 20 items no matter the number of results. The first parameter is the array we need to pad (the $db_result in the example), second is the pad size (20 in the example), finally the third parameter is the value used to pad. Though not used here, we could also pad to the beginning of the array by making the second parameter a negative number, also the third parameter is not restricted to a boolean and can be a number, string, array, etc.

array_reduce

function r_scoresum ( $sum, $player ) {
	if ( $player !== FALSE ) {
		$sum += $player['score'];
	}
	return $sum;
}
// Gather total score of all players in the top 20
$top_20_total = array_reduce( $top_20, "r_scoresum" );

The two snippets above determine the sum of the returned scores using array_reduce. Array_reduce requires two parameters, the array to reduce and the name of a callback function to use to perform said reduction. There’s an optional third parameter called initial that is used at the beginning of the process or as a final result in case the array is empty. The function here makes sure the array item passed to the r_scoresum function is not set to FALSE (one of the padded items that are possibly added at the end of the array) before adding the score to the running total. $top_20_total will now contain the integer 1080898.

function r_output ( $output, $player ) { if ( $player === FALSE ) { $output .=
"\t".'
<li>[empty]</li>
'."\n"; } else { $output .= "\t".'
<li>
  <a href="#"
    >'. $player['name'] .' - '. number_format( $player['score'] ) .'</a
  >
</li>
'."\n"; } return $output; } // Set up a simple page of output for the top
players $top_20_output = array_reduce( $page, "r_output" );

This is another use of the array_reduce function, I set up a function r_output that takes the array items and produces some HTML I then use to display the data in a more readable format.

array_chunk

// Paginate the results
$top_20_paginated = array_chunk($top_20, 10);

array_chunk splits an array into a multidimensional array whose parent items contain arrays of the specified size. This is an example of a possible use of array_chunk, we’re using it as a simple method for paginating results. I wanted ten items per page so I set array_chunk with the array to chunk and the second parameter was set to 10. So now $top_20_paginated will contain an two-dimensional array with two values, each of these two values will themselves be an array of ten results each.

Full Example

Here’s the code in it’s entirety:

<?php
/**
 * Reduce the $player array to the sum of all returned scores
 * @param int $sum - Stored sum of all player scores
 * @param array $player - Array of individual player data
 * @return int - The total sum of all provided player scores
 */
function r_scoresum ( $sum, $player ) {
	if ( $player !== FALSE ) {
		$sum += $player['score'];
	}
	return $sum;
}
/**
 * Return a simple output of the players and their scores linking elsewhere
 * @param string $output
 * @param array $player - Array of individual player data
 * @return string - The ordered list items of the player scores
 */
function r_output ( $output, $player ) {
	if ( $player === FALSE ) {
		$output .= "\t".'<li>[empty]</li>'."\n";
	} else {
		$output .= "\t".'<li><a href="#">'. $player['name'] .' - '. number_format( $player['score'] ) .'</a></li>'."\n";
	}
	return $output;
}

// Faux Database results
$db_result = array(
	array( 'name' => 'Nelson Stryker', 'score' => 66581 ),
	array( 'name' => 'Fernando Cuneo', 'score' => 65897 ),
	array( 'name' => 'Darryl Gudger', 'score' => 64152 ),
	array( 'name' => 'Lance Secrist', 'score' => 63652 ),
	array( 'name' => 'Christian Rostad', 'score' => 62800 ),
	array( 'name' => 'Nelson Wantz', 'score' => 61896 ),
	array( 'name' => 'Dona Hirata', 'score' => 61688 ),
	array( 'name' => 'Marcia Kyser', 'score' => 60161 ),
	array( 'name' => 'Julio Nordberg', 'score' => 59093 ),
	array( 'name' => 'Maricela Gapinski', 'score' => 58780 ),
	array( 'name' => 'Adrienne Carreon', 'score' => 58702 ),
	array( 'name' => 'Nelson Rearick', 'score' => 58326 ),
	array( 'name' => 'Ericka Ursery', 'score' => 58101 ),
	array( 'name' => 'Earlene Carstens', 'score' => 57684 ),
	array( 'name' => 'Sofia Regal', 'score' => 57047 ),
	array( 'name' => 'Katy Unknow', 'score' => 56453 ),
	array( 'name' => 'Lance Weibel', 'score' => 55362 ),
	array( 'name' => 'Clare Deppen', 'score' => 54523 )
);
// Count of original database results
$db_result_count = count( $db_result );

// Pad the resulting array up to 20
$top_20 = array_pad( $db_result, 20, FALSE );
// Gather total score of all players in the top 20
$top_20_total = array_reduce( $top_20, "r_scoresum" );
// Paginate the results
$top_20_paginated = array_chunk($top_20, 10);

//After pagination is determined, set up an ordered list to display
foreach ( $top_20_paginated as $pagenum => $page ){
	// Set up a simple page of output for the top players
	$top_20_output = array_reduce( $page, "r_output" );
	echo '<h2>Page '. ( $pagenum + 1 ) .'</h2>'."\n".
		'<ol start="'. ( $pagenum * 10  + 1 ) .'">'."\n". $top_20_output .'</ol>'."\n";
}

// General stats
echo '
<dl>
	<dt>Sum of the Top 20 scores</dt><dd>'. number_format( $top_20_total ) .' points</dd>
	<dt>Average of the Top 20 scores</dt><dd>'. number_format( round( $top_20_total / $db_result_count ) ) .' points</dd>
</dl>';
?>

And the output will look like this:

<h2>Page 1</h2>
<ol start="1">
  <li><a href="#">Nelson Stryker - 66,581</a></li>
  <li><a href="#">Fernando Cuneo - 65,897</a></li>
  <li><a href="#">Darryl Gudger - 64,152</a></li>
  <li><a href="#">Lance Secrist - 63,652</a></li>
  <li><a href="#">Christian Rostad - 62,800</a></li>
  <li><a href="#">Nelson Wantz - 61,896</a></li>
  <li><a href="#">Dona Hirata - 61,688</a></li>
  <li><a href="#">Marcia Kyser - 60,161</a></li>
  <li><a href="#">Julio Nordberg - 59,093</a></li>
  <li><a href="#">Maricela Gapinski - 58,780</a></li>
</ol>
<h2>Page 2</h2>
<ol start="11">
  <li><a href="#">Adrienne Carreon - 58,702</a></li>
  <li><a href="#">Nelson Rearick - 58,326</a></li>
  <li><a href="#">Ericka Ursery - 58,101</a></li>
  <li><a href="#">Earlene Carstens - 57,684</a></li>
  <li><a href="#">Sofia Regal - 57,047</a></li>
  <li><a href="#">Katy Unknow - 56,453</a></li>
  <li><a href="#">Lance Weibel - 55,362</a></li>
  <li><a href="#">Clare Deppen - 54,523</a></li>
  <li>[empty]</li>
  <li>[empty]</li>
</ol>

<dl>
  <dt>Sum of the Top 20 scores</dt>
  <dd>1,080,898 points</dd>
  <dt>Average of the Top 20 scores</dt>
  <dd>60,050 points</dd>
</dl>

Recharge & Release

2012-10-07T10:46:00.000Z

I find that I go through productivity phases, generally the two I am most cognizant of are what I can loosely refer to as recharge and release.

When recharging I feel I read a lot more than usual. I catch up on a backlog of articles I flagged, dig into books I had been meaning to read, and generally find outside inspiration from various sources. I sleep and even eat more. The result is a focused sense of creativity and determination in my own work. I get the urge to update my website, portfolio, and blog. I dust off personal projects that had slipped away from me and give them another chance. I sleep and eat less and typically can focus on tasks longer. Leading inevitably back to the beginning.

I suppose that makes sense, it’s pretty easy to burn oneself out by working too much and a person can only read and rest so much before the urge to create flares up again.

No Shame In Looking It Up

2012-09-27T10:44:00.000Z

Web developers are tasked with remembering several different programming languages in order to effectively get the job done. HTML, CSS, & Javascript are the big three of course, but there are others such as Coffeescript, SCSS, XML that help workflow and facilitate tasks. Backend devs also commonly need to know scripting languages (e.g. PHP, Ruby on Rails, .NET) and how to interact with a database (e.g. SQLite, MSSQL, MySQL). Beyond the base programming languages there’s no shortage of frameworks and plugins available to increase organization and assist in common tasks, jQuery and CodeIgniter being two notable examples. Though, with great power comes great responsibility – as the saying goes.

Each framework and plugin has their own documentation and structure that needs to be reviewed and retained. On top of this foundation of programming language and frameworks knowledge, there are other principles and methodologies to also keep in mind:

architectural patterns e.g. REST
programming principles e.g. DRY
workflow methodologies e.g. Agile and Lean
semantic & accessibility best practices

In this veritable acronym stew of programming & process, I wholeheartedly believe that there’s no shame in looking it up. There’s simply too much out there to interact with and utilize to be able to retain it all. Need to find a string in a string but don’t recall which PHP string function to use, go ahead and check it out! I think it’s far more important for us to grasp what these languages, frameworks, and plugins are capable of before we attempt to memorize all the available methods and their syntax. You could always look up how to write a jQuery selector for all <input> elements with a name attribute starting with “quarterly” (it’s [name ^=”quarterly”] by the way), having the knowledge that such a selector is available is an excellent start.

PHP Functions – Part 1

2012-09-06T10:41:00.000Z

I’ve been working with PHP for several years, dare I say a decade at this point, and I’m still surprised at functions I’ve never or rarely used. In an attempt to share in my delight of discovering these gems and hopefully enlighten others to some very helpful functions, I’m going to try to start a series of quick articles explaining various PHP functions. This first part will go over four very inter-related array functions.

Pop, Push, Shift, Unshift

Gotta love the naming conventions sometimes, these make me think of a Daft Punk song. Anyways, these are four array functions that I like to keep lumped together in my mind as they do very similar tasks. Here they are in the order I’m using them in the forthcoming example:

array_shift – Takes the first variable off the array and returns it
array_pop – Takes the last variable off the array and returns it
array_push – Adds a variable onto the end of the array and returns the array count
array_unshift – Adds a variable onto the beginning of the array and returns the array count

One thing worth noting that I find helps me remember these functions without having to look them up constantly. The first pair (array_pop and array_shift) and the second pair (array_push and array_unshift) do the same things, the only distinctions are whether it’s targeting the beginning or the end of the array and the returned value. Function array_pop and array_shift return the variable that was removed from the array, array_push and array_unshift return the array count after the addition was made.

Here’s an example that uses all four functions mentioned here to modify an array.

$input = array(0, 1, 2, 3, 4, 5);

echo '
  <strong>Starting Array</strong>
  <code>$input = array (' . implode(', ', $input ) . ')</code>
';

$result = array_shift($input);

echo '
  <strong>Using array_shift</strong> - <em>Takes the first variable off the array and returns it</em>
  <code>$result = array_shift($input);</code>
  <strong>Result:</strong>
  <code>$input = array (' . implode(', ', $input ) . ')</code>
  <code>$result = ' . $result . '</code>
';

$result = array_pop($input);

echo '
  <strong>Using array_pop</strong> - <em>Takes the last variable off the array and returns it</em>
  <code>$result = array_pop($input);</code>
  <strong>Result:</strong>
  <code>$input = array (' . implode(', ', $input ) . ')</code>
  <code>$result = ' . $result . '</code>
';

$result = array_push($input, 5);

echo '
  <strong>Using array_push</strong> - <em>Adds a variable onto the end of the array and returns the count of the array</em>
  <code>$result = array_push($input, 5);</code>
  <strong>Result:</strong>
  <code>$input = array (' . implode(', ', $input ) . ')</code>
  <code>$result = ' . $result . '</code>';

$result = array_unshift($input, 0);

echo '
  <strong>Using array_unshift</strong> - <em>Adds a variable onto the beginning of the array and returns the count of the array</em>
  <code>$result = array_unshift($input, 0);</code>
  <strong>Result:</strong>
  <code>$input = array (' . implode(', ', $input ) . ')</code>
  <code>$result = ' . $result . '</code>
';
?>

This code returns:

Starting Array
$input = array (0, 1, 2, 3, 4, 5)

Using array_shift – Takes the first variable off the array and returns it
$result = array_shift($input);
Result:
$input = array (1, 2, 3, 4, 5)
$result = 0

Using array_pop – Takes the last variable off the array and returns it
$result = array_pop($input);
Result:
$input = array (1, 2, 3, 4)
$result = 5

Using array_push – Adds a variable onto the end of the array and returns the count of the array
$result = array_push($input, 5);
Result:
$input = array (1, 2, 3, 4, 5)
$result = 5

Using array_unshift – Adds a variable onto the beginning of the array and returns the count of the array
$result = array_unshift($input, 0);
Result:
$input = array (0, 1, 2, 3, 4, 5)
$result = 6

A bit cyclical I admit, but it gets the point across. We removed the first then last values from the array and then turned around and added them back in. So we end up with the same array values that we started with.

Stay tuned, in Part 2 I’ll be talking about a few more underutilized array functions.

Apache 2GB file limit

2011-02-16T13:40:00.000Z

Just came across a new issue I hadn’t dealt with before, apparently once a file (in my case a very large error_log file) reaches 2GB or 2,147,483,647 bytes it can’t work with the file anymore. In this case the system couldn’t write to the error log and threw an Internal Server Error. I didn’t realize what the issue was until I went to download the error log to diagnose and found out it was exactly 2GB. Lo and behold as soon as I renamed it and started a new log the site worked fine again.

After some research I found it’s due to Apache 1.3.x or 2.0.x 32bit register limits. Apache 2.2.x changed it to a 64bit register so that limit is no longer an issue for people running newer versions.

Anyone else have experiences dealing with this limit?

URI vs URL? Think Scotch vs Whisky

2010-12-02T13:37:00.000Z

For the longest time, I’ve been unconsciously transposing URI and URL (with the occasional sprinkling of “web address”) in conversations and correspondences without ever really considering that they are abbreviations for two different things. That is until I decided to finally read up on these confounding abbreviations and got the proper info on the real difference between URL and URI. So you wanna know what the difference is?

After all that build up I’m sad to say there really isn’t much of a difference. URI vs URL is actually very similar to Whisky vs Scotch – how’s that for a memory jogging association? Any good bartender that knows their jigger from their jeroboam will tell you that Scotch is really just a whisky that was produced in Scotland. A URL is actually a URI that identifies the location of the resource. For another explanation, A URL is a URI but a URI is not necessarily a URL just like scotch is always a whiskey but a whiskey is not necessarily scotch.

Another little tidbit I discovered while researching this is that there’s another abbreviation called URN that identifies a resource by name in a particular namespace and is also a URI. So for example 1400082471 is the ISBN URN of the book Dreaming in Code.

So to recap, a URL is a URI that identifies a location (hence the last word of the abbreviation being location) and URN is a URI that identifies a name (hence the last word of the abbreviation being name). For all you right brain visual learners out there, check out the diagram to the left as a reminder.

Not really the most groundbreaking of topics but I thought it was cool to know the difference (what little difference there is at least) especially considering it’s a part of what I do on a daily basis. Hopefully someone out there feels the same.

Website Performance – gZipping & Extended Expirations

2008-07-06T13:29:00.000Z

With a mixture of a few techniques added to the .htaccess or httpd.conf files, you can reduce the pageload and the bandwith usage of your website fairly easily. In the examples below i’m referring to expressions for addition to .htaccess, the http.conf file may be structured differently to do the same things. I’m setting this up in a standard LAMP setup with Apache 2 and PHP5. It will also wirk with versions of PHP4 but not all the following items work in Apache 1.3.

Apache Module mod_expires

The first thing to do is extend the amount of time text, images, css, flash and javascript are stored in the users cache. To turn this on we need mod_expires to be active, we then use the expression ExpiresActive On. We then set a default expiry for everything which is generally set to 6 hours (300 seconds) from the time of access. This is set using the expression ExpiresDefault A300. Alternatively we can set it to expire a set amount of time since the file was last modified using M instead of A as in ExpiresDefault M300. Then, if need be, we can take a more granular approach to expiration times by setting expiration by filetype using the expression ExpiresByType _[mimetype][a|m][seconds]_. So to set GIF images to expire one week from time of access we’d use ExpiresByType image/gif A604800.

FileETag Directive

The FileETag directive configures the file attributes that are used to create the ETag (entity tag) response header field when the document is based on a file. Because we’re manually setting expirations we don’t require these headers so it’s easiest to just turn it off using the expression FileETag none.

Compressing PHP Pages

The following requires the PHP installation to have the zlib extension enabled, which it should be by default. We use the expression php_value output_handler ob_gzhandler to turn on compression of the final php pages sent to the users browser. It’s noted on the PHP.net website that turning this on via the php.ini zlib.output_compression is preferred if available to edit.

Apache Module mod_deflate

As of Apache 2.0, there’s an available module that compresses the server output before sending to the user, called mod_deflate. This module must be turned on in order to work. I set this up to compress by filetype so it looks like AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript text/x-javascript application/javascript application/x-javascript. There are ways to set this up even on a per browser basis but since the browser negotiates with the server before any files are transferred, it’s not necessary. If the browser is not compatible with compressed content, the server will provide the content uncompressed.

It’s also worth noting that Apache version 1.3 had a method for serving compressed content called mod_gzip.

Final Notes

Using these methods I’ve decreased pageload and bandwith on my site, after adding it my ySlow score for the homepage went from a D(64) to a B(83) and there was a noticeable increase in pageload speed as I was navigating the site. Many people stress that including this code into the httpd.conf file is better because it loads faster and isn’t reloaded every page load as the .htaccess file would be but my being on a shared environment I haven’t tried it myself..

Final Code

ExpiresActive On
ExpiresDefault A300
ExpiresByType text/javascript A2592000
ExpiresByType text/x-javascript A2592000
ExpiresByType application/javascript A2592000
ExpiresByType application/x-javascript A2592000
ExpiresByType text/css A604800
ExpiresByType image/gif A604800
ExpiresByType image/png A604800
ExpiresByType image/jpeg A604800
ExpiresByType text/plain A604800
ExpiresByType application/x-shockwave-flash A2592000
ExpiresByType application/pdf A604800
ExpiresByType text/html A300
FileETag none  php_value output_handler ob_gzhandler  AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript text/x-javascript application/javascript application/x-javascript

MySQL Optimization Top Ten List

2007-11-06T13:27:00.000Z

I recently had the opportunity to delve deeper into MySQL and how to optimize and generally better my database structure and queries. There’s a lot of information on this topic so I thought i’d share the top ten things that matter to me when creating and querying databases.

Make the fields of your tables as small as possible, if you know a varchar field is never going to need a value more than 10 characters, set it to varchar(10).
Always use auto Increment IDs in your tables, even if you don’t expect you’ll need them now they always seem to come in handy.
Index all the fields you will be querying directly, especially those that you know an exact value for.
Normalize the data structure as much as possible, duplicate data is just more for the server to wade through when running a query.
If you’re querying something against a number e.g.( WHERE x = 12 ) there’s no need to use quotes around the number value, this actually slows down the query because it needs to convert from a string to a number.
Limit the use of LIKE and the % wildcard e.g.(WHERE userName LIKE %Woods%) as this slows the query considerably. If you know that the value is always going to be at the beginning of a field, be sure to only use the wildcard at the end to speed up the query e.g.(WHERE userName LIKE Woods%).
Multiple field indexes are good at speeding up queries but be aware that the first field in the index must be the first item from that index searched in the query or the whole thing won’t be used the way you intended.
Be aware that there is a cost to indexing, both in time and space. Indexes speed up select queries but slow down deletes and inserts and basically any other queries that involve writing to the DB. The more indexes a table has the slower these write queries will be because the indexes have to be changed with the data. The indexes also take up disk space which may cause a database to reach its disk limit more quickly. The practical implication of both these factors is that if you don’t need a particular index to help queries perform better, don’t create it.
Use the EXPLAIN keyword with your query to get important information on the query including the possible keys and estimated rows that will need to be searched to find a result. Especially handy with multiple table queries with joins.
Be careful with joins, if used incorrectly they can slow down a query considerably. Values from the preceding table (as listed in the output of EXPLAIN) are used to find rows in the current table. So if you have three tables each with 1000 rows to search you’re actually returning 1,000,000,000 rows of data. Obviously this is too many and indexes should be employed to reduce this number to something more manageable.