Can markup and CSS be backwards compatible?

Backwards compatibility, or back-compat, is a big part of what is taken into consideration in WordPress development, especially when it comes to core itself. It can be time consuming, and some consider it wasteful, but I would venture to say that it’s this dedication to preventing things like fatal errors on upgrades that helps WordPress be as widespread as it is. I know that when I started playing with self-hosted software on the web, I would never have chosen something that required manual updates and/or made it clear that if I chose to update I was absorbing all the risk, and I generally imagine that I’m not alone in something that I think or feel.

One of the things I’ve been thinking about recently is how back-compat works when it comes to my core comfort zone of UI, particularly markup and CSS. Within the WordPress admin, there is quite a bit of markup and CSS that derives from things that are added via API. Metaboxes are a prime example – you use the add_meta_box() function, and the containing markup is generated for you, with your callback function dictating the contents and markup of what appears inside the metabox itself. But what happens when somebody wants to use the current markup in the admin outside of that function, nevermind the reason why? Well, they grab it, copy-paste it into whatever they’re doing, and just like that it will utilize the existing CSS. I mean, it doesn’t sound like a tragic idea. But then, if/when we change the add_meta_box() function and the markup, or even the markup that surrounds a given metabox area, it breaks. So, developers understandably come asking questions, and fortunately are often understanding, but it’s frustrating for everybody involved. It sucks to have something just break, and it sucks to have caused it.

There are also areas where the API does not generate any sort of standardized markup as a wrapper – add_menu_page() is one of them. You provide a callback function, such as with add_meta_box(), but to get your admin page looking like the rest of the WordPress admin, you end up with this as a starting point (as of this writing):

function my_custom_page_callback(){
<div class="wrap">
		// won't show anything without adding CSS to specify the image if it's a top level menu!
	<h2>Test Title</h2>
	<p>Admin Page Test</p>

I think this poses a bit of a barrier to creating a basic admin page that provides a seamless user experience, and sort of undermines any wondering/complaining one might do about why developers don’t integrate their custom additions into the WordPress admin UI. It also means that if we change the structure of admin pages in the future, everybody who’s written a custom menu page will be left scrambling to make it match again. Luckily, in this case it’s not really ugly or non-semantic markup, so we may not have to worry about the “what if” of changing it, but it still begs the question.

Let’s say I were to advocate for having add_menu_page() output that typical wrapping markup (completely hypothetical, if you please). Well, I’d have to advocate for it being able to output that markup, not just doing it, and that ability to output the markup would have to be off by default for, you guessed it: backwards compatibility. It would be super bad to have a function suddenly start outputting markup that a plugin or theme author has probably already added themselves. But, that also means that developers have to turn something on rather than getting default good treatment. Would it have to stay that way forever? Could we ever have it become a default or will it remain tied to a legacy? I would not advocate for it being enforced, as the possibility of an admin page not needing some of the markup is there and should not be disallowed.

The other thing we have to worry about is just generally re-styling things. The thing I think WordPress’s giant admin stylesheet is most missing (besides sanity) is the providing and self-usage of what I refer to as reusable components – that is, provisions for form styling, a structural grid, etc. that can and should also be used by a developer adding on to the admin. Ideally, if we were to restyle something, anybody using the appropriate markup/classes wouldn’t have to do much of anything to stay integrated in the UI. As various admin UIs are added or revamped, we are certainly doing a much better job of heading in the direction of components (see: new buttons), but the legacy of what exists remains, and it can be very difficult to remove or rename anything. It’s also extremely time consuming to test possibilities and do things like search through the plugin repo to see who’s doing what.

In 3.5, Koop and I contemplated just adding the .wp-admin class to the media modal so that buttons could be scoped in when used on the front end and not impact themes. Too bad we found things like .wp-admin { margin-top: 0 }, or even better, JS that was using the .wp-admin class to detect whether or not it was being used in the admin without further specifying that it should be on the body element, as it is in the admin. Here again, we are talking about things that are not good practice, or even just straight up bad practice, but can we really go that route if it has side effects that are not the end user’s fault? Probably not. So we chose to add .wp-core-ui to places as a scope helper instead, and now I get to worry about usage/abuse of that class beyond its intention of scoping and declaring that the contained markup uses WordPress core styling, like the media modal or wp_editor() on the front end.

So, what happens if we just start removing CSS that core no longer uses and is not component-related? Do we move it to a back-compat CSS file and advise developers to enqueue it if they find it necessary? How ugly would THAT file get, and how quickly? When does something get retired from that file, or does it? Maybe it would just stay there forever, like deprecated.php, except that the size of a CSS file does impact the end user.

Also unlike PHP, we can’t designate markup or CSS as being internal/private use only. So long as it exists, it’s fair game for use. But, does that mean we’re now beholden to supporting these non-core but obviously currently working additions? Are we going to drive people away from building on WordPress if our answer is always “well you shouldn’t be doing that in the first place”, especially when we don’t (and perhaps can’t) explicitly say “don’t use this markup/ID/class”? What do projects like Bootstrap or jQuery UI do when it comes to updates? What differences and difficulties are encountered because WordPress is distributed, self-installed software that can be infinitely extended in infinite combinations?

At this point, I have more questions than answers (if I have answers at all), and would love to hear any experiences or opinions people have or have had when it comes to their additions to the WordPress admin and keeping it looking and feeling smooth. Who knows what I personally can actually do about it, but I love thinking and learning, it is open source software, and WordPress is all about the community 🙂

Can markup and CSS be backwards compatible?

6 thoughts on “Can markup and CSS be backwards compatible?

  1. There’s two parts of core CSS that I’ve tried to use and been bitten by changes to it. The first one is the .star-holder class for holding ratings, where the markup changed in 3.4 and ruined it completely. One of the things that would have helped immensely here is a helper function to output all the markup needed, which would have meant that it could have been both backwards- and forwards-compatible with WP.

    The other component I’ve tried using and had problems with is using the new media overlay’s styling as a replacement for thickboxes. The problem here is that both the markup and CSS is linked very heavily into media and is unreliable outside of that context.


    1. I think you are totally right about the star ratings markup – we should probably use a helper function for that instead, because who knows where it’ll be used next, whether in core or by a plugin/theme.

      As for the modal replacement, I don’t know how it all fits together… yet 🙂 Honestly, I’m not sure it’s currently imagined as a general modal, but we should see if it can be used as a jumping off point for finally killing off the rest of Thickbox. We’re almost there, though – I think it’s just plugin details that are left?


      1. Yep, plugin details are one of the only places as far as I know (also where I wanted to use the new-style modals). In the mean time, I’m duplicating the CSS and modifying the class names to ensure compatibility.


      2. funkatronic says:

        It would be nice to have the modal be generalized. All of the classes have the .media prefix on them. I’ve basically had to copy the rules and renamed the for my own purposes.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s