In my last post, My Second Brain Never Worked. Then I Gave It a Gardener, I mentioned that putting my Obsidian vault on a VPS with Claude Code permanently running on it, and being able to access it from my phone, was the real “ah ha” moment for me. A few people asked how I set that up, so here’s the full walkthrough.

The idea is simple: rent a cheap DigitalOcean droplet, sync your vault using obsidian-headless (a lightweight CLI — no Electron needed), install Claude Code so it can read and write your notes, and use Happy to control the whole thing from your phone. Total cost is about $24/month.

Update (March 2026): This post originally required running the full Obsidian Electron app headlessly via Xvfb — a real pain to set up. Obsidian has since released obsidian-headless, an official lightweight CLI that handles Obsidian Sync without the desktop app. It uses ~35MB of RAM instead of ~400MB+, and eliminates the need for Xvfb, VNC, a window manager, and all the Electron library dependencies. I’ve updated this guide accordingly — Phase 2 is now much simpler.

With all that out of the way, here is essentially the plan I followed with Claude Code. Before starting, I’d recommend firing up your own Claude Code instance and pointing it at this post so it can help you out if you hit any snags!

Phase 0: Create the Droplet

Step 1: Sign Up / Log In to DigitalOcean

Go to https://cloud.digitalocean.com — create an account if you don’t have one.

Step 2: Create a Droplet

1. Click Create → Droplets
2. Region: Choose the closest to you (reduces latency for Happy sessions)
3. Image: Ubuntu 24.04 (LTS) x64
4. Size: Regular (shared CPU) → $24/mo (4GB RAM, 2 vCPUs, 80GB SSD)
   • The 2GB tier might work now that we use obsidian-headless (~35MB) instead of Electron (~400MB+), but 4GB gives comfortable headroom for Claude Code sessions
5. Authentication: Choose SSH Keys (recommended)
   • If you don’t have one: on your Mac, run cat ~/.ssh/id_ed25519.pub (or id_rsa.pub)
   • Copy the output and paste it into DigitalOcean’s “New SSH Key” dialog
   • If you have no SSH key at all: ssh-keygen -t ed25519 on your Mac first
6. Hostname: vault-server (or whatever you want)
7. Click Create Droplet

It’ll be ready in about 60 seconds. Copy the IP address it shows you.

Step 3: First Login

# From your Mac:
ssh root@YOUR_DROPLET_IP

# Example:
ssh root@143.198.123.45

Accept the fingerprint. You’re in!

Step 4: Create a Non-Root User

Don’t run everything as root. Create your own user:

# Create user (replace 'YOUR_USER' with your name)
adduser YOUR_USER
# Set a password when prompted, skip the rest with Enter

# Give sudo access
usermod -aG sudo YOUR_USER

# Copy your SSH key to the new user
mkdir -p /home/YOUR_USER/.ssh
cp /root/.ssh/authorized_keys /home/YOUR_USER/.ssh/
chown -R YOUR_USER:YOUR_USER /home/YOUR_USER/.ssh
chmod 700 /home/YOUR_USER/.ssh
chmod 600 /home/YOUR_USER/.ssh/authorized_keys

# Log out and log back in as your user
exit

ssh YOUR_USER@YOUR_DROPLET_IP

From here on, everything is done as your non-root user.

Phase 1: System Setup

Step 5: Update Everything

sudo apt update && sudo apt upgrade -y

Note: If prompted about a modified sshd_config, choose “keep the local version currently installed” — DigitalOcean customizes this file and you don’t want to overwrite it. After the upgrade finishes, you may see “System restart required” on your next login. If so, run sudo reboot and SSH back in after ~30 seconds.

Step 6: Install Core Dependencies

# Misc tools
sudo apt install -y git curl tmux htop wget

# Fix for Ghostty terminal users — tmux won't work without this
echo 'export TERM=xterm-256color' >> ~/.bashrc
source ~/.bashrc

Step 7: Install Node.js via nvm

Claude Code and Happy CLI both need Node.js. Use nvm so you control the version.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Load nvm into current session
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install Node.js 22 (LTS)
nvm install 22
nvm use 22
nvm alias default 22

# Verify
node --version  # should show v22.x.x
npm --version

Phase 2: Install Obsidian Headless Sync

Obsidian offers an official lightweight CLI (obsidian-headless) that syncs vaults without the desktop Electron app. It uses ~35MB of RAM instead of ~400MB+, and you don’t need Xvfb, a window manager, VNC, or any Electron library dependencies.

Step 8: Install obsidian-headless

sudo npm install -g obsidian-headless

# Verify
ob --version

Step 9: Authenticate and Set Up Sync

# Log in to your Obsidian account
ob login
# Enter your email, password, and MFA code when prompted

# List your remote vaults
ob sync-list-remote
# Note the vault name you want to sync

# Create the local vault directory
mkdir -p ~/obsidian-vault

# Link the local directory to your remote vault
ob sync-setup --vault "YOUR_VAULT_NAME" --path ~/obsidian-vault --device-name "vps-headless"
# Enter your end-to-end encryption password when prompted

# Do an initial sync to pull down all files
ob sync --path ~/obsidian-vault
# Wait for it to finish

Step 10: Create the Obsidian systemd Service

This makes headless sync start automatically on boot.

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/obsidian-headless.service << EOF
[Unit]
Description=Obsidian Headless Sync
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/obsidian-vault
ExecStart=/usr/bin/ob sync --continuous --path %h/obsidian-vault
Restart=on-failure
RestartSec=10
Environment=HOME=%h

[Install]
WantedBy=default.target
EOF

# Enable lingering (so user services run without being logged in)
sudo loginctl enable-linger $USER

# Enable and start the service
systemctl --user daemon-reload
systemctl --user enable obsidian-headless.service
systemctl --user start obsidian-headless.service

# Check it's running
systemctl --user status obsidian-headless.service

Verify sync is working:

# Check the service — should show a single node process (~35MB)
systemctl --user status obsidian-headless.service

# Check memory usage
free -h
# Without the Electron app, expect much lower memory usage

Phase 3: Install Claude Code

Step 11: Install Claude Code

# Native installer
curl -fsSL https://claude.ai/install.sh | bash

# Verify
claude --version

Step 12: Authenticate Claude Code

claude
# This will give you a URL to paste into a browser on your Mac/phone
# Open the URL, enter the code shown, and follow the prompts
# to connect your Claude account.

After auth, test that it works:

cd ~/obsidian-vault
claude "list the files in this directory"
# Should see your vault files

Exit with /exit or Ctrl+C.

Phase 4: Install Happy CLI

Step 13: Install Happy

npm install -g happy-coder

# Verify
happy --version

Step 14: Connect Your Phone

happy --auth
# This displays a QR code in your terminal

1. Download the Happy app on your phone (iOS App Store / Google Play)
2. Scan the QR code with the Happy app
3. You’re paired. The connection is end-to-end encrypted.

Step 15: Test Happy

cd ~/obsidian-vault
happy
# This starts Claude Code wrapped in Happy's relay

Now open the Happy app on your phone — you should see the Claude Code session. Type a message from your phone and watch it appear. Type in the terminal and watch it appear on your phone.

This is the magic moment. You can now control Claude Code from your phone, working on your Obsidian vault files, from anywhere!

Phase 5: Make It Persistent

You want happy (wrapping Claude Code) to be running whenever you want to connect from your phone. Happy needs a real terminal (TTY) to work, so running it as a plain systemd service fails. The solution: systemd launches a tmux session with Happy inside it — auto-starts on boot, survives SSH disconnects, and gives Happy the terminal it needs.

Step 16: Create the Happy systemd Service

# First, find your happy path (we need the full path for systemd)
which happy
# Example output: /home/YOUR_USER/.nvm/versions/node/v22.x.x/bin/happy
# Use YOUR path in the ExecStart line below

cat > ~/.config/systemd/user/happy-claude.service << 'EOF'
[Unit]
Description=Happy CLI (Claude Code mobile access)
After=network-online.target obsidian-headless.service
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=%h/obsidian-vault
ExecStart=/usr/bin/tmux new-session -d -s claude %h/.nvm/versions/node/v22.14.0/bin/happy
ExecStop=/usr/bin/tmux kill-session -t claude
Environment=HOME=%h
Environment=PATH=%h/.nvm/versions/node/v22.14.0/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable happy-claude.service
systemctl --user start happy-claude.service

Note: Adjust the node version path (v22.14.0) to match your actual install. Check with which happy.

Verify It’s Running

# Check the service status (should show "active (exited)" — that's correct for oneshot)
systemctl --user status happy-claude.service

# Confirm the tmux session exists
tmux list-sessions
# Should show: claude: ...

# If you want to peek inside (optional):
tmux attach -t claude
# Detach with: Ctrl+B, release, then D
# DO NOT use Ctrl+C — that kills the Happy process

If Happy Dies or You Need to Restart

systemctl --user restart happy-claude.service

Phase 6: Verify Everything Works

Checklist

# 1. Obsidian headless sync is running
systemctl --user status obsidian-headless.service
# Should show "active (running)" with a single node process

# 2. Sync is connected
ob sync-status --path ~/obsidian-vault

# 3. Vault files are present and syncing
ls ~/obsidian-vault/
# Should show your vault's files/folders

# 4. Claude Code can access the vault
cd ~/obsidian-vault && claude "what markdown files are in this vault?"

# 5. Happy is running in tmux via systemd
systemctl --user status happy-claude.service
# Should show "active (exited)"
tmux list-sessions
# Should show "claude" session

# 6. Happy works from phone
# Open Happy app on phone, verify connection

# 7. Memory looks healthy
free -h
# Should show well under 2GB used — headless sync uses ~35MB vs ~400MB+ for Electron

# 8. After a reboot, everything restarts automatically
sudo reboot
# Wait 30 seconds, SSH back in
systemctl --user status obsidian-headless.service
# Should show "active (running)"
systemctl --user status happy-claude.service
# Should show "active (exited)"
tmux list-sessions
# Should show "claude" session

Maintenance & Troubleshooting

Updating Components

# Ubuntu
sudo apt update && sudo apt upgrade -y

# obsidian-headless
sudo npm update -g obsidian-headless

# Claude Code (auto-updates, but to force)
claude update

# Happy CLI
npm update -g happy-coder

# Node.js
nvm install 22  # installs latest 22.x

Common Issues

Obsidian Sync stops working:

# Restart the headless sync service
systemctl --user restart obsidian-headless.service

# Check sync status
ob sync-status --path ~/obsidian-vault

Can’t connect to Happy from phone:

• Check that the service is running: systemctl --user status happy-claude.service
• Check that the tmux session exists: tmux list-sessions
• If the session died, restart: systemctl --user restart happy-claude.service
• The Happy relay (app.happy.engineering) needs to be reachable from both the droplet and your phone
• Unlike a home Pi, the droplet’s internet is rock solid — so this is almost always a process issue

Obsidian Sync conflict: If you edit the same file on your phone/desktop AND Claude Code edits it on the droplet simultaneously, Obsidian Sync will create a conflict file. Rare in practice.

“Killed” or process disappears: This is the OOM killer. Your droplet is running out of RAM. Check with dmesg | tail — if you see “Out of memory”, you need to either add swap or upgrade to a bigger droplet:

# Add 2GB swap (quick fix)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make it permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Monitoring

# Quick health check
echo "=== Memory ===" && free -h && echo "=== Obsidian ===" && systemctl --user status obsidian-headless.service --no-pager -l | head -5 && echo "=== Vault files ===" && ls ~/obsidian-vault/ | head -10

Backups

Your vault is synced to:

1. Obsidian Sync (cloud) — with 12 months version history on Plus
2. Your phone (Obsidian mobile)
3. Your desktop (Obsidian desktop)
4. The droplet (this setup)

That’s 4 copies. For extra paranoia:

# Weekly local backup
crontab -e
# Add this line:
0 3 * * 0 tar -czf ~/vault-backups/vault-$(date +\%Y\%m\%d).tar.gz ~/obsidian-vault/

Quick Reference

When to Upgrade to a Raspberry Pi

I was initially debating between setting this up on DigitalOcean or buying a Raspberry Pi to run everything. I figured spending $24/mo to test if I liked this setup would be a good way to validate things before sinking money into a Pi.

If you find yourself using this daily and the $24/mo feels wasteful, that’s a good signal to switch. A Pi 5 8GB (~$180) pays for itself in ~8 months vs the droplet. The setup process is nearly identical — same systemd services, same tools, just on local hardware. You can reuse this guide almost verbatim.

I always wanted a second brain.

The thought of it seems so alluring: organize all of your thoughts, make connections, discover new ideas, build your personal knowledge graph! But I could never seem to get the promise of the second brain to materialize because of the maintenance work.

If you follow productivity gurus on YouTube they all recommend the same strategy:

Step 1 - Dump all of your unstructured thoughts and todos into a folder called “Inbox” or “Daily Note”.

Great! I can do this!

Step 2 - Now organize it all. Put things into a well thought out folder structure. Add tags and backlinks. Decide which docs stay and which get tossed. Become a one-person Wikipedia.

yeah. no. I am not going to do that.

Then it occurred to me that Claude Code is really good at reading markdown. As I’ve been creating AGENTS.md and Skills and rules, etc. etc. it often felt like I was trying to build it a second brain. So, why not flip the script and have it build my second brain?

My Gardener: Claude 🌱

For me, the key insight — one I first encountered in Alex Komoroske’s Bits and Bobs — is that I want Claude to do cognitive labor, not thinking. I don’t want it to generate ideas. I want it to take my rough, unstructured thoughts and give them shape — add tags, create links, break a rambling paragraph into an organized note.

This matters because the value of a second brain was never supposed to be in the filing! It was in the connections. The problem was that you had to do a bunch of boring filing work before you could get to the interesting part. Claude eliminates that bottleneck.

The first thing I asked Claude to do was to read my entire vault and look up some common Obsidian organization strategies, and try to organize the vault for me. It came back with a number of questions, starting from pretty broad and slowly working down to specifics as we hashed out how I wanted to work.

Next I asked it to write a CLAUDE.md to codify the system we had built. Then I asked it to write a simple Skill called /process-daily that looks at my Daily Note and turns it into nicely structured idea docs.

My Daily Workflow

Here’s what a day in the life of using this system looks like:

Stage 1: Capture and organize. I create a new daily note each day and braindump into it. I do this a lot when I’m walking around so I started using Superwhisper to make dictation easier. At the end of the day, I run /process-daily and a messy daily note becomes nice, connected documents.

Stage 2: Explore connections. Now that my ideas are organized and cross-linked, I can have a conversation with Claude about what’s in the vault. Often this takes the form of me telling it to read an idea doc for context, and then we go back and forth expanding and exploring different points and looking for connections.

Stage 3: Write and edit. A big goal of all this is for me to get back into publishing. When I’m ready to write, Claude becomes an editor. I tend to edit as I write, so I’ll send sections to Claude for feedback, and iterate. “This paragraph is clunky — how would you tighten it?” or “I don’t feel like I have an ending, help me come up with some options.”

I also added a /weekly-summary Skill that will look at the last week of daily notes, and turn them into a digest newsletter-style doc. Here I let Claude do some thinking and writing of its own. It frequently surfaces things that I had forgotten which makes these newsletters surprisingly useful.

Mobile is a must

The thing that really changed everything, honestly, was putting my entire Obsidian vault on a VPS with Claude Code permanently running on it using Happy so I can talk to it from my phone.

When I first wake up and take my dog for a walk, it’s a wonderful time to think. But I’d found over the years that I had started smothering my brain with podcasts during this time. As an experiment, I thought “I’ll just walk in silence today and if anything occurs to me I’ll chat with Claude on my phone and we’ll work on ideas in the vault.”

The very first time I did this, I remember being so engrossed that I was still talking to it when I got home, and even stopped brushing my teeth at one point so I could tell it another idea.

This has now become one of my favorite parts of the day.

Why Obsidian is the right canvas

This workflow isn’t Obsidian-specific in theory, but in practice Obsidian has three properties that make it work exceptionally well:

Markdown is Claude’s lingua franca. Claude reads and writes markdown natively. I don’t even bother with MCPs, I just run Claude in the root of the Obsidian Vault and it immediately understands the structure — frontmatter, headings, wiki-links, tags, all of it.

It’s local and file-based. Your data stays on your machine (or syncs however you choose). There’s no dependency on a third-party API or cloud service. This also means Claude can read, write, and reorganize files directly — no intermediary layer.

The whole vault is actionable. At some point I realized what I really wanted was something with access to all of my context. That’s what this gives me. Claude doesn’t just work with your “notes” — it works with everything in the vault. Recipes, meeting notes, project specs, reading lists. Any structured markdown becomes a surface Claude can operate on.

The flywheel

Publishing again after years of not writing has created a positive loop: writing makes me want to capture more, capturing more creates connections, connections give me things to write about. A few small rituals — going for a walk, running my slash commands, watching ideas get organized — compound into something that feels genuinely new.

Steve Jobs called the computer “a bicycle for the mind.” I keep coming back to that when I think about this system I’ve cobbled together.

I’m doing the pedaling — Claude just amplifies it and propels me forward.

Recently they launched an AI chatbot. On the surface this seems like a cool feature, like my own little personal CPA, but in practice I could never seem to get excited by it. Mainly because it’s like talking to my financial data through a mail slot.

The chatbot only knows what Monarch knows. But my financial life connects to everything—my goals in Obsidian, that spreadsheet where I’m modeling whether we can afford to remodel the kitchen. The chatbot can’t see any of that. It’s working with a fraction of the context I have.

And there’s no memory. Each conversation starts fresh. Instead of feeling like a CPA who’s known me for years, it’s a new employee on their first day, every time.

I can’t do anything with the conversation either. There’s no place to save it. No way to build up plans over time that the AI and I can refer back to as things evolve.

I realized what I wanted was the full power of Claude Code along with my financial data so I could construct whatever interpretation of it I wanted.

So I Built My Own

I found an unofficial SDK for Monarch’s API and had Claude port it to TypeScript. Now I’m able to pull my financial data into a local SQLite database whenever I want. I built a little web UI to trigger snapshots, or I can just ask Claude to do it.

Suddenly the experience feels bigger than Monarch.

When I talk to Claude about my finances, it has all of the context—my Obsidian notes, other data sources I’ve connected, the financial plans we’ve generated together in previous conversations. I can say “remember that plan we made in October?” and it does!

This transforms it from a chat window into a workspace.

One tradeoff: I’m now responsible for my own data privacy. I handle this by stripping names and account numbers from each snapshot before saving. It’s not fancy, but it works.

The Chatbot Is a Ceiling

Here’s what I realized: an AI chatbot feature is inherently limiting. You’re giving users the full power of an LLM and then… capping it. They can only access their data through your interface. They can only ask the questions your chatbot is designed to handle with the context you provide.

This turns the chatbot into a gatekeeper.

Until the advent of something like Claude Code, there was very little value in giving users direct access to their data. A very small subset of technically minded customers might choose to build something with it, but the majority would not, so why invest time in building a public API?

But now that software is cheap and bespoke, giving users access to their data might actually be a selling point.

What I’d Do Instead

