How Semantic Markup Helps Server-side Developers Write Reusable Code

    Meitar Moscovitz

    helpnote-code-teaserIf you spend most of your coding time working directly with the browser, you probably already know how much easier maintenance, testing, and rendering consistency all are when your markup is well-structured and semantic. The importance of separating content and presentation is not lost on you. Moreover, you know how to accomplish that separation well.

    If only you could write every single line of code in your next project, you’re certain it would be the cleanest, most maintainable website on the Internet! But websites are rarely the sole products of front-end developers, and in any project that involves a lot of programmatic heavy-lifting it can be a struggle to instill an appreciation for the benefits of a quality front-end codebase on even the most quality-conscious server-side programmers. Too often, what at first seems a minor instance of HTML semantics actually involves quite a number of implications beyond what’s evident to most people (including management and operations departments) in most projects.

    Recently, a colleague of mine (a very talented PHP developer), asked a fantastic question about just such a situation. In our project, we wanted to create a line break before the anchor text of a link appearing in notes, which would be rendered differently across the site. My solution was HTML that looked similar to this:

    <div class="help-note"><p>
        <span>Can you add a picture to the page about</span>
        <a href="..." title="Help us improve the article about 'Altocumulus clouds'">Altocumulus clouds</a>?

    and CSS like this:

    .help-note span { display: block; }

    My colleague wanted to know why I chose to use a span with an extra CSS rule to accomplish the line break in our artist’s design. Wouldn’t it be more natural, he reasoned, if we just used a div? That way, we could forgo adding CSS at all. Besides, aren’t div elements the same as span elements, except with display: block applied by default?

    This is a great question with which to illustrate the interconnectedness that markup has throughout many parts of a website’s codebase. Let’s take a look at some of these implications.

    Although practically speaking div and span elements are both intended to be meaningless, there is a subtle difference. This is not only in that the browser’s default styling of these elements is different but also, and arguably more importantly, the implications of logical grouping on a contextual basis.

    The W3C says:

    The div and span elements, in conjunction with the id and class attributes, offer a generic mechanism for adding structure to documents. These elements define content to be inline (span) or block-level (div) but impose no other presentational idioms on the content. Thus, authors may use these elements in conjunction with style sheets, the lang attribute, etc., to tailor HTML to their own needs and tastes.

    At first blush these may seem to be the same, but take a closer look at the wording: these elements define content to be inline (span) or block-level (div).

    In other words, the content itself suggests the appropriate element. Since the entire help note is logically a single sentence and is only intended to be split up onto multiple lines when styling is applied (and presumably not in, say, a text-only representation of the content since that would be weird for sentence structure), then a span element is the only one of these two that’s appropriate. movie downloads

    Using a span also has technical benefits. For example, assume our users like HelpNotes so much that we decide to use them in more places. We create a class, HelpNote, which has only one output method, with a signature like this:

      * Produces appropriate output of a note for help regardless of display context.
    public static function renderHelpNote( Object $title )

    This function is what back-end developers can use to output a HelpNote no matter where they call it from. So regardless of whether we use a HelpNote in a multi-part email or web page (for example), in PHP we can just say renderHelpNote( $title ) and be done with the call. This would be useful in, say, a loop or a template system.

    Now the question becomes, should the help note sentence use a span or a div? If we use a div, then we know that to create a list-item version of a help note, we have to add logic to the renderHelpNote function in order to omit the div, or to restyle the div as an inline-level element. If we use a span, however, then we’re not only sticking to the sentence structure, but we’re also remaining flexible by adhering to the notion of progressive enhancement, by styling only the most specific cases and letting the more general, low-fidelity designs go unstyled.

    Admittedly, this is the sort of precision and obsessive correctness that may be annoying or even senseless to a person unaware of the subtleties. However, I think that’s all the more reason to promote a proper separation of concerns.

    As a front-end developer, it’s unimportant to me how the list of help notes is ordered; I simply trust that there’ll be a list and that my colleague will have sorted it in the order he intended. Similarly, I don’t want to force my colleagues to care whether or not the line break will look right; I just want them to output the code and let me handle the display. The result with a span is more than just cleaner front-end code, it’s also simpler, more reusable server-side output logic.

    To me, it often feels like there’s a huge culture clash between back-end developers and front-end developers. The choices one group makes can seem crazy to the other. However, more often than not, just a little cross-functional education can go a long way towards writing code that’s better for us all. So ask questions, because techniques that help your colleagues are likely to help you, too.

    Update: I love how scrutinous everyone who’s been commenting on this post is! :) Some good points have been made, and some points of clarifications asked for, so I’ve tried to address these in the comments. Specifically, for instance, here’s why this example precludes the use of just styling the <a> element.