Keeping dynamic HTML classes easy to find

The Problem

I imagine many of us have been there: there’s some CSS class in your markup, and you need to do something with it. Maybe you want to remove it, change it, or perhaps alter its style declarations. “Easy peasy,” you think, “I’m a developer. I got this.” And so you should.

Next, if you’re anything like me, your first instinct is to fire up your search tool of choice and search your codebase for that string. You’d expect that would lead you to where that class is getting added to your markup, along with anywhere CSS rules are applied to it… right?

Except it doesn’t. Phooey. That class string doesn’t appear anywhere except in your browser's dev tools. At this point, you either toss your developer pride overboard and hack a fix in some other way, or you search for assorted variations of your string in ever shorter segments until you find something resembling this:

$classes_array[] = 'some-' . $class;

Aha! It was helpfully obfuscated for you. And of course, you could hardly expect to simply search for that class name and find its CSS rules. That would be too easy! So naturally, they were written in SASS like this:

.some-#{$class} {
   // Some declarations…
}

Now that’s just what it might look like in PHP and SASS, but I’m sure you can imagine what it might look like in your templating language, javascript, or whatever CSS-pre/postprocessor you might abuse.

The point is, you’ve gotta slow down and tread a little more carefully here; this isn’t a simple find-and-replace job anymore. There are a few reasons why such code might have been written:

• The latter half of that class might originate from a fixed list of options exposed to your content editors.
• Perhaps there’s some other logic in play, that has intentionally been kept out of the CSS: your element gets a class based on its region or container, for example.
• Your colleagues are actively trying to make your life difficult.

If you’ve never been in this situation - good for you! Future-you called and asked that you avoid munging together parts of a CSS class like this if you possibly can. Do it for future-you. Don’t let them inadvertently introduce bugs when they fail to spot your class-munging!

The solution

“But what if,” I hear you cry, “I need to generate a class dynamically. How can I keep future-me on side?”

Well, dear reader – I hear you. Sometimes you really don’t want to explicitly list every possible variation of a class. Fair enough. So I have a proposal, one that I’d like a nice name for but, y’know, naming things is hard. Maybe the “Searchability class” pattern. Or “CSS search placeholder classes”. Or “CSS class search flags”. Suggestions on a postcard.

Anyways, returning to our earlier PHP example, it looks like this:

$classes_array[] = 'some-%placeholder'
$classes_array[] = 'some-' . $class;

Producing markup like this:

<div class="some-%placeholder some-arbitrary-suffix"></div>

That is: wherever you add a dynamic class into your page source, additionally put a recognisably formatted, static version of that class alongside it. That would also include anywhere you generated classes in JavaScript or any CSS-pre/post-processing madness.

Obviously, you don’t need these placeholder classes in your actual CSS (if you wanted to edit the static CSS, the regular class will already show up in searches) but if you are doing this in some dynamically generated CSS, then you’ll want to drop the static version of the class in as a comment. So our Sass example would become:

// .some-%placeholder
.some-#{$class} {
  // Some declarations…
}

Once this becomes an established practice within your team, instead of fumbling around trying to find where a given class may have come from, you’ll be able to spot those placeholder strings and search for those, and relatively quickly find all the relevant bits of code.

So I think this is something we’re going to try to adopt/militantly enforce upon ourselves at ComputerMinds. As a Drupal shop, something like %placeholder makes sense, as that syntax is used elsewhere in core to denote dynamically replaced parts of a string. It also has the advantage of being slightly tricky to actually use in a CSS selector (if you don’t already know, I’m not going to tell you). You really don’t want any styling attached to these.

So there you have it – the “Searchable CSS class placeholder flags for generated class names” pattern. We’ll keep working on the name.