If I were building a product like Monarch, I’d focus on two things:

1. Own the drudgery.

Monarch is great at the stuff I don’t want to deal with: fiddly Plaid connectors, keeping transaction history up to date, auto-categorizing everything. Sure, I could try to vibe code my own version of this—but it would almost certainly bitrot and break as soon as I walked away. This is where Monarch earns the $100/year I pay them.

2. Make the data accessible.

Provide read-only API access so users can pull their data into whatever context they want. Maybe provide an API or CLI so agents can perform actions on the user’s behalf. We’re not there yet—there’s infrastructure to build first—but it’s where things are heading.

The point is: stop being a gatekeeper. Be infrastructure. Let users bring their data into their own AI workflows, with their own context, their own memory, and their own tools.

Don’t wall users in with your AI, let them bring their own.

Who would be crazy enough to do that?

No encryption, no standards, no recourse if something went wrong. Fast forward to today: we buy groceries, cars, and houses online without a second thought. What changed was that we built the infrastructure to make it safe.

We’re at that same inflection point with agents.

The Trillion-Dollar Problem

Right now, giving an agent access to your computer feels a lot like typing your credit card into a 1994 website. The potential is obvious—an assistant that can actually do things for you, not just talk about doing things. But the risks are equally obvious. One prompt injection or compromised package, and suddenly your AI assistant is sending your bank info to evil.com.

The recent Clawdbot hack made this visceral. A supply chain attack turned a helpful AI into a data exfiltration tool. And here’s the uncomfortable truth: there was nothing particularly sophisticated about it.¹ The attack worked because we haven’t built the infrastructure to make agents safe.

Building that infrastructure is a trillion-dollar opportunity. I realize that’s a very sales-y way to put it but I think it’s true.

What E-Commerce Got Right

E-commerce didn’t become safe because of one breakthrough. It became safe because of layers—each solving a different part of the problem.

Encryption (SSL/TLS) meant your credit card couldn’t be intercepted in transit. Certificate authorities meant you could verify you were talking to Amazon, not a scammer pretending to be Amazon. Payment processors meant merchants never saw your actual card number. PCI-DSS gave companies standards to follow. Chargebacks meant mistakes could be reversed. Consumer protection laws meant someone was liable when things went wrong.

No single layer was sufficient. Together, they made e-commerce trustworthy.

Agents need the same thing: a security stack where each layer handles what the others can’t.

The Required Unlocks

1. Supply Chain Security

When your AI installs a package, it’s not installing one thing. It’s installing a hundred smaller packages in a trench coat. If any single dependency is compromised, it’s game over. And as the Clawdbot hack showed, agents trust their supply chain implicitly.

We need packages to declare what they actually do—what inputs they read, what outputs they produce, what network calls they make. And we need something watching to make sure they don’t lie.

“Hey, it looks like left-pad wants to access your SSH keys. That seems… wrong.”

2. Prompt Injection Defense

Even with secure packages, an AI can be manipulated by malicious text. A cleverly crafted email could instruct your agent to open a port on your network, download a file, or leak sensitive data.

There will probably be a bunch of interlocking solutions here: better sandboxing, and built-in guardrails (like OpenAI’s rule limiting agents to public URLs) to name a few.

Future models may also get better at recognizing manipulation—the same way you’d be suspicious if a stranger asked you to wire money to an overseas account.

3. Identity and Authorization

E-commerce asked: “Who is this merchant, and can I trust them?” Agents need to ask: “Who is this tool, and what should it be allowed to do?”

Right now, permissions are too coarse. “Claude wants to run shell commands” is like a website asking for your entire bank account when it only needs to charge $20. We need scoped permissions: this agent can read files in ~/projects but not ~/.ssh, can make HTTP requests to api.example.com but nowhere else.

Importantly, these policies can’t be ad hoc. Most users don’t know ~/.ssh is dangerous. And even those who do don’t want to write security rules for every corner of their machine.

4. Reversibility

Chargebacks made e-commerce viable. If a merchant scammed you, you could undo the transaction. What’s the equivalent for agents?

Git gives us reversibility for code. But what about the email your agent sent? The API call it made? The file it deleted? We need more systems designed with “undo” as a first-class feature.

5. Audit Trails

When something goes wrong, you need to reconstruct what happened. E-commerce has transaction logs, fraud detection systems, paper trails for disputes.

Agents need the same: a complete record of what actions were taken, what data was accessed, and why.

Audit trails also enable other layers:

• Reversibility — you can’t undo what you can’t identify
• Fraud detection — you can’t spot patterns without records
• Containment — “freeze the account if you see unusual activity” requires knowing what activity occurred

6. Containment

Smart security assumes breaches will happen and limits the blast radius. Credit cards have fraud limits and transaction caps. Your bank might freeze your card if it sees unusual activity.

Agents need similar containment: resource quotas, restricted directories, network isolation, cooling-off periods for dangerous operations. The goal isn’t to prevent all attacks—it’s to make sure a successful attack can’t do unlimited damage.

7. Reputation Systems

E-commerce has seller ratings, buyer protection, and escrow services. You can see that a merchant has completed 10,000 transactions with a 99% satisfaction rate.

What’s the equivalent for AI tools and packages? “This MCP server has been used by 50,000 developers with no security incidents” sounds good in theory, but this is exactly what the Clawdbot hack exploited—artificially inflating download counts to build false trust.

The Pace Layers

Architect Stewart Brand talks about “pace layers”—how civilizations have fast-moving layers (fashion, commerce) built on top of slow-moving layers (infrastructure, culture, nature). The fast layers innovate; the slow layers stabilize.

Security works the same way:

It feels like we’re currently trying to solve AI security almost entirely at the fast layers—smarter models, better prompts, application-level guardrails. These help, but they’re not durable. The fast layers buy us time while the slow layers catch up.

E-commerce wasn’t truly safe until the slow layers matured. SSL and fraud detection were stopgaps. PCI-DSS and consumer protection laws were the foundation.

Agents won’t be truly safe until we have the equivalent: industry standards for agent behavior, legal frameworks for liability, and runtime environments designed for containment from the ground up.

The Opportunity

The good news is that every layer represents an opportunity. Companies that build the identity layer, the audit layer, the containment layer—they’re building the infrastructure that makes the entire ecosystem possible.

In 1994, it was crazy to put your credit card online. In 2004, it was normal. The companies that built the layers in between—Verisign, PayPal, Stripe—created enormous value by making trust possible.

The same will be true for agents.

What does Voltus do?

Voltus offers a number of programs to its customers, but it’s primarily known for its demand response programs. Demand response is a clever grid balancing technique that’s especially important as we transition to renewable energy.

You can think of it like this: When there is more demand (i.e. people using power) than there is supply (power being generated) then a grid operator has two choices—either generate more supply, or reduce demand.

Generating more supply means firing up a power plant and producing green house gases. Reducing demand means convincing (or incentivizing) customers to use less power. This is where Voltus comes in.

When a grid operator needs a reduction in demand they send a signal to Voltus, and Voltus pays major power users (factories, big box stores, etc.) to curtail their consumption. Voltus gets paid by the grid operator for this reduction in demand, and Voltus passes a percentage of that payment on to their customers.

You may have heard the term “virtual power plant” before (I wrote about it recently). That’s essentially what Voltus does. They manage around 2 Gigawatts (GW) of power—enough to run ~328,000 homes—and have paid out more than $31M to their customers.

How does Voltus fight climate change?

If Voltus did not exist, when a grid operator needed more power they would be forced to fire up a fast acting fossil fuel plant. Voltus provides a cleaner (literally zero CO2) alternative.

But what’s more important is how Voltus enables renewable energy. A grid designed around wind and solar is highly volatile—every cloud or reduction in wind speed causes the supply to drop. If we want to move away from fossil fuel reserves, then we need grid balancing technologies like Voltus.

What about batteries? you might ask.

According to the Energy Information Administration (EIA), at the end of 2021, the United States only had 4.5GW of energy storage, but it’s estimated that the U.S. will need 930GW by 2050. So, yes, batteries are great, but there’s just not enough of them right now and they take time to install. The beauty of a virtual power plant is that there’s no construction required!

But really these things are not mutually exclusive. A greener grid will require a combination of renewable generation, long and short term battery storage, and demand response.

We’re hiring

One of the things that attracted me to Voltus was the incredibly strong work culture. Everyone I spoke to during my interview process seemed to really care about the company’s mision, and the leadership team has put a lot of thought and effort into creating a supportive, inclusive environment. I feel like this video from my manager Jamie does a good job of conveying the vibe 😁

Voltus is entirely remote, and currently hiring across a number of positions. If you’re interested in joining the team, take a look at our careers page or feel free to reach out to me on Twitter and I’d be happy to answer any questions you may have.

All in all, I feel really fortunate to have found this team, and I hope if you’re reading this that you might be considering a role in climate as well. It’s a big challenge, and we need all the help we can get, but I’m hopeful and optimistic that we’ll get there 🌎

Smoke from nearby wildfires was trapped over the Bay Area, making the region look like the surface of Mars. It’s hard to describe the feeling of walking around my neighborhood with it looking like the set of Blade Runner, but the one thing I can say is that it made the immediacy of climate change paramount.

That morning a switch flipped in my brain. I couldn’t keep doing my job and ignoring what was literally happening outside of my window. I decided to leave Google to look for a role doing something—anything!—connected to climate.

Today I want to talk about a clever idea I learned about during my job search. I think it is potentially a transformational new industry and one that many, if not all of us, will participate in: turning every home (and apartment) into a virtual power plant ⚡️

On the surface that just sounds cool, right? But what does it actually mean? To understand how it works we first have to understand how the grid operates and what happens when there’s not enough power to go around.

How the grid works

The power grid is a balancing act—there’s the amount that consumers are trying to use—the demand—and there’s the amount being generated by power plants—the supply.

Sometimes, like on the hottest day of the year when everyone is running their air conditioners, demand outpaces supply. During these times, the grid operator has to go to the energy market to buy more power to respond to the demand.

Depending on the situation, this might mean calling up a peaker plant. These are fast-acting—and very dirty—fossil fuel plants that can ramp up quickly.

There are a number of problems with peaker plants:

1. They’re expensive to operate

   A new report has found that New Yorkers over the last decade have paid more than $4.5 billion in electricity bills to the private owners of the city’s peaker plants, just to keep those plants online in case they’re needed — even though they only operate between 90 and 500 hours a year. source

2. They’re dirty

   Many of these facilities are 50 or more years old, lack modern pollution controls, and run on dirty fuels like kerosene or oil source

3. They damage the health of our communities

   They’re predominantly located near population centers where energy demands are greatest and typically located in communities of color and under-resourced areas. There are more than 1,000 peakers in operation across the country today source

Ironically, as we’ve moved from using fossil fuels to renewables like wind and solar, some electric utilities have proposed building more peaker plants to make up for the intermittent nature of renewables.

An alternative to peaker plants is that we could all agree to use less energy when the grid is under strain. But this presents a coordination problem: consumers don’t know when the grid is under strain, so they don’t know when to use less energy, and therefore grid operators cannot rely on these energy savings.

So how do we solve this coordination problem?

Demand response

As I mentioned earlier, the power grid is a balancing act. One way to balance the grid when demand is high is to generate more power. The other way is to lower demand, a.k.a. “demand response”.

In other words, if you and I agree to unplug our refrigerators for an hour when the grid is under strain, then we help rebalance the grid by lowering the demand.

Where this gets interesting is when you think about aggregating that collective action. Instead of unplugging one refrigerator for an hour, we unplug one million. Now we’re talking about megawatts of power that can be “generated”, on-demand, to rebalance the grid.

Technically we’re not generating new power, but the net effect is the same. If the grid needs one megawatt of power, and we turn off one megawatt’s worth of refrigerators, then everything evens out.

Rather than thinking of these as megawatts generated, you can instead think of them as “negawatts” saved (yes, that is an actual term used in the industry).

If we all knew when to turn off our refrigerators (or thermostats/lights/space heaters/air purifiers/EV chargers/etc.), and we understood energy markets well enough to sell energy into them, then we could act as a kind of virtual power plant. When a grid operator needs power, instead of going to a dirty peaker plant, they could instead call up our virtual power plant and pay us for our negawatts!

It might seem odd to think about selling energy that we didn’t use, but according to the Federal Energy Regulatory Commission (FERC), we can do just that. Negawatts are priced and sold just like megawatts.

To do this sort of collective action, we need aggregators: someone to tell us when to reduce our energy consumption, who can handle selling that energy on our behalf. This is where startups like Voltus and OhmConnect (to name a few) enter the picture.

These companies present themselves as virtual power plants to grid operators and sell negawatts at a cost per kilowatt hour. They generate these negawatts by sending notifications to their users who then reduce their energy consumption during specific times. When Voltus or OhmConnect gets paid by the grid operator, they pass a percentage of that payment on to their users.

Voltus mostly targets industrial customers (steel mills, factories, etc.) but they told me that they plan to do more consumer demand response soon. OhmConnect, on the other hand, is entirely consumer facing and currently operates in California, Texas, and New York. I’ve been using OhmConnect since February 2022—about two months—and have so far earned around $100 through a combination of energy savings and referrals.

While the money is a nice bonus, what most excites me about OhmConnect is feeling like I’m participating in a social experiment to improve grid intelligence and help the climate. I had wanted to add smart lights and plugs to my home for convenience, but this creates an additional incentive when I can think of my home as (part of) a virtual power plant.

Let me walk you through an example so you can see how it works.

One OhmHour

When the grid is really busy, OhmConnect sends me a notification with a specific time—an OhmHour—during which I should ramp down my power consumption. OhmHours typically occur once per week, and they notify me a day or so in advance, and then an hour before the event begins.

During the OhmHour I’m rewarded in points—called watts—based on how much I reduce my consumption. Watts can be exchanged for cash (via PayPal), spent on discounted smart devices, or used for contests: free groceries for a year, an e-bike, that sort of thing. OhmConnect also pays me cash for referring new users. It varies by state, but I earn $40 if I refer a fellow Californian, and the referee receives $10.

There’s no requirement to connect devices to OhmConnect—you can walk around your house and manually turn things off during an OhmHour—but I found it easier to let them do it for me, plus I receive bonus watts for every connected device. So I connected my Nest thermostat and a smart plug powering my refrigerator to their system.

During the event I’m graded on how much energy I save compared to my previous 10-day average. For example, on March 16th from 7-8pm, I reduced my consumption down to 0.19kWh from an average of 0.43kWh.

I didn’t have to radically alter my life to achieve these savings. During this specific event, I was watching TV on the couch with my wife. But prior to the OhmHour starting I turned off the unused lights in my house and put my dishwasher on a timer so it would start later in the evening. My refrigerator automatically turned off and my thermostat switched to eco mode.

Brief aside: Did you know that most dishwashers have a timed start feature? This is really helpful if you’re on a peak time-of-use electricity plan!

In total I earned 605 watts during that OhmHour: 245 watts in energy savings + 360 bonus watts for having two smart devices connected to my account (320 for my thermostat and 40 for my smart plug). Because you can use watts to buy more smart devices, which then grant additional watt bonuses, you can see how this turns into a positive feedback loop.

Is this a scam?

OhmConnect is clearly trying to gamify this process—apparently the CTO used to work at Zynga—so there are streaks and levels that increase the discounts you receive when you exchange your watts for smart devices. You can also spend watts to increase your referral bonus, something I’ve done in the past before referring a few of my friends.

Does it feel a tad like a multi-level marketing scheme? Sure. But if you understand the demand response / virtual power plant model, you can see that they’re actually making money by selling negawatts to grid operators and paying you a percentage of that when you cash out your watts or use them to buy subsidized smart devices.

So it really is more of a social game where reducing CO2 is the goal and there are financial incentives. It’s a novel approach to climate change because it takes the addictive engagement and recruitment model of Farmville but uses that power for good. Who would have ever thought that Farmville could help save the planet?!

Privacy concerns

I think it’s fair to mention that participating in OhmConnect does require sharing some data. For OhmConnect to work, it first needs to know how much energy you’re using, which means giving them access to your energy data via your utility’s website. In addition, you’re rewarded for connecting smart devices to your account, which lets OhmConnect turn those devices off during an OhmHour.

I can totally understand being concerned about a third-party having the ability to turn off your refrigerator, but you can always opt-out of the OhmHour or walk over and turn your refrigerator back on (or through the smart plug app on your phone). Another option is to only use the smart plugs for less critical devices.

Since you’re only rewarded based on your energy savings, if you choose to completely ignore the OhmHour there’s no real penalty, you just won’t earn any watts.

The way I see it, giving OhmConnect the ability to ramp down my power consumption acts as a kind of backpressure model for the grid, so even if I’m not at home, my devices can quickly switch off and hopefully do a bit of good. Also, I’ve learned that an unopened refrigerator has enough thermal inertia to safely be off for around four hours 😄

Give it a shot!

If you’re interested in trying OhmConnect you can use my referral and we’ll both get some money 🙌 When you sign up they will offer to send you a smart plug for $1. Technically you have to pay the full $11 and then they refund you $10 if you connect the device to your account (I can verify that they did refund me).

If you want to learn more about their business I recommend checking out the My Climate Journey interview with their CEO, Cisco DeVries.

I should also mention that both OhmConnect and Voltus are hiring!

• OhmConnect jobs
• Voltus jobs

I think this is such a cool space and am excited to see where these companies go in the future. If you do give OhmConnect a shot, give me a shout on Twitter and let me know how it goes for you!

Do climate companies even need front-end engineers?

Right out of the gate I can say an emphatic yes—there are plenty of web dev roles available at climate tech companies. Also, you don’t need to be a climate expert to apply. None of the places I spoke with assumed that I had any prior knowledge of their domain, but they were all really motivated to help me get up to speed. I learned a lot just in the application process and I imagine you will as well.

Unlike traditional tech companies, web (and mobile) are not always the centerpieces for climate tech companies. Many are focused on building new kinds of batteries/fuels/sensors/grids/etc. So when you’re searching for roles you’ll see a lot of IoT and low-level programming, plus cloud and big data. But there’s absolutely demand for front-enders as well.

Where to find jobs

The best resource for job hunting is Climatebase. I cannot stress this enough: sign up for their newsletter. It comes out weekly and gives a brief rundown of what’s new in the world of climate and then lists all the new jobs and companies for that week. Here’s a sample from October.

Take the time to fill out a profile on Climatebase and each week they will email you roles that match your skills.

You can also go through the back catalog of the My Climate Journey podcast and look at the careers page for the companies being interviewed.

How to educate yourself

The Work on Climate group has some good resource starter packs. They also have a Slack that you can join to converse with like-minded folks. Personally, I didn’t use the Slack much, but I did find the starter pack reading material interesting.

I listen to a lot of podcasts and I found the Volts podcast/newsletter by David Roberts to be really helpful. Go through the archive and pick an assortment of episodes that seem interesting. Some are incredibly dry and wonkish (be forewarned) but others are really good explanations of topics that I only kind-of, sort-of understood. Here’s a great starter episode that’s all about methane.

Another podcast is How We Survive by Molly Wood. It’s a nine-part series that mostly focuses on lithium batteries, but it does a good job of talking about the social justice side of climate change, as well as the tech.

