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">
	<?php
		screen_icon();
		// 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>
</div>
<?php
}

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

Styling the Really Simple Gallery Widget

The Really Simple Gallery Widget has some very light CSS selectors in the HTML for you to apply your styles to. They amount to this: there is an outer div with the class “rsgallery”, each image is given a class of “rsg_image”, and captions are given a class of “rsg_caption”. There are no current plans attach stylesheets, but some better structure and/or options for classes may be provided in a future version.

Examples:

/* Add some space (20 pixels in this example) under each image */
.rsg_image { margin-bottom:20px; }

/* Add a border that changes when moused over
Important: don't forget that you need to add double the width of the border to the image width to get the total */
a .rsg_image { border:1px solid #00F; }
a:hover .rsg_image { border: 1px solid #F00; }

/* Create a grid of images - will not work with captions in the current version. Adjust the margins to fit in the width of the widget area - there will be leftover margin on some sides
Be careful - the floating may cause your layout to behave strangely, especially anything that follows the gallery widget */
.rsg_image { float:left; margin:0 20px 20px 0; }

To add CSS to a theme that you can’t edit, try using the the Simpler CSS plugin. Remember that if you edit a CSS file in a downloaded theme like Twenty Ten, it will probably get overwritten if you upgrade the theme in the future. Make a child theme instead.

Hiding the search form in the 3.1 Admin Bar

I love the new admin bar in WordPress 3.1, but the search box just isn’t needed for Eastman thanks to a combination of things. For the Eastman site, we are not using the built-in WordPress search in the usual way. We are also not directing all searches through Google, so having search.php just completely redirect doesn’t. We also already have a site search box in the header, anyway, so it’s kind of redundant (even if it’s just web editors who are seeing the admin bar search).

I looked into the rendering code for the admin bar and didn’t see a hook to manipulate the search box like there are for other menu items. This seems rather unfortunate to me and I may ask the question on wp-hackers later on tonight to see if I’m missing something, but I figured I could probably use CSS to hide it for now. I mean, it’s not like ESM web editors are going to use Firebug and resurrect the form (and I’d have to admit that I’d be really impressed if any of them could do it), and it’s not like the search itself is nonfunctional, it just doesn’t quite behave the way you think it might when searching the entire site. Now, because I want to create a consistent experience, I want to be sure that the search box doesn’t show even if the rare network site uses a different theme, so I figured I’d make a simple plugin and network activate it. So, here goes the plugin:

<?php
/*
Plugin Name: Hide Admin Bar Search
Plugin URI: http://www.helenhousandi.com/wordpress
Description: Uses CSS to hide the search box in the admin bar. Helpful if you don't use the built-in WordPress search like usual.
Version: 1.0
Author: Helen Hou-Sandi
Author URI: http://www.helenhousandi.com
*/

if ( !function_exists('hide_admin_bar_search') ) {
	function hide_admin_bar_search () { ?>
		<style type="text/css">
		#wpadminbar #adminbarsearch {
		display: none;
		}
		</style>
		<?php
	}
	add_action('admin_head', 'hide_admin_bar_search');
	add_action('wp_head', 'hide_admin_bar_search');
}

What we are using the built-in search for: the News Room (a category) and Faculty (a custom post type). The one for Faculty does something pretty cool – to be written about more at another time.