The most helpful book I read was The Ends of the World which is a fascinating retelling of all of the world’s mass extinction events and how all of them (yes, even the dinosaurs) were connected to the planet’s carbon cycle. Understanding how the carbon cycle works and what happens when there’s too much or too little CO2 is just really interesting.

What the employment landscape is like

Most of the companies are startups

I realized early on that I didn’t know any “climate companies”. It’s easy to name big tech companies, but there hasn’t been enough time or investment for climate companies to become household names. So most of the places I spoke to were in the range of tens of people, to maybe a couple hundred.

On the one hand, this is great. I got to speak directly to the founders of some companies and the engineering teams felt tight-knit and energized. Your work will almost certainly have a big impact on the organization and that can be really motivating.

On the other hand, there’s a lot of career and financial uncertainty when joining a startup. The base pay may be less than you currently make and equity will be much riskier/there will be less of it to go around.

I don’t say these things to discourage you from working on climate—I personally think we all need to seriously consider making the career switch—but I understand that everyone is in a different situation with their financial responsibilities and it’s important to know ahead of time what kinds of companies are out there and what the compensation will be like.

Carbon offsets are popular…for better or worse

A significant portion of the companies I looked at deal in carbon offsets, which are a fairly controversial topic. The idea with an offset is that a big company can pay someone else to capture CO2 (i.e. plant or protect a forest), and this then “offsets” the big company’s own emissions. Companies that sell offsets are market makers, they find the projects that will offset emissions, and they package them up and sell them.

There are a number of problems with offsets, a few that I know of are:

• It’s unclear how they’re regulated, or if they actually deliver the results they claim.
• Planting a forest can take years to capture significatn CO2, but your emissions go into the air today.
• The offset buyer doesn’t have to change any of their behaviors.

That last point is a big deal, and one of the reasons why folks say offsets are “greenwashing”. Right now a lot of companies are making announcements about offseting their emissions, but imagine if they couldn’t buy offsets? Would they be pressured to actually operate more efficiently instead?

It’s hard for me to answer these questions, but my gut tells me that offsets are not a good model so I tended to steer away from companies who make them their primary business.

React is king

I interviewed or had exploratory phone calls with six companies, and I’ve also read pretty much every Climatebase newsletter over the past four months. I can say with confidence that the two most in-demand front-end skills are React and TypeScript. Every company I interviewed with is using React, and pretty much every company on Climatebase lists it as a desired skill.

Most companies seem fine with you learning React on the job, especially if you have prior experience with similar frameworks (Vue, Angular, Svelte, Lit, etc).

I personally was not that experienced in React (I’ve mostly used Lit), but the beta React docs are really good and do great job of explaining newer concepts like Hooks. I highly recommend reading through these.

Most companies want senior full-stack (but don’t be discouraged!)

Because many of the companies are smaller startups, and likely don’t have enough engineers to specialize in front-end or back-end, most of the roles listed are for full-stack engineers, often listed as senior level.

This all makes sense but it can be discouraging. I’m pretty specialized in the front-end, and I shied away from applying to some roles because I wasn’t confident enough in my back-end skills. This doesn’t mean that you can’t find a front-end specific role—they’re certainly out there—but it just takes a bit more patience to find them. I guarantee you that they’re there—I managed to apply to several—there just aren’t as many as full-stack. It can be demotivating at times, but be persistent!

Wrapping up

One thing I didn’t talk about yet is how I prepared for the coding interviews or what those were like. I’ll write a follow-up post to cover that. But in the meantime, if you have any questions, please feel free to reach out to me on Twitter. I’m more than happy to talk about this process if it helps other folks make the switch!

In this post, I’ve done a write-up on tools and techniques I use in my day-to-day work. This is a snapshot of my process in 2021, but I may revise it in the future.

• Todoist
• Pinboard
• Aggressively closing Chrome tabs
• Alfred multi-clipboard
• Notion (or maybe Obsidian?)
• Brain.fm
• GitHub notifications

First, a bit about me

I currently work on two content sites at Google, web.dev and developer.chrome.com. I also manage a geographically distributed team of three engineers who sit in the Bay Area, Sydney, and Zurich. Time zones are my enemy. ⏰

I spend most of my day either helping authors in our team chat, jumping between GitHub projects, in meetings 😵, or planning “What’s next” for our team. When things are going well and I’m being organized my workflow and tooling look something like this:

Todoist

I’ve tried a lot of project management tools—and at Google, we have some of our own—but since I work across projects it means my tasks are spread between GitHub issues, various kanban boards, and spreadsheets.

What I found helpful about Todoist is that I can give myself a personal project management tool, which acts as a layer on top of all of the other tools I use.

Todoist has a lot of features but I only use a handful of them: priorities, scheduled tasks, and project boards.

Priorities let me quickly dash out if I think a task is a p1 (very important) or a p3 (less important) and Todoist will color code and sort them accordingly.

Scheduled tasks let me file an idea away for later.

For example, if I write “Wash the dog tomorrow”, it will move the task out of my view and tuck it away until tomorrow.

Recently Todoist added kanban style project boards, which didn’t interest me at first because I like the simple list view. But I realized I could use priorities and scheduled tasks as project subtasks and get the best of both worlds.

If I have a big project I’ll create a card for it and break it into scheduled subtasks, when the date arrives the subtask gets added to my Today list.

Usually on Monday I’ll look at all of my project boards and triage the subtasks, assigning them to a day of the week and a priority. As new tasks crop up that are unrelated to my bigger projects, like a sudden important email I need to follow up on, I’ll add it to my Today list. This way the priority tasks for my week are on auto-pilot and I can let my brain context switch without worrying that I’ll drop the ball.

I’m not dogmatic with this setup, sometimes I get really busy and end up brain dumping 20 items into my Todoist Inbox and then triaging them later. The important point is that I’ve gotten into the habit of checking this tool at least once a day, and cleaning it up at least once a week.

If you’re interested in giving Todoist a try you can use my referral code and I’ll get a few months for free 🤝

Pinboard

Pinboard is a minimalist bookmark tracker. It sort of looks like Craigslist.

It has a simple browser extension you can use to bookmark something and assign it tags. Then, months or weeks later, you can go back to your pinboard and track it down again.

Combining Todoist and Pinboard leads me to my first productivity win:

Aggressively closing Chrome tabs

If I have more than a handful of Chrome tabs open I start to get overwhelmed. I know folks often have a hard time closing their tabs but I’ve found having a combination of a good to-do list and a bookmark list helps me mentally file stuff away for later. If it’s important I’ll assign it a task and either drop the link in the task as a comment or pin it.

Then I close the tab. 💆‍♂️💆‍♂️💆‍♂️

If I don’t do this then I feel like I’m staring at a wall of cognitive debt. If I file the tab away I know I’ve triaged it and it doesn’t tug at my focus when I’m trying to complete something else.

One tip is to use pinned tabs in Chrome for things that you leave open all day like Gmail, chat, or calendars. Here’s what my tab bar usually looks like:

Alfred multi-clipboard

With a multi-clipboard, you can copy as many chunks of text as you want and then use a shortcut to open a little window so you can search and paste the right one. It will also keep track of your screenshots.

I use Alfred for this but there are other tools that do something similar.

If I’m going to attempt something sketchy in a file I’ll Select All and hit copy so I know I have a backup in case things go wrong.

The built-in search is quite handy as I’ll often remember a something from a week ago and I can usually dial it up with fuzzy search. Plus you can create handy snippets for emotes ʕ•ᴥ•ʔ

Notion (or maybe Obsidian?)

Sometimes you just need a big notebook to braindump ideas. In the past, I’ve used Evernote and tried Bear. Currently I use Notion.

I’ve found that while Notion looks great, I don’t use the majority of its features, and text selection can make the authoring process clunky.

I’ve started looking into Obsidian after seeing Andy Bell switch to it on Twitter. I like that it’s just a simple markdown tool that organizes things into a kind of brain wiki similar to Roam. Importantly Obsidian is free and all of the content stays on my machine as markdown files—so I don’t have to worry that I’m sending these ✨brilliant thoughts✨ to a third-party.

Brain.fm

I can’t concentrate if the music I’m listening to has words in it. For a while, I’ve used the Spotify Focus playlists but discovered Brain.fm after Sara Soueidan mentioned she uses it.

Brain.fm uses 🧪 science music 🧬 which sounds a lot like your typical focus playlist but it has this subtle warbling sound. They claim it makes your brain neurons do a happy dance.

Brain.fm holds patents on key processes for creating functional music, including technology to elicit strong neural phase locking—allowing populations of neurons to engage in various kinds of coordinated activity—and technology to remove distraction in sound.

It’s a pretty simple dashboard where you choose the type of music you want and then it plays a song for a few hours.

I did the free trial, didn’t think much of it, and went back to Spotify. But after a few days, I was like “Dang, I feel like my phases aren’t locking like they used to!” so I became a paying customer. I have no idea if the science works but I listen to it every day.

If you have neural phase envy, you can use my referral code to try Brain.fm 🧠

GitHub notifications

I used to filter all of my GitHub notifications to my email but I found it annoying because I couldn’t differentiate between a new issue, a mention, or an assignment. A while back GitHub redid their notifications dashboard and made it more of an inbox of sorts with keyboard shortcuts to jump between notifications and archive them.

I should probably do more to configure it, but right now I mainly use the Assigned and Mentioned tabs. Separately I’ll scan through the PR tabs on any of my open projects and handle reviews there. I wish GitHub would let me automatically archive reviews once a PR is merged so I don’t end up with a backlog saying I have 122 reviews to look at.

That’s it!

This was a very tools focused post, but I’d like to do a follow up about other work behaviors I’ve been trying to improve on like cutting down on coffee, scheduling recurring blocks for mindfulness meditation, etc.

If you found any of these tips helpful give me a shout on Twitter!

A while back I was working with a fellow Googler to try and improve the accessibility for one of our apps. In the scenario, a user needed to click some UI, which then opened a panel, where the user needed to click more UI to perform an action.

Helping a screen reader navigate these various UI states is a tricky technique known as focus management.Focus management is when you manually direct the user’s keyboard and screen reader cursor as they use the app. For example, if clicking a piece of UI loads more content into the page, then you need to tell the screen reader that this new content is available.

Because the web does not have a built-in tool for doing focus management, this is often left as a design exercise involving clever uses of tabindex, the focus() method, and a lot of guesswork.

Look up

As my teammate and I were discussing how to move focus into the next panel, he mentioned something that got me thinking. He said that he wished web apps had menu bars like desktop apps.

You know, like the File and Edit menus in Outlook. I can do anything I want with those!

It had never occurred to me how much I take the OS menu bar for granted and how powerful of an accessibility tool it can be. Instead of forcing the user to learn a bunch of UI states—which are different for each app—the menu bar is a common affordance for executing commands.

So why don’t web apps have menu bars? Especially if they could improve the accessibility for our users?

There might be a few reasons for this:

• The OS menu bar is presented separately from the app, which lives in a window. Web apps don’t have this capability because they run inside of a browser which already has a menu bar.
• In addition to the browser’s menu bar, there’s also a URL bar and associated controls. Adding another menu bar may feel cluttered.
• Every website would have to solve this for themselves. It would be hard to create the consistent experience of OS menu bars.

It’s worth noting that some web apps do support their own menu bar—Google Docs for example—but I think that’s because they’re following in the well worn footprints of their native counterparts.

In general the menu bar is not a common pattern across the web. Instead, we tend to hide controls behind hamburger menus or cryptic settings icons. So if it’s design prohibitive to add menu bars to every web app, is there a better alternative?

Help!

One of the most interesting and (literally) helpful buttons in the menu bar is Help. In particular, the Search field in the Help menu which acts as a command palette. Start typing in a command, and it will find it for you.

You can reach commands that do not have an associated keyboard shortcuts this way. And fuzzy search lets you guess the name of the command if you’re unsure.

On the Mac you press CMD + SHIFT + / to open the Help menu. This means a user only needs to know one shortcut to access most of the functionality of any desktop app!

Thinking about this made a little lightbulb go off in my head 💡

Why don’t web apps use command palettes to emulate the best parts of the OS menu bar? They’re a simple UI—just a modal autocomplete—that could have a big impact for users!

An example

As a Googler, I live inside of the Gmail web app. Because the app has so much functionality, the Gmail team has provided a large set of keyboard shortcuts.

But shortcuts can be difficult to remember and typically only cover a subset of the functionality of an app.

Adding a Gmail filter is a task I do occasionally, but not frequently enough to remember a keyboard shortcut (btw, there isn’t one). And I always forget which settings menu it lives in. As it turns out, the command to add a filter is buried a few screens deep, creating a focus management conundrum. Wouldn’t it be a better experience if I could type CMD + SHIFT + P and "filter" to go straight there?

Could this improve the experience for users of assistive technology by giving them direct access to all of the commands an app supports—especially those tucked away in hard to discover modals and submenus?

While it’s important to still do the work of managing focus between states; providing a command palette as an additional affordance might have a big impact on UX.

Has this been tried before?

Sort of.

Alice Boxhall showed me both the command and menuitem elements which were designed for creating custom context menus. Similarly there is the contextmenu event which you can use today to create your own custom menu—but the event only fires if the user right-clicks or presses the context menu key.

I think the context menu route is not the path we want to take.

I think what we want is closer to what VS Code and other editors provide. A fuzzy search text field that can be summoned by a single command.

How we go about doing this is an open question. My naive guess is that we might want browsers to standardize a command palette keyboard shortcut, like CMD/CTRL + SHIFT + P that triggers a commandpalette event. Triggering this event could also be done directly through assistive technology in whatever way is most efficient for the user.

It would be nice if there was a built-in, easy to style HTML element for handling the fuzzy text input, but designing that is its own can of worms 😅

Closing thoughts

Focus management is hard and there’s no agreed upon way to do it. While it is important to ensure that every UI state in your app is keyboard and screen reader accessible, it feels like command palettes could be a nice, additional UI affordance that all users would benefit from.

I’m curious to know if this idea resonates with folks. Let me know your thoughts on twitter and thanks for reading!

This will require nuking your old server—which sounds scary, but is so much easier than upgrading it in place. If all you’re doing is running Ghost then it may be no big loss—it wasn’t for me at least 😛

If you’re doing a bunch of other stuff on your server then you may want to try a different guide.

It’s also worth mentioning that in this post I’ll use a one-click Ghost install on Digital Ocean so I don’t have to deal with setting everything up myself. I am lazy 🤤

Backup

1. Go to the Labs section of your Ghost admin page (yourblog.com/ghost) and click export to get your JSON data. You’ll use this to recreate your posts.
2. Download your images. The easiest way to do this is with scp. Here’s a little cheatsheet if you’re unfamiliar with it.

cd /var/www/ghost/content
sudo zip -r images.zip images    
scp YOUR_USERNAME@YOUR_SERVER_IP:/var/www/ghost/images.zip /local/path/to/file

You can attempt to download your theme as well but if you’re going from 0.x to 2.0 I think there’s a really good chance it will not work.

Locally migrate your post data

This step is key. You can’t just import Ghost 0.x data into a Ghost 2.0 blog. You first have to import it into a Ghost 1.0 blog, export it again, and import that JSON into the 2.0 blog.

I tried to setup Ghost 1.0 on my previous server but it was a pain. I was running Ubuntu 14 but Ghost CLI will blow up if you’re not running Ubuntu 16 or above. Better to just do these steps locally.

You’ll need to install the ghost-cli and create a local version of Ghost 1.0. You’ll also want to make sure you’re running Node 8 or above.

node --version # hopfully >=8, otherwise upgrade node first
npm install -g ghost-cli
mkdir ghost-v1
cd ghost-v1
ghost install --v1

This should fire up a server on localhost that you can access to setup your blog. Once you’ve done that, go to the Labs section of the Ghost admin page and import the JSON you downloaded earlier. You may see some warnings but I was able to safely ignore these. They seem related to duplicate content from 0.x to 1.0.

You can also replace the content/images directory with the one you downloaded from your old server.

If all goes well you should be able to preview your content in the Ghost 1.0 casper theme.

Finally, in the Labs section use the export command to retrieve your Ghost 1.0 JSON. You don’t need to mess with the images because Ghost 0.x, 1.0, and 2.0 all seem to use the same directory structure for /images.

Create a new Droplet

If you use DigitalOcean or another service that provides one-click installs, now’s the time to create a new Ghost 2.0 instance, ideally running on Ubuntu 18.

Grab the IP for the new server but don’t log into it just yet.

Setup DNS and SSL

Go to your domain registrar and update your records to point at the IP for your new server. If you have a simple setup then you may just need to update the A record. It will take a while for the DNS to propagate (~15 minutes to an hour).

You can use a DNS checker to verify that the domain is pointing at your server’s IP.

Login to the new server

When you first login the server should kickoff the ghost CLI install step. It will walk you through a few steps similar to the ones you did during the previous local install. Once it’s finished, sign in to your Ghost admin, import your JSON, and use scp to copy over your images.

If all goes according to plan then you should be done. Yay! 🎉

As a last step you should consider doing some server hardening on your new Ghost instance. This guide by Rob Ferguson seems like a good next step.

I hope this blog post helps those of you in the same boat as me. Good luck!

Is there a list somewhere of which HTML elements can and can’t have a shadow DOM?

As it turns out, there is! (Big thanks to Anne van Kesteren for showing us the way).

If context object’s local name is not a valid custom element name, article, aside, blockquote, body, div, footer, h1, h2, h3, h4, h5, h6, header, main, nav, p, section, or span, then throw a NotSupportedError``DOMException.

Here’s a quick example using div:

Exceptions

It’s worth calling out that button, input, select, img, and a are not on this list and will throw an error if you try to attach a shadow root to them. If you need to use them you’ll probably need to look into either wrapping these elements or using a type extension.

This idea, testing a screen reader, proved much harder than I thought. It’s actually a bit of a holy grail in the accessibility space. Something that many have dreamed of, but few—if any—have achieved.

To understand why this is, it helps to know a bit about the process your page goes through when it finally gets announced by a screen reader.

The Accessibility Tree

When Chrome parses the DOM and the CSSOM it produces a tree of nodes. You may have heard folks on my team refer to this as the render tree. It tells the browser what to paint on screen, and when to omit things hidden by CSS.

But what many don’t know is that during this process there’s a second tree created called the accessibility tree. This tree removes all the nodes which are semantically uninteresting and computes the roles/states/properties for the remaining nodes. Similar to the render tree, it will also remove nodes hidden by CSS.

So, given the following HTML:

<html>
  <head>
    <title>How old are you?</title>
  </head>
  <body>
    <label for="age">Age</label>
    <input id="age" name="age" value="42" />
    <div>
      <button>Back</button>
      <button>Next</button>
    </div>
  </body>
</html>

Chrome would produce an accessibility tree that looks something like:

id=1 role=WebArea name="How old are you?"
    id=2 role=Label name="Age"
    id=3 role=TextField labelledByIds=[2] value="42"
    id=4 role=Group
        id=5 role=Button name="Back"
        id=6 role=Button name="Next"

Next Chrome needs to convert these nodes into something the user’s operating system can understand. On Windows it will produce a tree of IAccessible objects, and on macOS it will use NSAccessibility objects. Finally, this tree of OS-specific nodes gets handed off to a screen reader, which interprets it, and chooses what to say.

If you’re really interested, you can check out this doc which explains a lot more about how accessibility works in Chromium.

So it’s pretty tricky to know what any specific browser + OS + screen reader combo will announce. There are differences in how each browser builds its accessibility tree, there are differences in how well each browser supports ARIA, and there are differences in how the various screen readers interpret the information browsers give to them. Oof!

So how do we test this stuff?

Rather than test what a screen reader announces, a better place to start might be to test the accessibility tree itself. This avoids some of the layers of indirection mentioned above.

If you follow me on twitter, you’ve probably heard me mention a new standard we’re working on called the Accessibility Object Model or “AOM”, for short. There are a number of features AOM seeks to achieve, but one that I’m most excited about is the ability to compute the accessibility information for a given node.

const {role} = await window.getComputedAccessibleNode(element);
assert(role, 'button');

Note, this API is still being sketched out so the final version may be different from the snippet above.

When this lands (hopefully in 2018) we should be able to start writing unit and integration tests that ensure our components are properly represented in the browser’s accessibility tree. That’s pretty darn close to Holy Grail territory!

Aside from AOM, there are linters and auditors we can use today, like eslint-plugin-jsx-a11y, Lighthouse, axe, and pa11y. Ultimately we’ll want to use a combination of these tools plus AOM tests to monitor the accessibility of our apps. If you haven’t seen Jesse Beach’s talk, Scaling accessibility improvements with tools and process at Facebook, I recommend you give it a look to see how an organization the size of Facebook is integrating these tools into their process.

To wrap up, I think testing the output of a screen reader may still be a ways off, but in 2018 we’re going to have more tools in our toolbox than ever before. If you want to learn more about accessibility fundamentals you can check out this free Udacity course and if you’d like to start incorporating more accessibility work into your team practice take a look at my session from this year’s Google I/O. I’m really excited to see what you all build in 2018 😁

Happy new year!

Rob

Politics

The year opened with a lot of protests and rallies. We rallied at the SF city hall, the Women’s March in Oakland, at San Francisco Airport, and even at the Google Campus. It was intense. When the riot police showed up at SFO while folks were banging on the security barriers I wondered if it was only a matter of time before they tear gassed us. Thankfully that didn’t happen.

2017 made me realize how much we’ve been asleep at the wheel, just letting politics happen, assuming that somehow it would all work out in the end. I’m very thankful for organizations like Run for Something, SwingLeft, Indivisible, and Crooked Media. If I had to recommend one person to follow on twitter it would be Celeste Pewter. I love her daily briefings, and 2017 was the first year I started phoning my reps to tell them when I thought they were doing good (or bad).

Travel

I went to Australia, Peru, Denmark, Japan, and Rwanda. Each of these trips was an awesome adventure. I realize I’ve now been to every continent except Antartica, which I really want to go to. To be 100% honest, I’m not the best traveler. I get really anxious when I don’t speak the language, and nervous about walking around a city I don’t know. Over time I’ve gotten better about this and in 2017 I started to feel more comfortable in unfamiliar places. But I think I still have a ways to go before I’m fully embracing the whole globetrotter thing.

Work

On the work front, I took on more of an ownership role for both Web Components and Accessibility. I co-presented at CSUN and worked the Google booth—which was super fun! I think the most rewarding thing this past year has been all the folks who meet me for the first time and say “I did your accessibility course on Udacity!” It took Alice and I about a year to put that course together. It was so.**much.**work. We would send each other messages like “oh god I still have 30 slides to make [cries face down on the floor].” But we toughed it out, and even though there are bits I’d like to improve upon, I’m pretty happy with the result.

Speaking of Alice, I wanted to thank her for helping me so much in 2017. Not only did she introduce me to the topic of accessibility, and basically teach me everything I know, but she also:

• Proofread and edited my blog posts before they went out. Making major revisions so they sounded much smarter than originally authored.
• Helped lead the AOM, :focus-ring, and inert standards discussions and polyfills.
• Shipped new accessibility devtools in Chrome which everyone can use in version 63.
• And, helped teach me C++ (more on this in a moment).

She’s just awesome, and an incredibly strong person who has really pushed me to see the world differently. Thank you Alice!

At the tail end of the year I was promoted (yay!) so I’m now a “Staff Developer Advocate”. On January 13th, I’ll have been at Google for four years, which is the longest I’ve ever worked at the same place. I love my job and the opportunity it affords me to just go all in on the things I’m excited about. The folks around me are awesome and always supportive and pushing me to be better. I really am lucky to have such amazing coworkers and I’m very excited to work with the new folks who will be joining the team in 2018.

Hello, 2018!

Personal stuff

In December my wife accepted a job at Highland Hospital in Oakland, so soon we’ll be moving from Palo Alto up to either Oakland or Berkeley. For years we’ve been unable to really put down roots because with medical school, residency, possible fellowship, etc. it was always assumed that every three years we would need to move to a new city. But now that she’s accepted a full time role at Highland, we know we’ll be staying in the Bay Area. I am stoked.

Work

To start the year I’ll be doing a software engineering rotation with the Chrome Accessibility team. This means I’ll spend all of Q1 acting as a member of their team instead of working in developer relations. I’ve been picking up as much C++ as I can, and trying to wrap my head around Chromium. I’m a bit nervous because I’ve never worked in C++ and I really want to do a good job. I’m excited because I’ll get to work directly on a few things I’ve been evangelizing and when I switch back to developer relations, later in the year, I’ll have a much deeper understanding of accessibility. I’m thrilled to talk about all the things I don’t even know about yet!

Politics

2018 feels like a really momentous year to me. I am excited and nervous at the same time. Obviously the political scene is going to be an all out slugfest, but I’m looking forward to that. Upon reflection, I think we needed this wake up call so we could get our act together when it comes to things like universal healthcare. It’s deeply unpleasant having Donald Trump as president, but U.S. politics is cyclical, and in 2018 we push back.

Resolutions

When it comes to resolutions I prefer having very specific goals, as opposed to really broad things like “work out more”. I think when you have an actual target then you can feel yourself making progress and that measure of progress becomes its own motivating factor.

Let’s start with the exciting personal stuff:

Buy a house.

Yes, Bay Area housing prices are… steep, to put it mildly, but my wife and I have been saving up for a few years and we’re really excited to finally own a place of our own. There’s all sorts of nerdy things I want to do, like put up solar panels. Stuff you just can’t really do with a rental. But most importantly, it will unlock my next resolution…

Get a doggo (or 2).

It’s actually really hard to find a rental in the Bay Area that will allow dogs. This sucks because I love dogs. If you follow me on twitter you may have noticed that my feed is like 90% dog gifs, and 20% web stuff and politics. I really want to get two dogs because I want to make sure they each have a buddy. I have already decided on their names. This is happening.

Create an Instagram account

OK I realize this isn’t that exciting and that I’m the last person to not have an Instagram account. Currently my phone has a ton of travel photos but I never share them. It seems kind of silly to take all these photos and never really look at them or share them with anyone. In 2018 I plan to change that. Get ready to be spammed.

Dress better.

There’s just something about walking into an important meeting with a shirt that says “Trust me, I’m a dogtor” that makes me think people aren’t taking me seriously. So no more t-shirts with random company logos, or hoodies.

Run a half marathon.

In 2017 (or maybe it was 2016?) I started the year with a goal of being able to consistently run a 5K. Prior to that, I’d maybe jog once a year, hate it—deeply, and then resolve to getting swole some other way. But working toward that 5K goal really helped me develop a love of running. I still get shin splints if I run too frequently, and I’ve been a couch potato cuz it’s cold outside, but in 2018 I’m setting out to do a half marathon. One thing I’ve recently discovered is listening to books on tape while you run is pretty awesome. I’m currently listening to Too Far From Home and really enjoying it.

Boulder at a V4 level.

I started bouldering a few years ago, and over the past year I’ve managed to get up to where I can climb some V3s. I’m not going consistently enough right now, so that has to change if I want to get to the V4 level. Maybe 2-3 times a week would be enough.

Write a will and document my medical directives.

OK, so this is one of those very unfun adult things that nobody wants to do but both are incredibly important. Because my wife works inpatient medicine (meaning, inside the hospital) I’ve heard countless stories of families being in a situation where they have to decide whether or not to intubate someone. Thinking about this stuff is scary, but it would break my heart for my wife or family to be in a situation where they have to make a decision about me and they don’t know what my wishes are. To spare my loved ones any undue anguish, I want to make sure I have all this stuff sorted out, just in case.

Volunteer at organizations to promote inclusivity in tech.

Our industry is a total monoculture. I’m not happy with the current state of things and I want to do my part to change that. In 2018 I plan to find organizations that help promote diversity and inclusivity in tech, and do whatever I can to help them out. This could include speaking, or being a teaching assistant, or connecting those groups with folks at Google who work in their area of interest. Whatever it takes, I want to make sure I’m moving the needle on this.

Get (even more) involved in politics.

Obviously this year is a big one because of the midterm elections. In California we have the “Crooked Seven” that need to be voted out of office. This is where I’ll be focusing all of my political energy. Text or phone banking, maybe driving over to Modesto to knock on doors, whatever it takes.

Release a game a quarter.

I’ve always secretly dreamed of being an indie game maker. When I read Dave Rupert’s 2017 year in review he mentioned that he (secretly) has been trying to release a game a quarter. I think this is a great goal and one I’m planning to aspire to as well. I figure the games don’t have to be big, but they do have to be “complete” which means pushing through all the unfun bits. I’ve already started making my first game, a simple tilt maze and I have a ton of ideas for where I’d want to take it. The hard part will be editing that list down, and doing the production work to actually create a handful of levels and something that feels like it has a beginning, middle, and end.

ONWARD!

This post ended up being way longer than I originally expected. I guess that’s what happens when you drink too much coffee and have the house all to yourself. I’m really looking forward to this year and hope you are too. Now it’s time to go work on that half marathon. Happy new year! 👟

For example, if a screen reader visits a login button:

<button>Sign in</button>

—it would announce, “Sign in, button”. This tells the user about the affordance available to them—whether something is a button that may be pressed, for example, or if it’s just a block of text content with no other semantics.

Additionally, built-in elements support keyboard-based usage, which is important for users who can’t use a pointing device—whether they are unable to see the pointer, or don’t have the physical ability. This is why accessibility experts always urge developers to mark up their pages with the built-in elements.

Custom elements, by contrast, have no implicit semantics or keyboard support.

When you define a new tag, the browser really has no way of knowing if you’re trying to build a button, or a slider, or just a fancy text container. Adding these features back in requires a fair bit of work on the developer’s part and it can be difficult to reach parity with the native equivalents.

<howto-component>

Recently we launched a project called HowTo: Components which demonstrates how to build accessible custom elements. Many folks have since asked us why we’re bothering to implement things like checkbox since there is already an accessible, native version.

Taking an even cursory look at any web framework shows that developers are going to keep building custom checkboxes, even though it’s arguably more work than using a built-in element. We’ll get to why that is in a moment, but given that’s the case, we’d like to educate developers on the best practices for doing so. Here we take inspiration from the ARIA Authoring Practices Guide, and in fact all of the HowTo: Components are based on their examples. We just want to illustrate how to do them as custom elements.

So, why do developers keep reinventing this wheel?

Built-in elements are great. Until you try to style them.

<input> is like the Swiss Army Knife of elements. It contains multiple different types (text, date, file…) and each of them is difficult to style. Have you ever tried to style an <input type="file">? It sucks. Here’s how Mark Otto, co-creator of Bootstrap, recommends styling them on his site, wtfforms:

The file input is the most gnarly of the bunch. Here’s how it works:

• We wrap the <input> in a <label> so the custom control properly triggers the file browser.
• We hide the default file <input> via opacity.
• We use :after to generate a custom background and directive (Choose file…).
• We use :before to generate and position the Browse button.
• We declare a height on the <input> for proper spacing for surrounding content.
• We add an explicit label text for assistive technologies with an aria-label attribute.

In other words, it’s an entirely custom element, all generated via CSS.

Not fun. I think a large reason so many sites are inaccessible is because developers run into these styling limitations and decide to just roll their own controls—without adding back in the necessary semantics and keyboard support.

So why is it so hard to style the built-in form elements? Can’t browsers make this as easy as styling a <div> or an <h1>?

Not really. Elements like <input> and <select> aren’t always implemented in terms of regular DOM elements. Sometimes they are, which is why there are articles on CSS hacks for styling <input type="range">. Other times they are rendered directly by the operating system - this is why a standard <select> comes up looking like any other native drop-down list on the platform you’re using. They are specified as a kind of black box, meaning it’s up to the browser to figure out their internals, so exposing styling hooks for them is quite difficult and often very limited. It is entirely possible that we may never be able to style these elements to the degree we want.

The alternative is to expose the magic behavior that these elements have as new web platform APIs. Not only will this allow us to create more flexible versions of <input> and <select>, but we can also expand the grammar to include other elements like <multi-select-autocomplete-thing>.

This is why I am so passionate about custom elements. In my mind, it is where the future of accessibility lives. I deeply want to be able to stop hacking CSS on top of <select>. I want to make my own badass, extensible, styleable, accessible elements that are just as good as the built-ins!

So as well as modeling best practices with today’s technologies, I’m hoping that HowTo: Components can help us identify areas where we can create better APIs for the next generation of web technology. We want to get to a point where we’re not forced to choose between the impossible task of styling the existing set of built-in elements, or the fiddly, error-prone and largely forgotten job of re-implementing accessibility for every new custom element.

How do we get there?

The first step is to make sure our custom elements have the right semantics.

I’m excited for the potential of the new Accessibility Object Model (AOM) proposal to help us out here. AOM lets an element define its semantics directly in the accessibility tree.

What’s the accessibility tree you ask? Ah ha! We have a article for you!

As I mentioned before, a custom element is, semantically speaking, just a <span>, whereas the native <button> element has built-in accessibility because it has an implicit role of “button”. While we could have our <custom-button> sprout ARIA attributes to define its semantics, this can get ugly fast. To recreate a <input type="slider"> as a custom element would end up looking like:

<custom-slider
  min="0"
  max="5"
  value="3"
  role="slider"
  tabindex="0"
  aria-valuemin="0"
  aria-valuemax="5"
  aria-valuenow="3"
  aria-valuetext="3"
></custom-slider>

And because ARIA is exclusively an HTML attributes API, it means we need to touch the DOM every time we want to update our semantic state. For an individual element this isn’t so bad, but if you have hundreds of controls (perhaps inside of a table or list), having each of them call setAttribute() multiple times at startup could lead to a performance bottleneck.

With AOM your element can just define its semantics in its constructor like so:

class CustomSlider extends HTMLElement {
  constructor() {
    super();
    this.accessibleNode.role = 'slider';
    this.accessibleNode.valueMin = 0;
    this.accessibleNode.valueMax = 5;
    this.accessibleNode.valueNow = 3;
    this.accessibleNode.valueText = 3;
  }
}

—and the consumer of your element doesn’t have to see it sprouting attributes all over the place. Effectively, <input type="slider"> and <custom-slider> become indistinguishable at the semantic level.

Some folks have even proposed giving custom elements access to a special “private” accessibleNode so the author can define immutable default semantics. This would mean that one could safely override an element’s role, then delete that override, and things would safely fallback. For example:

// default role is "slider"
// set using private accessibleNode by the element author
<custom-slider id="mySlider">

// element consumer changes role to "button"
mySlider.accessibleNode.role = "button"

// element consumer nulls role
mySlider.accessibleNode.role = null

// element falls back to default role
getComputedAccessibility(mySlider.accessibleNode).role // returns 'slider'

// note: the ability to compute the accessibility tree is
// a phase 4 AOM proposal. The line above is pseudo code :)

But wait, there’s more…

Another major pain point of using ARIA is the fact that all relationships must be defined using ID references. On numerous projects I’ve had to auto-generate unique IDs to make this system work:

<custom-listbox
  role="listbox"
  aria-describedby="generated-id1 generated-id2"
  aria-activedescendant="generated-id3"
></custom-listbox>

Furthermore, new standards like Shadow DOM create scoping boundaries for IDs. If you need to point aria-labelledby or aria-activedescendant at something on the other side of this shadow boundary, you’re out of luck!

AOM fixes this by allowing you to build relationships using object references. In the above example we could rewrite our listbox with:

el.accessibleNode.describedBy = new AccessibleNodeList([
  accessibleNode1,
  accessibleNode2,
]);
el.accessibleNode.activeDescendant = accessibleNode3;

The accessibleNodes in the above example just come from referencing other elements on the page. No more generated IDs or cluttering up the DOM. Nice!

Wait, wasn’t there something called is=”” for custom elements?

A counter proposal to adding all of these semantics yourself is to just inherit from the built-in elements. For custom elements this idea was specced as “customized built-ins”. With customized built-ins you could inherit from something like HTMLInputElement and then do <input is=”custom-checkbox”>.

Unfortunately customized built-ins have not really caught on with all of the browsers, mainly because they suffer from a few gnarly issues. Chief among these is the fact that if you inherit from another element like <select>, and add your own shadow root, it will blow away all of the default styling and behavior of the element. Since the primary reason you were extending the element in the first place was probably to style it, this just ends up creating more problems.

I think in the near term, new primitives like AOM and an as of yet unspecified form submission callback offer a better alternative when it comes to replicating the built-in elements. Because custom elements still require JavaScript to boot up there are still open questions around progressive enhancement, but my hope is that increasingly exposing primitives will help us find other ways to solve that issue.

Wrapping up

These are not entirely custom element concerns. Really, any component (React, Angular, etc) should be able to benefit from proposals like AOM. But custom elements are the only standards-based way to define a component that can be shared amongst frameworks, so solving things at that level seems very useful.

Our plan with HowTo: Components is to continue to build custom element equivalents of the built-ins so we can educate developers, and push these standards forward. We’ll also be updating the docs to explicitly call out the limitations custom elements currently face, and when using a built-in might make more sense. We would love help landing all of the ARIA Authoring Practices examples as custom elements and plan to push things even further in future quarters by exploring more complex widget types. If you’re interested in pitching in, please feel free to open up a pull request over at the HowTo: Components repo and if you want to learn more about AOM you can check it out in the Web Incubation Community Group repo.

Big thanks to Alice Boxhall, Matt Gaunt, and Surma for reviewing this blog post.

Over the last year I’ve had a number of discussions with mid to large sized companies who are interested in creating common UI libraries that all of their teams can share. Often these teams are on different stacks (React, Vue, Angular, etc.) so using something like Web Components and Polymer makes sense, as all of these frameworks can consume and communicate with Web Components.

Most frameworks tend to rely on ES Modules or CommonJS and tools like Webpack to bundle their code. Polymer, on the other hand, uses HTML Imports. This means developers who want to use the two together will need to reconcile how things get bundled and the order in which they’re loaded.

But Webpack can already understand multiple file formats (.css, .tsx, etc). So could it be extended to understand HTML imports? Sure, why not! Today I’m really excited to show off polymer-webpack-loader, a new tool which consumes HTML Imports and outputs modules ready for Webpack. Not only does this make it much easier to use Polymer with other frameworks, but it also adds interesting new features to Polymer like the ability to use ES Module import syntax to pull in code installed via npm.

Before I get too ahead of myself I want to point out that this is not an official Polymer project—Polymer isn’t “going all in on Webpack” or anything like that—this is just an awesome tool created by two community members, Bryan Coulter and Chad Killingsworth, that solves a pain point a number of developers have encountered. Although the project is still in a beta phase, I thought it would be cool to do a short write up so members of the Polymer community can kick the tires and give it some feedback.

Who is this for?

Before jumping into the nitty gritty, I wanted to first identify which users would benefit the most from this tool. If you’re already using the Polymer CLI or polymer-build, and you’re happy with your project, then by all means stick with them! They’re great tools that do awesome stuff 😁

polymer-webpack-loader will be most beneficial for anyone who:

• Is integrating Polymer elements as part of a larger project that uses a different framework.
• Wants to use import syntax to leverage npm packages in their Polymer elements.
• Wants to use TypeScript, JSX, emojiscript, [insert yr FancyScript of choice].

How does it work?

polymer-webpack-loader takes an HTML Import file and converts the entire thing into a JavaScript module. It does this in three steps:

Step 1. Convert <link>'s

All <link> elements are converted to ES Module import statements. For example <link rel="import" href="paper-button.html"> becomes import ‘paper-button.html’; That might seem a little weird but remember, everything is a module in Webpack, even HTML and CSS files. By converting <link> elements to import statements, Webpack is able to crawl the rest of our dependency graph.

Step 2. Turn <dom-module>’s into string templates

Polymer’s <dom-module> is a Custom Element which captures its contained template and places it inside of a global map. Whenever a Polymer element is created, the first thing it does is find its template in this map and stamp it out. The polymer-webpack-loader just takes the contents of your <dom-module> and converts them into a string template which will get imported when the bundle is executed. Essentially it achieves the same end—a global map is created so the element’s template is accessible—but does so in a slightly different fashion.

Step 3. Separate out <script> elements

Finally any <script> tags which contain a valid src attribute are converted to 'import' statements. Inline scripts are separated out and made available to other loaders in the chain (like babel-loader or ts-loader). Finally, they get tossed into the bundle.js along with everything else.

At the end of all this we should end up with a bundle.js with all of our elements and any other dependencies compiled into it.

Let’s do a hello world!

I’ve created a tiny demo project so you can follow along.

To get started with the loader, install it from npm.

npm install --save-dev polymer-webpack-loader

Or if you’re using the demo project, cd into the demo directory and run npm i and
bower i.

Next, drop the loader into your webpack.config.js, here’s the full config file from the demo. I’ve done my best to comment each section so if you’re new to Webpack you can grok what’s going on.

The key thing to note is the module section where we define the rules array. The first rule tests to see if a file ends in .html, if so, it gets sent to a set of chained loaders. Loaders transform a file in some way, similar to “tasks” in other build tools. Here we’re saying “run everything through polymer-webpack-loader, take the output from that and give it to babel-loader.”

Next we’ll need to give our app a starting point, so create an index.js file and include an import statement to pull in an HTML Import.

/* src/index.js */

import './my-element.html';

And here’s the actual definition for my-element.html.

my-element.html, is a fairly plain Polymer element with one interesting feature. In the <script> element I’m importing the date-fns library. Webpack will resolve this to the version in my node_modules directory and compile it into my bundle, which is pretty sweet. Finally we can leverage properly scoped modules in our element definitions!

The last thing we need to do is throw together an index.ejs which will be served by the Webpack dev server.

The index.ejs loads the Custom Elements ES5 adapter, Web Components polyfills, and the bundle.js created by Webpack. It also contains an instance of <my-element> in the <body>.

Not sure what that Custom Elements ES5 Adapter is all about? Check out this clip for the full explanation.

Note the line that says <%= htmlWebpackPlugin.files.js[0] %>, as this is where our bundle.js will end up.

Finally, in the terminal run npm start to kickoff the Webpack dev server which will open a browser window for you. You should see something like this:

Success! You’ve now got Polymer bundling with Webpack and leveraging imports from your node_modules directory.

Open questions

Can I publish elements I create using the loader to WebComponents.org?

It depends. If you’re taking advantage of ES Module import syntax to pull in npm packages, then no. Otherwise anyone who wants to use your element would be required to also use Webpack. I think this tool is best used for handling code in your own application and for elements that you don’t intend to share.

Does this mean I don’t have to use bower anymore?

Not really. The primary reason Polymer, and Web Components in general, rely on bower is because Custom Element tag names are global. This means you can’t have multiple conflicting versions of an element trying to be registered at once. Bower enforces deduplicating version conflicts at install time so you always end up with one version of a dependency. npm does not support this same feature, so for the time being it’s probably best to continue using bower to install your Web Components. If you’re curious to learn more about this check out this clip from one of my recent I/O talks.

What about PRPL / code splitting?

One of my favorite features of HTML Imports is that it encourages you to colocate all of the HTML, CSS, and JavaScript for a component into a single file. This makes it easy to separate components that are critical for first render, from those that can come later in the process. You can then use a tool like Polymer CLI to bundle your critical and noncritical components into separate “fragments”, and lazy load them with Polymer’s importHref method.

We can achieve the same effect in Webpack using a feature called Code Splitting. The authors of the polymer-webpack-loader have put together a nice Polymer Starter Kit example which demonstrates how to setup your Webpack configuration for code splitting, and how to swap out Polymer’s importHref method for Webpack’s dynamic import().

Conclusion

I think Custom Elements built with Polymer should absolutely work in any library or framework. But too often we hit bumps along the way, sometimes related to build tools, and it makes the entire process feel like more trouble than it’s worth. I’m really excited about polymer-webpack-loader because it addresses a major pain point I’ve experienced and I can’t wait to see more folks use it to bring Custom Elements into their project and share them across their teams.

Big thanks to Bryan Coulter and Chad Killingsworth for creating polymer-webpack-loader and Sean Larkin for reviewing this post.

tl;dr: jQuery plugins don’t work inside of Shadow DOM because typically they try to query for something starting at the document level and the shadow root blocks this.

A super handwavy explanation of jQuery plugins (featuring shitty drawings)

jQuery plugins work by latching on to an element, stamping a template inside of it, and then (often times) querying for items in that template using $().

For example, you might initialize a WYSIWG plugin like this:

<div class=".container"></div>
<script>
  $('.container').wysiwg({ // options });
</script>

At which point it will fill the .container element with some template markup.

Often times the plugin will want to reference specific nodes in the template to give them behaviors. In the above diagram the .foo element represents a footer with a few controls inside of it. The plugin may attempt to use $('.foo') to reach this element. It’s important to note that $('.foo') is equivalent to document.querySelector('.foo').

How is this different with Shadow DOM?

The primary thing to note about Shadow DOM is that it provides DOM encapsulation as well as style scoping.

In other words, you can’t query for something inside of a shadow root unless you start the query from within the shadow root itself. If you try to query from the document level (or really any point outside of the shadow root), the shadow boundary will block you.

This is actually an intended feature of Shadow DOM. I don’t know if you’ve ever been in a situation where you accidentally query something inside of a jQuery plugin (or maybe a plugin accidentally queries some other element on your page) but it can lead to breakages pretty fast. By encapsulating a component’s DOM we can prevent such scenarios from happening. This also means that components built with Shadow DOM can be safely dropped into big framework apps and they won’t blow up the world.

But the plugin works in Firefox!

Complicating this whole issue is the fact that effectively polyfilling Shadow DOM can be pretty tricky. As a result folks might see a situation where the plugin seems to work in Firefox (which currently does not support Shadow DOM) but breaks in Chrome or Safari. If you’re seeing this behavior then you’re almost certainly running into a situation where native Shadow DOM is preventing the plugin from querying something inside of a shadow root.

So… how do I fix it?

Yeah this is where things get a bit tricky. There’s no silver bullet fix to this issue. If you’re putting a jQuery plugin inside of a component’s Shadow DOM, then your component is probably too big. See if you can factor it down into smaller pieces. Maybe the plugin could end up being a leaf node that just sits along side your other Web Components.

Another alternative is to see if you can distribute the plugin as a “Light DOM” child of the component using Shadow DOM’s <slot> element. You’ll need to write some extra code to get access to your distributed children and install listeners on them, but this might be a workable solution depending on how your page is setup.

Conclusion

jQuery plugins are great but they were created in an era before Shadow DOM. Trying to mix the two will more often than not lead to bugs and confusion. If you’re having a hard time getting them to work in your app, ask yourself if everything needs to be in the Shadow DOM, or if it might be better to only use Shadow DOM for the UI components where you know you want a strong encapsulation boundary.

After years of effort Web Components have been a waste of time

Something I’ve learned from working with the Chrome team is that browser makers view shipping something in the platform very differently from the web dev audience. Once you ship something in the browser, the assumption is it’s there “forever”, at a minimum several years, possibly decades. This means big changes are often undertaken in a slow process that to outside observers feels downright glacial.

Web Components are a big change and as a result they’ve moved pretty slowly. Along the way some parts got dropped or reworked but that’s a good thing. Using an ES6 Class instead of building a prototype Object to create a Custom Element is a much nicer approach, but required revising the Custom Elements spec. It’s frustrating because it delayed native Custom Element support for folks, but the final product is better.

I’d still like things to move faster, but in 2016 we saw Safari add support for Custom Elements and Shadow DOM, and it looks like Firefox may be on track to do the same in 2017 (fingers crossed). It’s taken a (very) long time, but I do think we’re getting close to having full cross-browser support soon.

React built a better mouse trap

React is awesome and drives a ton of discussion among folks who work on Web Components. My perspective is that the ideas in React and the ideas in Web Components are not mutually exclusive. Instead, we should roll those patterns into how we build components and make sure we have a good story for interoperability.

Whether you choose to use React or Web Components (or both) I think ultimately comes down to personal style and project constraints. Let’s say in another year or two Web Components become fully supported and you’re asked to build a UI library to scale across a huge company with tons of developers on different stacks. Web Components would fit that job very well. Or let’s say you’re a marketing agency making a site for a product launch. There’s only one team invovled and everyone is already familiar with React. It would make sense to just use React for the whole thing. There are a lot of scenarios that fall in between these two examples but really it comes down to using the right tool for the job.

As a bit of an aside, I also feel like a lot of folks often overlook the fact that libraries like Amp are in fact Web Components (specifically Custom Elements), and Amp is incredibly successful. Their elements are performant and meet a need for publishers. Often times the Web Components discussion descends into Framework X versus Framework Y, but taking a step back reveals there are other applications for these standards that we may have overlooked.

The DOM is slow

Abstractions like React/JSX which help you manage your DOM updates are great, but they don’t come free of cost. A major bottleneck for page load times is large javascript bundles being downloaded which then take a very long time to parse on underpowered mobile hardware. Here’s a great talk on the subject by my teammate Sam Saccone: https://www.youtube.com/watch?v=RWLzUnESylc

The important takeaway is that React (or really any library that provides an abstraction over the DOM, including Polymer) is not a silver bullet. If you end up shipping megabytes of slow-to-parse javascript, then you’ve just shifted the problem around. The fix is to make sure you’re splitting up your bundles, and only loading what you need, when you need it.

Using JSX and Virtual DOM is nicer than using DOM APIs directly

The DOM APIs are meant to be low level tools that we can build abstractions on top of. JSX is a great tool but the use case cited by the author (JSX + ReactDOM) is just sugar over the native DOM APIs. As a result, there’s no reason why you can’t use JSX with Web Components, and libraries like SkateJS do this today.

There’s no standardized data binding system

A frustration cited in the blog post is that there’s no standardized data binding system and that Polymer had to invent their own. Originally there was a proposed standard, called Model Driven Views, and (if I understand my history correctly) this is what Polymer’s binding system was originally based on. But this proposal never caught on. I’ve heard anecdotally that it was too difficult to get the various stakeholders (including framework authors) to agree on exactly how data binding should work in the platform.

Today many developers prefer the look of JSX to template bindings (MDV style) and with things like Observables and ES6 Proxies on the horizon, I’m not sure what this space will look like in a few years. It may just be too volatile to standardize right now. Competition in this space is a good thing though. Over time it helps us zero in on a solution that makes everyone happy.

Working with string attributes is annoying

Because a Custom Element is really just a class instance, you can (and should) provide a properties interface using ES6 class getters/setters. That way you don’t have to rely on attributes for anything other than initial configuration (if you want to). I wrote up a blog post on how to do this here.

This means properties (not attributes) can be the source of truth for your element. And libraries like Angular2 already support this in their binding system when communicating with Web Components.

Evangelizing component authoring best practices that use this approach is something I’m currently pursuing along with the help of my teammates so stay tuned for more in this department :)

Wrapping up

I completely understand the frustration expressed by the author in this post. As someone working on Web Components for years (and years) at this point I’m like “OMG CAN WE PLEASE BE DONE SOON!” But I’m actually more excited for the work I’m doing this year than I was in 2016.

I think we’re finally getting on solid footing when it comes to browsers shipping native implementations. The standards have stopped moving around so we can start publishing best practices. And folks are taking Web Components in new and interesting directions. I’ve already mentioned SkateJS, but just the other day I discovered Switzerland, and the Polymer team is close to releasing Polymer 2.0. Also the Amp team just wrapped up a two day conference where they showed off all the cool stuff they’ve been working on (videos available on their YouTube channel).

So yeah, as crazy as it sounds given how long things have taken, I think 2017 is going to be a good year for Web Components. There are still hard problems to tackle but I think we’ll get there. And just like any tool, the final result won’t be a panacea, but it will solve real problems and serve as a building block to address future issues in the platform.

In The Case for Custom Elements I pointed out that Custom Elements should be able to work in any context where HTML works. This includes being used by popular frameworks. To that end, the patterns I’m sharing in this post will not only help you write high quality components, but should also aid in framework interoperability. Specifically I’ll be referring to React and Angular 2 in this post as those are the ones I’m most familiar with, but ideally these patterns should benefit interoperability with all frameworks/libraries.

Use properties as your source of truth

Every HTML Element has the ability to receive state through its attributes and properties. Traditionally attributes are used to set the initial state of an element but they do not update as the element changes over time. For example:

<input type=”checkbox” checked>

The above line of code will render a checked checkbox. Clicking on the checkbox will uncheck it, however, the checked attribute will still exist in the DOM.

The same is true if you set a value attribute on a text input and then type in a new phrase. Calling getAttribute(‘value’) will produce the original (stale) attribute value. However, asking for the .value property will produce the correct result. In other words, attributes are useful for initial configuration, whereas properties are good for reflecting state. This leads to a few takeaways:

• The state of an element should always be determinable by its properties and it should not matter the order in which the properties are set.
• Every exposed attribute should have a corresponding property
• Updating an attribute should reflect that change to the property
• Updating a property should reflect back to an attribute only when it benefits styling, or perhaps accessibility (e.g. if you expose an API where setting a role property would reflect to an ARIA role attribute). If the property sets the corresponding attribute, and you’re using the attributeChangedCallback, you’ll want to add a guard to prevent an infinite loop.

Here’s an example element, a Custom Menu with a selected attribute/property, that adheres to the above pattern:

class CustomMenu extends HTMLElement {
  static get observedAttributes() {
    return ['selected'];
  }
  // Called anytime the 'selected' attribute is changed
  attributeChangedCallback(attrName, oldVal, newVal) {
    this[attrName] = newVal;
  }
  // Takes a numeric index value
  set selected(idx) {
    if (this._selected === idx) return;
    this._selected = idx;
    /* Update the DOM as necessary */
  }
  get selected() {
    return this._selected;
  }
}

This pattern becomes especially important when we think about interoperability with frameworks. Consider the following piece of code from Angular 2:

<custom-checkbox [checked]="item.inShoppingCart"></custom-checkbox>

This is a one-way data binding which sets the checked state of the element equal to a model value, in this case the inShoppingCart property of the item object. While it looks like we’re working with an attribute here, in actuality, Angular 2 is setting a property on the element. The above line of code is functionally equivalent to:

customCheckbox.checked = item.inShoppingCart;

Note: Angular 2 also provides special syntax for binding to attributes, but favors binding to properties.

One of the reasons frameworks prefer setting properties over attributes is because attributes can only pass string values, whereas many frameworks often need to pass more complex data like arrays and objects. To pass complex data with attributes would require serializing the data to JSON strings, setting those values on attributes, and then parsing that JSON on the other side to turn it back into an object. Using properties for everything avoids this extra work. This also highlights the need for a standards based way to declaratively serialize/deserialize data to/from something like attributes. Today libraries are forced to work around this limitation (either via JSX or data binding) but having an agreed upon way to declaratively pass complex data would be a big win for the platform.

Data out via events

Keep this mantra in mind: “data in via attributes and properties, data out via events”.

We’ve already covered how to get data into an element, now let’s talk about how we tell the outside world that our state has changed.

The DOM provides an easy mechanism for dispatching events in the form of the CustomEvent constructor. If you’re building a custom checkbox and a user clicks on it, the appropriate thing to do would be to tell the outside world that your checked state has changed:

class CustomCheckbox extends HTMLElement {
  connectedCallback() {
    this.addEventListener(‘click’, this.onClick);
  }
  onClick(e) {
    // This should trigger a setter which updates the DOM
    this.checked = !this.checked;
    this.dispatchEvent(new CustomEvent(‘checked-changed’, {
      detail: { checked: this.checked }, bubbles: false
    }));
  }
}

Frameworks already have built-in mechanisms for listening to DOM events, so they should be able to work with your component if it uses this pattern. For example, to respond to this check change in React we could do the following:

class SignUp extends React.Component {
  componentDidMount() {
    this.refs['signup'].addEventListener(
      'check-changed', this.onCheckChanged.bind(this)
    );
  }
  onCheckChanged(e) {
    /* Notify the outside world via callback or Redux */
  }
  render() {
    return (
      <div>
        <span>Join Our Newsletter!</span>
        <custom-checkbox
          ref="signup"
            checked={this.props.user.hasJoined}>
        </custom-checkbox>
      </div>
    );
  }
}

Note: There’s an ongoing discussion about improving event handler interop between Web Components and React over on GitHub. Till that issue is resolved you can use a library like webcomponents/react-integration to smooth over interop issues.

Or in Angular 2:

<span>Join Our Newsletter</span>
<custom-checkbox
  [checked]="user.hasJoined"
  (check-changed)=”user.hasJoined=$event.detail.checked”>
</custom-checkbox>

The key thing is that we’re telling the outside world that our state has changed. For top-down, unidirectional data flow systems this is important because it affords them the opportunity to revert that change if it doesn’t match their model. For example, React listens for the change event from the native <input type=”checkbox”> element, and if it doesn’t match React’s internal model, it reverts the change. Making sure our Custom elements dovetail into this system means they’ll ultimately be more shareable across the entire ecosystem.

When I showed this pattern off recently someone asked if it would be better to dispatch the events inside of the property setters, for example:

set checked(val) {
  this._checked = val;
  /* do any other updates we need */
  this.dispatchEvent(new CustomEvent(‘check-changed’, {
    detail: checked: val
  }));
}

The danger with doing this is you may end up creating an infinite loop if there’s an external listener for the event which in turn updates the property. Looking again to native elements, it seems that their event dispatching only takes place when some external force is acting upon the element, e.g. someone clicked, someone typed, something loaded, etc. Hence, we don’t dispatch check-changed when the public property is set, but instead only when someone clicks on the checkbox.

Also note that special care should be taken when working with events to prevent leaking too much information to the outside world. In general, don’t bubble events unless they are semantically meaningful. For example, changed is not a very semantically meaningful event, whereas document-opened would be. Non-semantic events can leak up and another element may accidentally handle them. Plus it makes things less explicit. Colocating the event dispatcher, and the element handling it makes relationships easier to grok. By default, custom events won’t bubble out of shadow roots without the composed: true flag set, so Custom Elements using Shadow DOM are default encapsulated w/ custom events.

In cases where you do need to bubble events, the element that handles the event should probably call event.stopPropagation(). Unless that element also has a good reason for letting the event continue to bubble up.

Favor a declarative API over an imperative API

It is preferable to always use properties (or attributes that reflect their changes to properties) to define the state for your component. This means avoiding methods which mutate state without reflecting those changes to the corresponding properties and dispatching the appropriate events. By focusing on properties you make it much easier to build your app in a declarative fashion.

<custom-dialog opened>
<!-- which is the same as saying... -->
customDialog.opened = true;

Instead of:

customDialog.open();

In the example above, the state of the app can be reasoned about entirely using HTML, whereas the second example requires imperative setup code in JavaScript (specifically calling a method). The declarative version lends itself well to systems like React/Redux and Angular 2 which favor a top-down data flow model, as they can just pass in the appropriate attributes/properties to make the state in the DOM match the state in their data stores.

Avoid sync issues with Shadow DOM

Frameworks and libraries which manage the DOM often have systems to dictate when components can render and how the DOM is updated. A good example is React’s virtual DOM diffing which creates a kind of snapshot of the DOM and uses it to reconcile changes whenever components update their state.

Custom Elements, on the other hand, render DOM in response to lifecycle callbacks triggered by the HTML parser. This means they may operate outside of a library’s ability to snapshot the DOM. This has the potential to lead to sync issues as the Custom Element upgrades and renders its own DOM that then does not match the snapshot the library is diffing against.

Shadow DOM offers a way to protect both the Custom Element and the library from getting their wires crossed. It does this by creating a shadow root, essentially a self-contained tree which the Custom Element can treat as its own private world, obscuring its internal DOM state from the rest of the page. Many of the native elements that you work with every day (input, video, etc) use Shadow DOM to encapsulate their internals.

To see this go to the Settings in Chrome Dev Tools and check “Show user agent Shadow DOM”.

Adding Shadow DOM to a Custom Element is quite easy:

class XFoo extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }
  connectedCallback() {
    this.shadowRoot.innerHTML = `<p>Hello from x-foo</p>`;
  }
}
window.customElements.define('x-foo', XFoo);

Or if you prefer using a <template> element for your markup:

<template id=”x-foo-tmpl”>
  <p>Hello from x-foo</p>
</template>

class XFoo extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }
  connectedCallback() {
    const tmpl = document.querySelector('#x-foo-tmpl');
    this.shadowRoot.appendChild(tmpl.content.cloneNode(true));
  }
}
window.customElements.define('x-foo', XFoo);

Using Shadow DOM will ensure that your element avoids potential conflicts with any framework managing the page and, as an added bonus, you’ll get style scoping for free!

Wrapping Up

The patterns listed above are based on conversations I’ve had with framework authors and I imagine over time we’ll need to augment and add to this list. Because the Web Component ecosystem is still fairly new, it feels like a good time to explore these patterns before possible bad habits get burned in and become widespread. If you’re building a Custom Element, consider giving these patterns a shot, and be sure to share your final project over on the new Web Components catalog. Also leave some comments! Thanks :)

Big thanks to Addy Osmani, Justin Fagnani-Bell, Jeff Cross, Rob Wormald, Sebastian Markbåge, and Trey Shugart for their reviews.

Recently I’ve run into two situations where it was extremely difficult for me to add proper keyboard support to the components I was building. After a lot of experimentation and research it became clear that maybe there were some missing primitives in the web platform that would have made my work a bit easier. I’ll explain the two scenarios here and cover some ideas for how to solve them.

Problem 1: Modals

A modal window is a dialog that appears above the page, often obscuring content behind it with an overlay. The idea is that if a modal is displaying the user should not be able to interact with anything else on the page.

For anyone who has ever tried to make a modal accessible you know that even though they seem pretty innocuous, modals are actually the boss battle at the end of web accessibility. They will chew you up and spit you out. For instance, a proper modal will need to have the following features:

• Keyboard focus should be moved inside of the modal and restored to the previous activeElement when the modal is closed
• Keyboard focus should be trapped inside of the modal, so the user does not accidentally tab outside of the modal (a.k.a. “escaping the modal”)
• Screen readers should also be trapped inside of the modal to prevent accidentally escaping

Nailing the above three points can be pretty difficult and requires a lot of contortions using combinations of aria-hidden to trap the screen reader and managing focus to trap TAB. Here’s one of the best examples I’ve found. Note that this example assumes your modal is a sibling to the rest of your main content so you can easily apply aria-hidden to main. If, however, your modal is mixed in with the rest of your main content (maybe for positioning reasons) then you are seriously screwed. You’ll need to find a way to put aria-hidden on everything in main that isn’t your modal (or a parent of your modal). It definitely feels harder than it should be.

What about <dialog>?

The HTML spec does mention the idea of a <dialog> element which would magically solve all of the above issues. The problem is that so far only Chrome has implemented it, and other browsers seem disinterested. Furthermore, <dialog> may not be the right solution. Let’s consider another example:

Offscreen drawer menus are an extremely popular UI pattern in responsive sites. But is an offscreen drawer menu the same as a <dialog>? The drawer also needs to comply with the three bullet points listed above but calling it a dialog feels like a stretch. My hunch is many developers might not think to reach for <dialog> when they’re building a drawer.

Possible solution: blockingElements

Rather than contort <dialog> to do our bidding, why not expose a JavaScript API that gives us all the same magical goodies. Then we could create our own custom elements and leverage the API as we see fit. This idea has been discussed over on the whatwg/html GitHub repo, under the thread “Expose a stack of blocking elements”.

The proposed API could look something like this:

// put element at the top of the blocking elements stack
document.blockingElements.push(element);
document.blockingElements.pop();
// see https://github.com/whatwg/html/issues/897#issuecomment-198565716
document.blockingElements.remove(element);
document.blockingElements.top; // or .current or .peek()

Putting an element at the top of the stack effectively means everything else on the page is inert (so no risk of the keyboard or screen reader “escaping”). And when an element is popped off of the stack, focus naturally returns to the previous activeElement. This allows us to explain the behavior of <dialog> so component authors can use it to build whatever they like, which dovetails really well with the whole extensible web movement. A natural side effect of doing this is we get tons of accessibility features for free. Developers wouldn’t need to sprinkle the page with aria-hidden attributes or write keyboard traps, instead they would use the best API for building a dialog and good accessibility would naturally come out of that. It’s a total win.

At the moment blockingElements is still a new idea, and new ideas are fragile, so please resist the urge to hop on that GitHub issue and bikeshed the heck out of it 😊 Our next step is to move blockingElements into a Web Platform Incubator Community Group (WICG) so we can continue to iterate on the idea. When we move to the WICG I will be sure to update this blog and let you all know!

Problem 2: Disabling tabindex

Let’s go back to that offscreen drawer example for a second. In order to animate that drawer on screen, and achieve a 60fps animation, I’m going to need to promote the drawer to its own layer using something like will-change: transform. Now I can transform the drawer on screen and I shouldn’t trigger unnecessary paints or layouts. This technique is explained really well by Paul Lewis in his I/O presentation.

One problem: to do this we must leave the drawer in the DOM at all times. Meaning its focusable children are just sitting there offscreen, and as the user is tabbing through the page eventually their focus will just disappear into the drawer and they won’t know where it went. I see this on responsive websites all the time. This is just one example but I’ve also run into the need to disable tabindex when I’m animating between elements with opacity: 0, or temporarily disabling large lists of custom controls, and as others have pointed out, you’d hit if you tried to build something like coverflow where you can see a preview of the next element but can’t actually interact with it yet.

What about aria-hidden?

Using aria-hidden it’s possible to remove an element and all of its children from the accessibility tree. This is awesome and solves the problem for screen readers (Marcy Sutton pointed out that it doesn’t completely solve the issue for screen readers and can even lead to “ghost controls” which are focusable but lacking a11y information). Unfortunately ARIA is forbidden from affecting page behavior, it only deals with semantics, and there is no similar concept for tabindex. This is important because there are sighted users with motor impairments who rely on the tab key to navigate the page. If you have a complex tree of interactive elements and you need to remove all of them from the tab order your only option is to recursively walk the tree (or write a pretty heinous querySelectorAll string) and set every focusable element to tabindex="-1". You also need to remember any explict tabindex values they may already have and restore those when the element is back on screen. Again, it feels harder than it should be.

What about pointer-events: none?

Settings pointer-events: none will make it so you can’t click on an element but it doesn’t remove it from the tab order and you can still interact with it using the keyboard.

What about setting the drawer to display: none?

When the drawer is offscreen we could set it to display: none or visibility: hidden. That would remove the focusable children from the tab order. Unfortunately that will also destroy our GPU layer which kind of negates the whole animation technique. On a simple enough drawer we can actually get away with recreating the layer right when the user opens it, but for a more complex drawer (like the kind on m.facebook.com) all of that painting would probably cause our animation to jank. I don’t think developers should have to choose between 60fps animations and good accessibility.

Possible solution: inert=""

Previously there was some discussion around adding an inert attribute to HTML. The basic idea is you could set the inert attribute on an element, and its entire tree of descendants would become non-interactive. This is perfect for our drawer example as it means we could paint something offscreen, set it to inert, and not have to worry about a keyboard user accidentally interacting with it.

Unfortunately the original use cases cited for inert seem to orbit mainly around dialogs and since there was already a <dialog> proposal floating around at the time, it was punted.

My feeling is this is perhaps backwards. I think the proposed blockingElements API would be a better way of letting developers build accessible dialogs because it says “everyone else BUT ME is inert”. Whereas inert="" would be useful for the animation example above where I need something to be painted and in the DOM but also be non-interactive (in other words, “I AM inert”). And for anyone doing accessibility work it becomes like a more powerful aria-hidden because presumably it would not only remove an element from the tab order but also from the accessibility tree. Developers would use the best API to build their component and they’d get good accessibility for free. ZOMG SO FULL OF WIN!

I should add that others on the discussion thread mention that maybe this would be better solved with a new CSS property. I’d be cool with that as well but to my (very limited) knowledge no proposal has come forward and this is a legitimate pain point for developers. So I’ve filed a chromium bug to see if the Chrome team will explore restarting the process of implementing inert. I hope by documenting these use cases we can convince others of its utility. If there’s progress I’ll be sure to write a follow up post to let you all know 🐝

As it happens, I formatted my laptop today and did a clean install of Yosemite so my machine is about as stock as they come. As I was setting up Android Studio, I ran into some hiccups and thought I’d document them for anyone else running into similar issues.

Step 1: Install Android Studio

After downloading Android Studio and firing it up for the first time, I was immediately confronted with an error:

Android Studio was unable to find a valid JVM

I realized I hadn’t yet setup Java on my machine so I followed the link from the Android Studio docs to download the JDK and installed Java 7. Hopping over to my command line, I verified the install by running javac -version which output javac 1.7.0_71.

Tried restarting Android Studio and…

Android Studio was unable to find a valid JVM

Crap.

Step 2: Google furiously

At this point, I must admit that I’m no Java expert. I followed the instructions to download the JDK but there are a ton of links on that page… maybe I made a mistake?

Thankfully this StackOverflow thread saved the day.

The accepted answer recommends hacking on the info.plist inside the Android Studio package. There’s discussion in the comments pointing out that this is no longer a recommended practice.

I finally found this answer which recommends downloading the latest JVM from Oracle and then downloading this Java bundle from Apple. After installing both packages I’m now able to fire up Android Studio (and I didn’t have to hack on any of the internals). Yay!

Step 3: Reflect

I’ve tried setting up Java in Eclipse before, and even previously in Android Studio. For some reason it’s always a pain and super discouraging. I think it would be great if the Android Studio guide contained a bit more explaination about exactly what I need to install to get up and running. Just pointing folks to this page and telling them to install the JDK is frought with peril. There are a million links on that page and almost no information hierarchy. If there are specific items I should click, gimme some screenshots.

Also, the error message from Android Studio is very unhelpful.

Android Studio was unable to find a valid JVM

That was literally the first thing I saw when I started Android Studio. There’s no “Hey click this link to find out how you can remedy this.” Just an OK button that closes the app. Add a link to a troubleshooting guide and I think you’ll save a handful of folks who were struggling like I was.

Update 01/24/2015

Looks like there’s a ticket to address this issue. According to the team:

In the next version of Android Studio, if no java 6 is found but 7 (or greater) is found then it will use that instead. We still recommend running studio with Java 6 due to improved font rendering, but there is no work around needed if, for example, only java 8 is found.

So it seems like much of the confusion is around using Java 7 (or 8) instead of Java 6. If 6 is the required version it would be nice to link directly to it instead of pointing everyone to the JDK download page which has the latest versions at the top. Still, I’m happy to see this issue is being resolved.

I did some digging and manged to turn up this thread on the Polymer mailing list.

The Fix

I had a bit of an “aha moment” when I remembered that the Shadow DOM is encapsulating those styles in a shadow boundary. A workaround is to pull your @font-face rules out of the stylesheet for your element, and move them to the top of your import.

Note to readers: This is old Polymer code but the idea is essentially the same. Move your @ rules into the global scope instead of putting them in the Shadow DOM.

<style>
  @font-face {
    font-family: 'FontAwesome';
    src: url('../fonts/fontawesome-webfont.eot?v=4.0.3');
    src: url('../fonts/fontawesome-webfont.eot?#iefix&v=4.0.3') format('embedded-opentype'), url('../fonts/fontawesome-webfont.woff?v=4.0.3')
        format('woff'), url('../fonts/fontawesome-webfont.ttf?v=4.0.3') format('truetype'), url('../fonts/fontawesome-webfont.svg?v=4.0.3#fontawesomeregular')
        format('svg');
    font-weight: normal;
    font-style: normal;
  }
</style>

<polymer-element name="semantic-ui-icon" noscript>
  <template>
    <link rel="stylesheet" href="./icon.css" />
    <content></content>
  </template>
</polymer-element>

I found this approach in the Polymer documentation, so I’m hoping it’s considered a best practice. You’ll also need to do this if you’re using @-webkit-keyframes rules.

I hope that clears things up for some of you who may have been stuck. I know it took me a couple days to come up with this solution, so I thought it best to go ahead and post about it :)

The Lowdown

Imports are a new type of link tag which should be familiar to you since that’s also how we load our stylesheets.

<link rel="stylesheet" href="/path/to/styles.css" />

For an import we just replace the rel with one of type import.

<link rel="import" href="/path/to/some/import.html" />

Support

Native imports are currently only available in Chrome. Be sure to check the support brackets on caniuse to see if things have changed since the writing of this article. If you’d like to play with imports today you can leverage the webcomponents.js polyfill.

A Basic Example

OK so what’s a very basic import look like?

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Basic HTML Imports</title>
    <!-- Pull in our blog post example -->
    <link rel="import" href="/imports/blog-post.html" />
  </head>
  <body>
    <p>Hello World!</p>
  </body>
</html>

In its simplest form an import works just like calling a stylesheet. We have to make sure there’s a document to import so let’s create a fake blog post in imports/blog-post.html.

<div id="blog-post">
  <h1>Awesome header</h1>
  <p>Here is some really interesting paragraph content.</p>
</div>

To test, you’ll need to host your index.html and imports/ folder on a local server. I recommend serve if you don’t already have one installed.

Once you have that setup, visit your index page. If you take a look at the console you can see the request returning.

Well that’s cool, but now what?

Let’s grab the content of the import using some JavaScript and append it to the body. We’ll do this back in our index.html.

<body>
  <p>Hello World!</p>

  <script>
    var link = document.querySelector('link[rel=import]');
    var content = link.import.querySelector('#blog-post');
    document.body.appendChild(document.importNode(content, true));
  </script>
</body>

First we query the link tag which loaded our import. Then we extract our #blog-post element and store it in a variable called content. In browsers with native support for imports (i.e. Chrome and Opera) notice that we don’t have to write any event handler code to wait till the import has loaded, we can just assume the content is there and start working with it. Finally we add the new content to our body.

If you’re following along you should end up with something like this:

Exciting, I know ;) But it demonstrates a no frills approach to loading content that doesn’t require ajax and writing our own event handlers. Let’s keep digging to see what else we find…

A Basic Example with Polymer

Polymer is a library that sugars the Web Components APIs and seeks to enable the use of Web Components in all modern browsers. The hope is that devolopers will use Polymer to inform the W3C on which direction to take with Web Components; so rather than wait for a stinky spec, we can guide the implementation process.

Polymer attempts to keep parity with the the evolving specifications but obviously there are some places where the API must differ because of the limitations of current browsers. In the case of HTML Imports, Polymer waits for the DOMContentLoaded event before triggering the actual import process. This means we need to listen for the HTMLImportsLoaded event on either window or document to know when it is finished. Let’s add that to our index.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Basic HTML Imports</title>
    <link rel="import" href="/imports/blog-post.html" />
  </head>
  <body>
    <p>Hello World!</p>

    <!-- Include platform.js -->
    <script src="/bower_components/webcomponentsjs/webcomponents.js"></script>

    <!-- Listen for the HTMLImportsLoaded event -->
    <script>
      window.addEventListener('HTMLImportsLoaded', function() {
        var link = document.querySelector('link[rel=import]');
        var content = link.import.querySelector('#blog-post');
        document.body.appendChild(document.importNode(content, true));
      });
    </script>
  </body>
</html>

Using the above we should get the same results as before.

You might notice that I used webcomponents.js instead of only including the HTML Imports polyfill. The Web Components polyfills are structured so you can take any of the polyfills à la carte but I find it’s easier to just include all of webcomponents.js when I’m experimenting, rather than worry if I have each individual polyfill loaded. That’s just personal preference (in other words: I’m lazy).

Using Scripts in our Imports

Let’s look at using <script> tags inside of our import. We’ll start by removing the <script> block from our index.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Basic HTML Imports</title>
    <link rel="import" href="/imports/blog-post.html" />
  </head>
  <body>
    <h1>Boring header</h1>
    <p>Hello World!</p>
  </body>
</html>

Then we’ll transfer that script block over to our blog post in imports/blog-post.html.

<div id="blog-post">
  <style>
    h1 {
      background: lightgreen;
      color: green;
    }

    p {
      font-size: 16px;
      font-family: Helvetica, Arial, sans-serif;
      color: green;
      font-weight: bold;
    }
  </style>

  <h1>Awesome header</h1>
  <p>
    Here is some really interesting paragraph content. It comes with its own stylesheet!
  </p>
</div>

<script>
  // thisDoc refers to the "importee", which is blog-post.html
  var thisDoc = document.currentScript.ownerDocument;

  // thatDoc refers to the "importer", which is index.html
  var thatDoc = document;

  // grab the contents of the #blog-post from this document
  // and append it to the importing document.
  var content = thisDoc.querySelector('#blog-post');
  thatDoc.body.appendChild(thatDoc.importNode(content, true));
</script>

If we run this we should get the following output (note: I’ve included a style element as well).

An important thing to take notice of is the relationship between thisDoc and thatDoc. thisDoc refers to the blog-post.html document, while thatDoc refers to our index.html file. It’s useful to distinguish between the two so we can querySelector for #blog-post and not worry that we may have grabbed something out of the importing document. Thanks to Dominic Cooney for the heads up on this.

You’ll also notice that since the import has access to our document object it is able to add itself to the page. In practice you probably wouldn’t want imports adding themselves wherever, but the important takeaway is that anything imported can access the main document. This means an import could register itself as a Custom Element using our document object and we wouldn’t need to write any additional code. We’re almost to that point so let’s keep going…

Using Templates in our Imports

I’m getting a little tired of our fake “blog post” so let’s switch over to something more practical. We’ll use Chart.js to create a very simple pie diagram and we’ll use the new <template> tag to hold the contents of our import. If you haven’t heard of the template tag before check out this introduction.

I’ve updated the index.html so it imports a new chart.html file.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Imports with Templates</title>
    <!-- Make sure to import chart.html -->
    <link rel="import" href="/imports/chart.html" />
  </head>
  <body>
    <h1>Quarterly Pokemon Sales</h1>
  </body>
</html>

Here’s what imports/chart.html looks like:

<!-- Include Chart.js so our import can use it -->
<script src="/lib/Chart.min.js"></script>
<template id="chart-pie">
  <canvas id="myChart" width="200" height="200"></canvas>
  <script>
    var data = [
      {
        value: 30,
        color: '#F38630'
      },
      {
        value: 50,
        color: '#E0E4CC'
      },
      {
        value: 100,
        color: '#69D2E7'
      }
    ];

    // Get the context of the canvas element we want to select
    // It's ok to use document here because this script block won't
    // activate till it's added to the page.
    var ctx = document.getElementById('myChart').getContext('2d');
    var myNewChart = new Chart(ctx).Pie(data);
  </script>
</template>

<script>
  // thisDoc refers to the "importee", which is chart.html
  var thisDoc = document.currentScript.ownerDocument;

  // thatDoc refers to the "importer", which is index.html
  var thatDoc = document;

  // grab the contents of #chart-pie from this document
  // and append it to the importing document.
  var template = thisDoc.querySelector('#chart-pie');
  thatDoc.body.appendChild(thatDoc.importNode(content, true));
</script>

We’re creating a new <template> which contains a canvas tag and a script block to create our pie chart. The advantage of using a template tag is that any script blocks inside of it will not execute until we clone the contents and add them to the DOM.

Running the above gives us this:

Well this is interesting. We’re importing an entire pie chart and our index page isn’t cluttered with a bunch of code. Unfortunately we don’t have much control over where the pie chart ends up. It would be nice if we could turn the contents of the import into a tag and place that wherever we please. Thankfully Custom Elements let us do just that!

Using Custom Elements in our Imports

I’ll say in advance that you might need to read through this section a few times before you fully grok it. We’re going to touch on a lot of new stuff so consider this the bonus round :)

The final markup for our index.html file is going to look like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Imports with Custom Elements</title>
    <link rel="import" href="/imports/chart.html" />
  </head>
  <body>
    <h1>Quarterly Pokemon Sales</h1>
    <chart-pie></chart-pie>
    <chart-pie></chart-pie>
    <chart-pie></chart-pie>
  </body>
</html>

We’re going to use our new Custom Element, chart-pie, which will allow us to produce pie charts wherever we want. The result will look like this:

Obviously not the most amazing thing ever, but from a practical perspective being able to drop a pie chart on your page with one line of HTML is pretty sweet.

To create the chart-pie tag we’ll need to create a Custom Element. Custom Elements are new tags with a lifecycle of JavaScript callbacks. Typically they use Shadow DOM to hide their internal markup and expose attributes and specific styles to the client. For a full primer on Custom Elements, check out this article by Eric Bidelman on HTML5Rocks.

Here’s what our updated imports/chart.html looks like.

<script src="/lib/Chart.min.js"></script>
<template id="chart-pie">
  <canvas class="myChart" width="200" height="200"></canvas>
</template>

<script>
  // thisDoc refers to the "importee", which is chart.html
  var thisDoc = document.currentScript.ownerDocument;

  // thatDoc refers to the "importer", which is index.html
  var thatDoc = document;

  var template = thisDoc.querySelector('#chart-pie');

  // Make sure you extend an existing HTMLElement prototype
  var ChartPieProto = Object.create(HTMLElement.prototype);

  // Setup optional lifecycle callbacks
  ChartPieProto.createdCallback = function() {
    // Create a shadow root to hold our template content
    var root = this.createShadowRoot();
    var clone = thatDoc.importNode(template.content, true);

    // Create the pie chart with Chart.js
    var data = [
      {
        value: 30,
        color: '#F38630'
      },
      {
        value: 50,
        color: '#E0E4CC'
      },
      {
        value: 100,
        color: '#69D2E7'
      }
    ];

    //Get the context of the canvas element we want to select
    var ctx = clone.querySelector('.myChart').getContext('2d');
    var myNewChart = new Chart(ctx).Pie(data);

    // Add the template content + chart to our Shadow DOM
    root.appendChild(clone);
  };

  var ChartPie = thatDoc.registerElement('chart-pie', {prototype: ChartPieProto});
  //var chartPie = new ChartPie();
  //var chartPie = document.createElement('chart-pie');
</script>

Let’s walk through it piece by piece.

<template id="chart-pie">
  <canvas class="myChart" width="200" height="200"></canvas>
</template>

On lines 1-3 we’ve shortened the template down so that it only contains our canvas tag. We’ll use the Custom Element createdCallback to actually instantiate the chart in here.

// thisDoc refers to the "importee", which is chart.html
var thisDoc = document.currentScript.ownerDocument;

// thatDoc refers to the "importer", which is index.html
var thatDoc = document;

var template = thisDoc.querySelector('#chart-pie');

Lines 6-12 should look familar from the last example. We’re storing our two documents in variables and querying for the template tag.

var ChartPieProto = Object.create(HTMLElement.prototype);

On line 15 we define the prototype for our Custom Element called ChartPieProto. This prototype extends the HTMLElement prototype which is a requirement for creating a new element.

ChartPieProto.createdCallback = function() {
  ...
};

On line 20 we see the first lifecycle callback, createdCallback. The createdCallback is run every time the parser hits a new instance of our tag. Therefore we can use it as a kind of constructor to kickoff the creation of our chart. We’ll want to create a new chart instance for each tag so all of our Chart.js code has been moved inside of this callback.

var root = this.createShadowRoot();
var clone = thatDoc.importNode(template.content, true);

On lines 22-23 we create a Shadow DOM to hold the markup for our chart.

var data = [
  {
    value: 30,
    color: '#F38630'
  },
  {
    value: 50,
    color: '#E0E4CC'
  },
  {
    value: 100,
    color: '#69D2E7'
  }
];

//Get the context of the canvas element we want to select
var ctx = clone.querySelector('.myChart').getContext('2d');
var myNewChart = new Chart(ctx).Pie(data);

Lines 26-43 should look familiar. It’s the same Chart.js code from before except now we use querySelector to find the contents of the template clone and we’re using a class for myChart instead of an id.

root.appendChild(clone);

On line 46 we add the new content to our Shadow DOM.

var ChartPie = thatDoc.registerElement('chart-pie', {prototype: ChartPieProto});

Line 49 is where we actually register our Custom Element and assign it to the name chart-pie. From here you can either place a <chart-pie></chart-pie> tag somewhere on your page, or use JavaScript to instantiate an instance and add it to the document. This is demonstrated in the comments on lines 50-51. If you refer back to our index.html example we just use the <chart-pie> tag.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Imports with Custom Elements</title>
    <link rel="import" href="/imports/chart.html" />
  </head>
  <body>
    <h1>Quarterly Pokemon Sales</h1>
    <chart-pie></chart-pie>
    <chart-pie></chart-pie>
    <chart-pie></chart-pie>
  </body>
</html>

Which produces this:

Conclusion

If you’ve made it this far congrats and thanks for hanging in there! I know that last section was a little crazy but stop for a moment and think about what we just did.

By using an HTML Import we were able to pull in a document which added a new tag to our application. Imagine if all of Chart.js was written in this manner. There would be no need for us to write any glue code to generate a chart ever again. That would allow us to focus only on the code that matters to our application, and leave all that other boilerplate tucked away inside of Custom Elements.

Over the next few months I’ll be blogging exclusively about this topic because I think it’s really interesting so check back later for more!

Till then make sure to hit me up on Twitter if you have any questions or leave a note in the comments. Thanks!

Comparing two things or one

Take a look at this sample code to get a feel for what we’re talking about.

<style>
p:nth-child(2) {
  background-color: green;
}
</style>

<div>
  <p>This paragraph is not green</p>
  <p>This paragraph *is* green</p>
</div>

You’ll notice that we’re setting our second p element to have a background-color of green. To do this we use p:nth-child(2). I think the way most people (myself included) would read that selector is “select the second child paragraph”. But if we change the markup to look like this:

<div>
  <h1>Hello World!</h1>
  <p>This paragraph is not green :(</p>
  <p>This paragraph is green!</p>
</div>

Suddenly our green background moves to the wrong element. What gives?!

Chris Coyier helpfully explains on CSS-Tricks.

Our :nth-child selector, in “Plain English,” means select an element if:

• It is a paragraph element
• It is the second child of a parent

Since we’ve added another child in the form of an h1 tag, we need to now say p:nth-child(3) if we want to select the same element. In my mind that makes the nth-child tag brittle and somewhat counterintuitive.

Thankfully there’s an alternative in form of the nth-of-type selector.

p:nth-of-type(2) {
  background-color: green;
}

Again, quoting Mr. Coyier:

Our :nth-of-type selector, in “Plain English,” means:

• Select the second paragraph child of a parent

So nth-of-type gives us the functionality we were originally looking for and doesn’t require us to change our markup if we add additional child elements which use different tags. That’s pretty sweet!

If you want to play around with the idea I’ve put together a codepen. Enjoy!

The video is around 35 minutes long and there’s a slide deck available on Github that has clickable links and whatnot. Enjoy!

Slidedeck on Github

There’s a great HTML5Rocks article on the subject of the template tag and I’m going to steal some of their examples.

Let’s start by making a template for an image placeholder.

<template id="kitten-template">
  <img src="" alt="random kitten image" />
  <h3 class="title"></h3>
</template>

<div id="kittens"></div>

<script>
  const template = document.querySelector('#kitten-template');
  template.content.querySelector('img').src = 'https://placekitten.com/400/400';
  template.content.querySelector('.title').textContent =
    'Random image from placekitten.com';
  document
    .querySelector('#kittens')
    .appendChild(document.importNode(template.content, true));
</script>

If you’ve worked with client-side template libraries like underscore or handelbars the above should look familiar to you. Where underscore and handelbars take advantage of putting their templates inside of <script> tags and changing the type to something like text/x-handlebars-template, the <template> tag doesn’t need to, because it’s actually part of the HTML spec. There are pros and cons to this approach.

Pros

• The content of the template is inert: scripts won’t run, images won’t load, audio won’t play, etc. This means you can have <img> and <script> tags whose src attributes haven’t been defined yet.
• The child nodes of a template are hidden from selectors like document.getElementById() and querySelector() so you won’t accidentally select them.
• You can place the <template> pretty much anywhere on the page and grab it later.

Cons

• You can’t precompile the template into a JS function like you can with other libraries like handlebars.
• You can’t preload the assets referenced by a template (images, sounds, css, js).
• You can’t nest templates inside of one another and have them automagically work. If a template contains another template you’ll have to activate the child, then activate the parent.
• There’s no support for data interpolation (i.e. filling a template with values from a JS object).

Given that list of cons you might say “Well why would I ever bother with the <template> tag if something like handlebars gives me way more power?” That’s a great question because by itself the <template> tag doesn’t seem so impressive.

Its saving grace lies in the fact that it is part of the DOM, whereas all other template libraries are actually just pushing around Strings. That makes them vulnerable to XSS and requires weird hacks to prevent the browser from rendering their content.

While features like data interpolation are pretty crucial, they can be fixed by the next generation of template libraries, in fact lit-html has already added this back in. Which leads to the bigger point: combining templates with Shadow DOM and Custom Elements gives us the future component model for the web, and that’s why I’m truly excited to use them.

After my last post @stevensacks tweeted at me that he was having issues getting node FileSystem commands to work in grunt. After a bit of poking around I noticed that there was no call to grunt’s async method, which was probably preventing the process from finishing properly. So today’s post is a primer on async grunt processes, and how to make sure your node and grunt syntax is setup correctly.

Grab the Example Source

I’ve provided a simple grunt project at the link above. Take a look at the tasks folder and you should see two custom tasks, grunt-read-write-local.js and grunt-read-write-web.js. The former will read a local file and write its contents to a new file. The latter will request a webpage and write its contents to a static file.

There are two asynchronous APIs at play here (Node’s and Grunt’s) and it’s important to understand both.

In Node an async operation will usually provide a callback, such is the case for fs.readFile, or it will use an event dispatch, for instance in an http request we listen for the data event.

Grunt, on the other hand, uses a token or a kind of promise. You grab a reference to grunt’s done function and you wait till your node process has finished before calling it. If you take a look at grunt-read-write-local.js you can see that we first call the async method to let grunt know it needs to wait:

var done = this.async();

and as we finish writing our file we tell grunt that everything completed succesfully and it’s ok to carry on:

// Write the contents of the target file to the new location
fs.writeFile(pathToWrite, data, function(err) {
  if (err) throw err;
  console.log(pathToWrite + ' saved!');
  // Tell grunt the async task is complete
  done();
});

We do something similar in our grunt-read-write-web task but this time we work with Stream events.

// Tell grunt this task is asynchronous.
var done = this.async();

http
  .get(pathToRead, function(res) {
    // Pipe the data from the response stream to
    // a static file.
    res.pipe(fs.createWriteStream(pathToWrite));
    // Tell grunt the async task is complete
    res.on('end', function() {
      console.log(pathToWrite + ' saved!');
      done();
    });
  })
  .on('error', function(e) {
    console.log('Got error: ' + e.message);
    // Tell grunt the async task failed
    done(false);
  });

The response returned by an http request implements the ReadableStream interface so it will emit data and end events. Node Streams have a great feature called pipes which handle the work of consuming data events and writing them to a destination. Sexy :) We still listen for the end event coming from our request so we can notify grunt that the process has finished and it can move on.

Grab the Example Source

If you want to test it all out make sure you run npm install first to pull down any dependencies. Then kick things off by running grunt. I’m thinking my next post might be all about Streams in node since they’re such a cool concept. Thanks to @maxogden and @dominictarr for their great posts on the subject of streams.

• Node Streams: How do they work? – Max Ogden
• High Level Style in JavaScript – Dominic Tarr

Overview

Note: This tutorial assumes you’re already familiar with RequireJS and its configuration options. If not, I recommend you check out the docs before proceeding

Grab the Boilerplate

When building single-page apps, many people choose to compile all of their JavaScript into one file before deploying to production. While this may make the initial download size of the page larger, the hope is that it reduces section-to-section http requests, thus making the overall experience feel snappier and more app-like.

When working with a multi-page site, compiling everything into one file is probably not a good idea. Since you have no guarantee that the user will visit every page, you may be loading unnecessary JavaScript and slowing down the experience. Do you really need to load all of the JavaScript for the About page if the user is just visiting the Contact page?

The ideal scenario is one in which each page has its own main file that contains page-specific instructions and then a separate (hopefully cached) file that contains all of the commonly used JavaScript libraries.

For example, if you have a page called About and a page called Contact you would have main-about.js and main-contact.js. Let’s say main-about.js and main-contact.js both require 'jquery' and 'underscore'. We wouldn’t want to compile jquery and underscore into each main file because then we’re creating unnecessary bloat. Instead, we should create a common.js file which contains jquery and underscore and we’ll make sure that this file loads before any of our main-* files. Take a look at this diagram to help it sink in:

OPTIMIZED SCRIPTS

common.js
----------------
js/vendor/jquery.js
js/vendor/underscore.js

About
----------------
js/common.js
js/app/main-about.js

Contact
----------------
js/common.js
js/app/main-contact.js

By compiling all of those libaries into common.js we’re reducing the number of http requests per page. Also, after the first page has loaded, common.js should be available from the browser’s cache. Now that you get the general concept, let’s take a look at an example.

Examples!

James Burke, author of RequireJS, has done a great job putting together some example projects which show how to effectively structure your project so it can be run through the r.js optimization tool. The one I typically refer to is the example-multipage-shim. There’s also an example-multipage, but I tend to use the shim version because it seems like there’s always a few non-AMD scripts that end up in a project.

I’ve put together my own boilerplate, using Bootstrap 3 and GruntJS, which you guys are free to grab here. The rest of this post will walk through this boilerplate.

Learn you a boilerplate!

If you’ve worked with RequireJS on a single page site, you’re probably used to defining a script tag that looks like this:

<!--This sets the baseUrl to the "scripts" directory, and
    loads a script that will have a module ID of 'main'-->
<script data-main="scripts/main.js" src="scripts/require.js"></script>

The data-main attribute is a convenience feature of RequireJS which sets Require’s baseUrl property. You usually put some configuration options in the main file as well, for instance, if you’re loading a 3rd party library you might create a path so you can easily reference it. Since our boilerplate has different main-* files for each page, we’re going to put that configuration data into our common.js file instead.

Hold on, I thought you said common.js was where we were going to compile all of our libraries?

Indeed, you are correct astute reader. But since common.js is going to be loaded before any other required modules, why not put our configuration options in it as well? Here’s what the common.js file from our boilerplate looks like:

//The build will inline common dependencies into this file.

requirejs.config({
  baseUrl: './js',
  paths: {
    jquery: 'vendor/jquery',
    bootstrap: 'vendor/bootstrap'
  },
  shim: {
    bootstrap: ['jquery']
  }
});

You’ll note that we’re using Twitter Bootstrap, which is not AMD compliant out of the box, so we have to shim it. In this case it depends on jquery, so we list that as its only dependency and we’re good.

Aside from common.js, you should probably take a look in the app/models directory. I’ve created two models that extend a BasicModel in order to illustrate that the common.js file isn’t only for 3rd party code. common.js is really for any code that’s going to be used over and over on your site. We’ll toss the BasicModel into common.js during the build process.

Just hit build already…

O.K., O.K. I can tell you’re ready to see some fireworks. Before we hit build, I want to point out the options.js file. This is where we tell r.js which modules to compile and what each module should include or exclude.

module.exports = {
  appDir: 'www',
  baseUrl: 'js/',
  mainConfigFile: 'www/js/common.js',
  dir: 'www-release',
  modules: [
    {
      name: 'common',
      include: ['app/models/basicModel', 'jquery', 'bootstrap']
    },
    {
      name: 'app/main-about',
      exclude: ['common']
    },
    {
      name: 'app/main-contact',
      exclude: ['common']
    }
  ]
};

You’ll note that first we put together our common module, then we tell the subsequent modules to exclude it. When you tell r.js to exclude a module it will find all of the nested dependencies in that module and exclude those as well. This is why we don’t need to tell main-about and main-contact to exclude bootstrap. It sees that bootstrap is already in common, so it knows to exclude it.

If you haven’t done so already, now is a good time to do an npm install. That should pull down all of the grunt dependencies. Speaking of grunt, you’ll need to install that as well if you’ve never used it npm install -g grunt-cli. You might notice in our Gruntfile.js, we are using a number of tasks from the grunt-contrib library. grunt-contrib is a great resource, and I encourage you to spend some time looking through all of the tasks that fall under its umbrella.

O.K. Ready to rock. Just type grunt to build, or grunt.cmd if you’re on Windows (thanks @stevensacks). When you’re finished, you should have a new folder called www-release. Check out the build.txt file to see where everything ended up.

css/bootstrap-responsive.css
----------------
css/bootstrap-responsive.css

css/bootstrap.css
----------------
css/bootstrap.css

css/style.css
----------------
css/style.css

js/common.js
----------------
js/common.js
js/app/models/basicModel.js
js/vendor/bootstrap.js

js/app/main-about.js
----------------
js/app/models/aboutModel.js
js/app/main-about.js

js/app/main-contact.js
----------------
js/app/models/contactModel.js
js/app/main-contact.js

If you take a look at the common.js file in www-release, it should look like a big blob of minified code. That’s what we want to see. In this case it contains our BasicModel, Twitter Bootstrap, jQuery, and our original configuration code. If you refer to about.html you can see how we control the load order:

<script src="./js/vendor/require.js"></script>
<script type="text/javascript">
  // Load common code that includes config,
  // then load the app logic for this page.
  require(['./js/common'], function(common) {
    // ./js/common.js sets the baseUrl to be ./js/
    // You can ask for 'app/main-about' here instead
    // of './js/app/main-about'
    require(['app/main-about']);
  });
</script>

First, we bring in RequireJS. Then we load common.js, and only aftercommon.js is loaded do we request the page specific code in main-about. If you stick to this structure, you should be able to layer your code so it’s easy to manage.

Grab the Example Source

Factories encapsulate and separate object creation from the rest of your code. In situations where the creation of an object can be complex or subject to change a factory can act as a nice buffer to help keep things tidy. Without proper planning Factories can lead to class explosions; as a result the pattern can be both a blessing and a curse depending on how it’s used.

Formal Definition

Factory Method

Define an interface for creating an object, but let subclasses decide which class to instantiate. Factory Method lets a class defer instantiation to subclasses.

Abstract Factory

Provide an interface for creating families of related or dependent objects without specifying their concrete classes.

Also Known As

• Virtual Constructor (Factory Method)
• Kit (Abstract Factory)

Simple Factory vs Factory Method vs Abstract Factory

The phrase “Factory Pattern” is rather overloaded so I’m going to give you a quick crash course in the three main types of factories.

A simple factory is an object which encapsulates the creation of another object, shielding that code from the rest of your application.

var user = UserFactory.createUser();

It’s common to parameterize simple factory methods to increase the number of products they’re able to return.

var admin = UserFactory.createUser('admin');
var customer = UserFactory.createUser('customer');

The actual implementaiton of createUser might look something like this:

UserFactory.createUser = function(type) {
  if (type == 'admin') {
    return new Admin();
  } else if (type == 'customer') {
    return new Customer();
  }
};

Typically the return value from a factory is known as the Product. In the case of our UserFactory there are two Products: Admin and Customer. It’s important for these products to maintain a consistent interface so the client can use any product from our factory without needing to do elaborate checks to see if a particular method exists.

Factory Method

While the Simple Factory is a nice start and good for many situations it’s possible to extend this even further through the use of the Factory Method pattern.

The Factory Method Pattern defines an interface for creating an object, but lets subclasses decide which class to instantiate. Factory Method lets a class defer instantiation to subclasses. Elisabeth Freeman, Head First Design Patterns

Factory Method defines one method, createThing for instance, which is overriden by subclasses who decide what to return. The Factories and Products must conform to interfaces for clients to be able to use them.

In Head First Design Patterns a Factory Method pattern is used to allow a PizzaStore to define many subclasses such as ChicagoPizzaStore, CaliforniaPizzaStore, NewYorkPizzaStore. Each subclass overrides createPizza and returns its own particular style of pizza (ie: a ChicagoPizza or a CaliforniaPizza). The main take away is that there is only one method, createPizza, that does anything. By subclassing and overriding this method we can offer aditional flexibility beyond what’s possible with the Simple Factory.

Abstract Factory

Unlike the Factory Method pattern, Abstract Factory defines any number of methods which return Products.

The Abstract Factory Pattern provides an interface for creating families of related or dependent objects without specifying their concrete classes. Elisabeth Freeman, Head First Design Patterns

Again in Head First Design Patterns, an Abstract Factory pattern is used to provide different Pizza ingredients depending on the type of Pizza. For instance, a ChicagoPizza would be given a ChicagoPizzaIngredients factory with methods like createDough, createSauce, createCheese, etc. A CaliforniaPizzaIngredients factory would also implement createDough, createSauce and createCheese. In this way the factories would be interchangeable.

The authors are keen to point out that the methods of the Abstract Factory (createDough, createSauce, etc) look very similar to the Factory Method (createPizza). One way of thinking about things is that an Abstract Factory can be composed of Factory Methods.

The Factory Method in JavaScript

Since I’ve already shown a basic Simple Factory let’s take a stab at doing the Factory Method in JS. We’ll continue with the PizzaStore theme since I’ve already spelled out how each pattern applies to it. We’re going to do this without the use of the new keyword and instead we’ll take advantage of JavaScript’s prototypes. How you ask?

The very awesome Object.create

ECMAScript 5 introduced a new method of the Object prototype called create. You can read up on it in full detail on MDN. In a nutshell it lets you pass in a prototype and receive a new object which points to that prototype. Object.create is actually a simple Factory Method! Here’s an example:

var firstPizzaStore = Object.create(PizzaStore);
firstPizzaStore.createPizza(); // returns 'Generic pizza created'

One very cool feature of Object.create is that it accepts a properties object which is then mixed in to the returned object. The code can get a little verbose since it uses defineProperty syntax so instead let’s steal a function from Yehuda Katz which lets us do something very similar.

var fromPrototype = function(prototype, object) {
  var newObject = Object.create(prototype);
  for (var prop in object) {
    if (object.hasOwnProperty(prop)) {
      newObject[prop] = object[prop];
    }
  }
  return newObject;
};

Now that we have that we can continue on our way. One quick caveat though! Some browsers *cough* IE *cough* don’t support Object.create so we need to shim it. Thankfully MDN has got our back:

// Polyfill
if (!Object.create) {
  Object.create = function (o) {
    if (arguments.length > 1) {
      throw new Error('Object.create implementation only accepts the first parameter.');
    }
    function F() {}
    F.prototype = o;
    return new F();
  };
}

Drop that into your page and you should be able to use Object.create like we are above. Note that the shim does not support the second properties object. For our purposes that’s ok but definitely keep it in mind if you’re thinking of using it.

Back to the Factory Method

With Object.create and fromPrototype in hand we’re ready to tackle our first Factory Method.

Let’s start by creating a PizzaStore:

// Define the Pizza product
var Pizza = {
  description: 'Plain Generic Pizza'
};

// And the basic PizzaStore
var PizzaStore = {
  createPizza: function(type) {
    if (type == 'cheese') {
      return fromPrototype(Pizza, {
        description: 'Cheesy, Generic Pizza'
      });
    } else if (type == 'veggie') {
      return fromPrototype(Pizza, {
        description: 'Veggie, Generic Pizza'
      });
    }
  }
};

Easy enough. Ok now let’s extend the PizzaStore so we have two variations: ChicagoPizzaStore and CaliforniaPizzaStore.

var ChicagoPizzaStore = fromPrototype(PizzaStore, {
  createPizza: function(type) {
    if (type == 'cheese') {
      return fromPrototype(Pizza, {
        description: 'Cheesy, Deep-dish Chicago Pizza'
      });
    } else if (type == 'veggie') {
      return fromPrototype(Pizza, {
        description: 'Veggie, Deep-dish Chicago Pizza'
      });
    }
  }
});

var CaliforniaPizzaStore = fromPrototype(PizzaStore, {
  createPizza: function(type) {
    if (type == 'cheese') {
      return fromPrototype(Pizza, {
        description: 'Cheesy, Tasty California Pizza'
      });
    } else if (type == 'veggie') {
      return fromPrototype(Pizza, {
        description: 'Veggie, Tasty California Pizza'
      });
    }
  }
});

// Elsewhere in our app...
var chicagoStore = Object.create(ChicagoPizzaStore);
var pizza = chicagoStore.createPizza('veggie');
console.log(pizza.description); // returns 'Veggie, Deep-dish Chicago Pizza'

The Abstract Factory in JavaScript

Since we have a variety of pizza styles we might also have a variety of ingredients. Let’s see if we can accomodate all the different kinds.

var Ingredients = {
  createDough: function() {
    return 'generic dough';
  },
  createSauce: function() {
    return 'generic sauce';
  },
  createCrust: function() {
    return 'generic crust';
  }
};

Ingredients.createChicagoStyle = function() {
  return fromPrototype(Ingredients, {
    createDough: function() {
      return 'thick, heavy dough';
    },
    createSauce: function() {
      return 'rich marinara';
    },
    createCrust: function() {
      return 'deep-dish';
    }
  });
};

Ingredients.createCaliforniaStyle = function() {
  return fromPrototype(Ingredients, {
    createDough: function() {
      return 'light, fluffy dough';
    },
    createSauce: function() {
      return 'tangy red sauce';
    },
    createCrust: function() {
      return 'thin and crispy';
    }
  });
};

In the above example Ingredients is our Abstract Factory. We know that for every different kind of pizza we’ll need different ingredients and therefore a new Factory Method. We also know that we have different styles of pizza so we’ll need Chicago style ingredients and California style ingredients. When a client wishes to grab some ingredients for a particular kind of pizza they just say:

var californiaIngredients = Ingredients.createCaliforniaStyle();
californiaIngredients.createCrust(); // returns 'thin and crispy';

The object that is returned by the call createCaliforniaStyle is the concrete implementation of our Abstract Ingredients object. In other words, if Ingredients is the Abstract Factory, then the object returned by createCaliforniaStyle could also be thought of as a CaliforniaIngredients object. It is a subclass of Ingredients if you want to think of it that way. The returned object extends Ingredients and overrides its Factory Methods with its own methods. In so doing we provide a lot of additional flexibility to our app. If we want to add a Hawaiian style ingredients we just add a createHawaiianStyle method.

If you recall from the previous article on Decorators we talked about the Open-Closed Principle which states that “classes should be open for extension but closed for modification.” You’ll notice that adding a createHawaiianStyle method would actually violate this principle so it should be noted that when using an Abstract Factory approach you’ll probably have to reopen the class/object a few times to modify it. Not ideal but depending on your use case this might not be such big deal and you might prefer the flexibility and organization that the factory offers.

Grab the Example Source

Related Patterns

• Template Methods: Factory Methods are usually called within Template Methods.
• Singleton: A concrete factory is often a singleton.

Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John (1994-10-31). Design Patterns: Elements of Reusable Object-Oriented Software. Pearson Education (USA).

Table of Contents

I want to go through some of what was said so I can refine my examples and also clear up any confusion.

That prototype example sucked!

OK let me start off by apologizing for even including that second example (the Sale decorators). It was meant as a kind of fun academic exercise but I tried to make it clear that I wasn’t suggesting anyone actually implement it. Redditor gizmo490 pointed out that for the pattern to actually work you would have to overwrite all the methods of the Sale object or risk working in the wrong context. You can see our full discussion here.

So I’ll just say if you’re considering that second example: Stop. Just don’t do it. It is way too much code.

We don’t necessarily need all those objects

Another Redditor, Draders, pointed out that the decorator objects aren’t really necessary since we can just put functions directly into the decoratorsList.

// This is presuming that `add` pushes a function into the
// list of decorators
validator.add('zipcode', validateZipCodeFunction);

If you want validateZipCodeFunction to be reusable you’ll have to define it somewhere and attaching it to the Validator object is probably a fine choice. In the end it’s a bit less code so definitely something to think about.

Finally, the power of CLOSURES!

Finally, and this is really the reason why I wanted to write this update, Redditor emehrkay pointed out that my examples are basically ignoring the power of JS functions and closures. In his quick and dirty example he shows how to achieve a similar goal with much less code:

function test(arg){
    return arg + arg;
}

function testDecorator(fn, args){
    var arg = args[0] * 2;

    return fn(arg);
}

function decorate(dec, fn, args){
    return function(){
        return dec(fn, args);
    }
}

x = decorate(testDecorator, test, [2])();
console.log(x)

So here’s my attempt to recreate the Sale example but using more of emehrkay’s approach:

function Sale(price) {
    this.price = price || 100;
}

Sale.prototype.getPrice = function() {
    return this.price;
};

Sale.prototype.setPrice = function(price) {
    this.price = price;
};

function usd(fn, context) {
    var price = fn.call(context);
    return "$" + price;
}

function decorate(dec, fn, context) {
    return function() {
        return dec.call(context, fn, context);
    };
}

// Let's run it!
var sale = new Sale(50);

// Decorate our getPrice method. We'll just add
// some extra dollar signs to the output.
sale.getPrice = decorate(usd, sale.getPrice, sale);
sale.getPrice = decorate(usd, sale.getPrice, sale);
sale.getPrice = decorate(usd, sale.getPrice, sale);
console.log(sale.getPrice()); // output: $$$50

// Test to make sure other methods can still
// access the price in the correct context
sale.setPrice(100);
console.log(sale.getPrice()); // output: $$$100

Since we’re kind of mixing OO and functional style here the one caveat is that you have to pass the context to your decorators so when they call getPrice they know which instance they’re referring to. So the code is a little funky but still interesting and if anyone can think of a way to write it cleaner I’m all ears!

Grab the Example Source

Update: Part 2 has been posted!

A Decorator is an object which adds functionality to another object dynamically. It can be used to enhance the behavior of an object without requiring the author to reopen its class. While Decorators might feel a little weird to implement in static languages they’re extremely simple in JavaScript due to the ease with which JS passes around functions and handles dynamic types.

Formal Definition

Attach additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

Also Known As

• Wrapper

When to use it

• When you’d like to add responsibilities to individual objects dynamically (i.e. without subclassing/inheritence).

• When you’d like to be able to remove the functionality at a later time. An undecorate method, for instance.

• When extension by subclassing would be unmanageable or lead to a class explosion. For instance, if a Vehicle class is subclassed by 30 other vehicle objects with only minor differences.

Pros and Cons

• Pro: More flexible than inheritance.

• Pro: Avoids feature-laden classes high up in the hierarchy.

• Con: A decorator and its component aren’t identical.

• Con: Lots of little objects.

A Brief Explanation

The Decorator pattern is very similar to one we’ve addressed earlier, called Strategy. The differences between the two can be subtle but usually a decorator enhances, layers upon or “decorates” the object or method it’s wrapping. In contrast, a strategy will replace a method’s algorithm completely.

The primary benefit of the Decorator pattern is that you can take a rather vanilla object and wrap it in more advanced behaviors. For instance a view which renders a plain window can have decorators to add different backgrounds, scroll bars, borders, etc. The underlying code, or guts, of the window object remains the same while the decorators provide a new skin.

Decorators are not limited to visual components. In fact much of the java.io package is composed of Decorators which add additional functionality such as buffering file streams and adding line numbers. A similar application to JavaScript might involve decorating I/O in Node.js. For instance, incoming data might need to be converted to ASCII and then compressed in some way. It might not always need to be converted to ASCII and it might not always need to be compressed. In this scenario we can apply or remove I/O decorators at runtime changing the behavior of our object instead of writing a big class with a bunch of cross-cutting concerns.

Enough Talk! COOOOODE!!!

Ok so let’s do an example. We’re going to create a Validator class which looks at the contents of a form and adds error messages to an array if anything in the form is not correct. We want our Validator to be really simple so it’ll just have two methods: validate and decorate. As the name implies validate will tell our validator to compare the form against its internal rules. We’ll use decorate to specify those rules. The decorate method will accept a String, such as ‘hasAge’ or ‘hasZipCode’ which corresponds to an actual function. We’ll collect these functions in a list and compare the contents of the form to each item in the list.

We’ll start with the constructor and decorate method:

function Validator () {
	this.errors = [];
	this.decoratorsList = [];
}

Validator.prototype.decorate = function(name) {
	this.decoratorsList.push(name);
};

We’ll collect any error messages in the errors array. We could write a method like validator.hasErrors() to check the length and contents of the array but for now I’ll leave that unspecified. Just know that if we do come across an error we’ll toss it in there.

The decoratorsList will hold all of our decorator functions. This is not how the Gang of Four does things, or how you will see the Decorator pattern presented in languages like Java or C++, but that’s because they’re using static languages which don’t do well with functions being passed around. In our case since JavaScript functions are objects we can pass our decorators into a collection to have them called sequentially. This is the easier approach recommended by Stoyan Stefanov in JavaScript Patterns. A little later I’ll show you the “hard” approach and you can decide which you prefer ;)

OK moving on… Let’s define some decorator functions. We’ll add an object to our constructor called decorators and we’ll attach our functions to it.

Validator.decorators = {};

Validator.decorators.hasName = {
	validate: function(form) {
		// Code to verify presence of name...

		// If no name found...
		this.errors.push('no name!');
	}
};

Validator.decorators.hasAge = {
	validate: function(form) {
		// Code to verify presence of age...

		// If no age found...
		this.errors.push('no age!');
	}
};

Validator.decorators.hasZipCode = {
	validate: function(form) {
		// Code to verify presence of zip code...

		// If no zip found...
		this.errors.push('no zip!');
	}
};

Each decorator is actually an object which implements the same interface as our Validator object. When we have all of our decorators added to our decoratorsList we’ll be able to loop through and call validate on each one.

Validator.prototype.validate = function(form) {
	var i,
		max,
		name;

	this.form = form;

	max = this.decoratorsList.length;
	for (i = 0; i < max; i++) {
		name = this.decoratorsList[i];
		Validator.decorators[name].validate.call(this, form);
	};
};