Web Design

Designing a Highly Reusable HTML Component

 

The UF College of Education uses a header/footer template designed to be applied to any page, and we use this across several applications such as WordPress, Moodle, Elgg, and Drupal. Changes can be propagated quickly to all sites, and adding the template to new PHP apps is trivial.

If you need to create an HTML component that can be reused across a wide set of sites/apps, these guidelines might help.

Avoid HTML5 elements if you can

HTML5 elements like header must be accompanied by JS to fix compatibility in old browsers. Sticking to HTML4 also helps with validation under HTML4/XHTML doctypes. Of course, if you’ll only be deploying to HTML5 sites that already have the IE shim, go ahead and use the best markup elements for the job.

Guard the host markup against the component CSS

Any component CSS selectors that match host markup elements can cause massive problems in the host application, and if this component is applied across an entire site, it’s very difficult to predict the impact. The key then is following a few simple rules for the component CSS:

  1. Each class/id name must be sufficiently unique such that there’s practically no chance of name collision. Unfortunately even selectors like .hidden and .clearfix could be implemented in different ways in the host app and this could cause problems. Using a constant prefix in every name might help.
  2. Each selector must include at least one of the component classes/ids.
  3. Avoid using a CSS reset/normalizer. If you must, make sure each selector follows the above rules so the effect of this is limited in scope to the component.
  4. Selectors must not match non-component elements. E.g. the selector #component-root + div should not be used because it would select a DIV element after the component.
  5. Take care to avoid obscuring elements in the host page. E.g. negative margins could pull the component over a host element.

Guard the component markup against the host CSS

Similarly, host CSS could break the desired styling of the component markup.

  • Test the component in a wide variety of pages and applications. Especially test pages that use common CSS resets and normalizers, and that have a lot of element-only selectors in the CSS.
  • When interactions occur, make the affected element’s selector more specific until the component CSS “wins”. As always, test across the browsers you need to support; IE7 still has some specificity bugs for the selectors it understands, if you need to care about that.

Javascript Tips

Expose as little to the global namespace as possible

E.g., define all necessary functions and variables inside an anonymous function that is executed:

!function () {
  // your code here ...

  // explicitly expose an API
  this.myComponentAPI = api;
}();

Document your script’s dependencies and let the implementor supply those

Automatically including JS libraries may break the host app. Consider the case of jQuery: Many plugins extend the jQuery object, so redefining it removes those added functions (actually stores them away, but it will break the host app nonetheless). Don’t assume the user did this right. Wrap your functionality in a condition that first tests for the presence of the the library/specific features you need, and make it easy for the implementer to realize the problem if they have a console open.

Here’s an example of how to test for jQuery’s on function:

if (this.jQuery && jQuery.fn.on) {
  // code
} else if (this.console && console.log) {
  console.log('Requires jQuery.on, added in version 1.7');
}

Assume the component could be embedded after the page loads, and multiple times

Carefully consider the initialization process your component requires. In some cases it’s reasonable to leave the initialization to be triggered by the implementer. If you do automatically use DOMReady functions like jQuery’s ready(), consider allowing the implementer to cancel this and initialize later.

String Subtypes for Safer Web Programming

 

Valid HTML markup involves several different contexts and escaping rules, yet many APIs give no precise indication of which context their string return values are escaped for, or how strings should be escaped before being passed in (let’s not even get into character encoding). Most programming languages only have a single String type, so there’s a strong urge to document function with @param string and/or @return string and move on to other work, but this is rarely sufficient information.

Look at the documentation for WordPress’s get_the_title:

Returns

(string) 
Post title. …

If the title is Stan "The Man" & Capt. <Awesome>, will & and < be escaped? Will the quotes be escaped? “string” leaves these important questions unanswered. This isn’t meant to slight WordPress’s documentation team (they at least frequently give you example code from which you can guess the escaping model); the problem is endemic to web software.

So for better web security—and developer sanity—I think we need a shared vocabulary of string subtypes which can supply this missing metadata at least via mention or annotation in the documentation (if not via actual types).

Proposed Subtypes and Content Models

A basic set of four might help quite a bit. Each should have its own URL to explain its content model in detail, and how it should be handled:

Unescaped
Arbitrary characters not escaped for HTML in any way, possibly including nulls/control characters. If a string’s subtype is not explicit, for safety it should be assumed to contain this content.
Markup
Well-formed HTML markup matching the serialization of a DocumentFragment
TaglessMarkup
Markup containing no literal less-than sign (U+003C) characters (e.g. for output inside title/textarea elements)
AttrValue
TaglessMarkup containing no literal apostrophe (U+0027) or quotation mark (U+0022) characters, for output as a single/double-quoted attribute value

What would these really give us?

These subtypes cannot make promises about what they contain, but are rather for making explicit what they should contain. It’s still up to developers to correctly handle input, character encoding, filtering, and string operations to fulfill those contracts.

The work left to do is to define how these subtypes should be handled and in what contexts they can be output as-is, and what escaping needs to be applied in other contexts.

Obvious Limitations

For the sake of simplicity, these subtypes shouldn’t attempt to address notions of input filtering or whether a string should be considered “clean”, “tainted”, “unsafe”, etc. A type/annotation convention like this should be used to assist—not replace—experienced developers practicing secure coding methods.

Bookmarklet: Horizontally invert HTML5 videos

 

My demands for “reverse” glasses have gone unserved, but I made a bookmarklet that provides the same effect: “flopping” a video horizontally.

  1. Install the SwitchStance bookmarklet, for which you’ll need a modern browser that supports CSS transforms on video elements.
  2. Opt-in to YouTube’s HTML5 trial
  3. Load up any video without ads (here’s one of Matt Hensley skating)
  4. While the video plays, click the bookmarklet.

The video will mirror and you’ll see Hensley, a regular-footed skater, now skating goofy foot (in “switch stance“). Or you can get Paul McCartney to play guitar right-handed.

Designing a Contextual Role-Based Capability Control System

 

Update May 2: ScopedRole is now a PHP5.3 library based on this design and is passing initial unit tests!

After surveying a few permissions models that one might want to choose for an LMS, I think Moodle really got right the notion that role-based permissions should be flexible depending on the domain(s) the user’s in. Unfortunately Moodle’s implementation is completely bolted in, so I started looking around for a standalone implementation (few dependencies, no globals/state) of something similar.

For PHP dating back to 2002, phpGACL is designed and documented really well. It’s truly a drop-in solution with some advanced functionality, but doesn’t quite cover the concept of contextual roles, so it doesn’t quite cut it. What I’m imagining is something very similar but ideally without forcing a particular DB abstraction library on you.

Using the awesome WWW SQL Designer, I designed a bare-bones schema for the data:

Schema diagram for Contextal Role-Based Capability ControlThis is loosely based on Moodle’s schema, but I removed quite a lot, not only in hopes of getting it working quickly, but also because most implementers will have varying needs. E.g., implementers may need to localize role names and descriptions by language, so simple keys are all this schema is responsible for storing. I also removed special feature-related columns on the entities and link tables: the implementer is free to add columns as needed or just reference the id on each table. I’d imagine most folks dropping this into, e.g., a Zend Framework app just won’t need most of the features that Moodle had in there.

Also note it would come without a users table. The implementer will provides the system with unique integers for each user and that’s all it should need to do its job. You’re free to join the tables to create whatever views you need.

Any ideas for a catchier name than “Contextual Role-Based Capability Control System”? ScopedRole?

IE6/7 CSS Specificity Bug

 

After our team launched the new College of Education site, I discovered that IE8’s handy “Browser Mode: IE7” mode of IE8 is useless for real IE7 testing (but IETester actually works!). Undoubtedly this “IE7 mode” has many quirks in its emulation we’ll never know about, but after a few hours of hair-pulling I finally pinned down a real IE6/7 bug that the emulator doesn’t have.

IE versions before 8 apparently vary in their calculation of CSS specificity depending on the order of elements in the selectors. What this means for poor suckers who worry about IE6/7 is that rules that appear later and (should) match specificity won’t always override values. E.g.

<div id="foo"><div id="bar">I should be green.</div></div>
/* both rules have the same specificity */
#foo div  { background:red   /* IE6/7 apply this value */ }
div  #bar { background:green /* correct value to apply */ }

This bug will hit you when you’re pursuing a good goal: trying to keep selectors short. So in these situations make sure to test in IETester at the very least and leave a comment to let future CSS editors know why a selector is longer than needs to be.

We need a frontend design tool for live web pages

 

It’s quite frequently that an HTML/CSS designer might want to make changes to a live web page. Maybe she doesn’t have write access, or maybe the fixes needed aren’t worth the start-up cost of copying the page locally and working on it there, or multiple designers want to work up ideas on a given page simultaneously. The “Inspect Element” capabilities of most modern browsers will let you make HTML/CSS changes to a live page, but navigating or refreshing causes those changes to be lost, and they’re hard to keep track of.

Here’s a feature wishlist:

  1. keep track of “Inspect Element” user changes with the ability to save them locally
  2. keep changes in discrete “changesets” that can be re-applied, or saved as a unified patch of the original files, or at least as the modified original files
  3. allow swapping page CSS files with user-controlled CSS files (e.g. file:/// or htttp://localhost/)
  4. allow swapped CSS files to be periodically “refreshed” so the user wouldn’t have to switch between CSS editor and browser.

Firefox’s Stylish extension looks to come close to (3), allowing you to add user styles to a page/site, like Greasemonkey does for Javascript. It doesn’t look like the editing experience is great, though.

You can manually do (3) and use the CSS Reload Every bookmarklet, but it reloads all CSS, which is kinda of jarring.

A bookmarklet could implement (3) and (4) and persist its settings in a cookie.

Other ideas?

Update: Here’s a bookmarklet that let’s you swap CSS files and stores its settings in a cookie for the current page. Next step is for it to allow adding files and controlling the cookie path.

You must enable Javascript! (right-click, add to favorites or bookmarks)

(CSSswap source).

Email Address Munging Still Mitigates Harvesting

 

At least a decade into the use of simple email munging on web pages (my own solution here) there’s a growing consensus—and it seems like common sense with the advancement of the web in general—that this surely can’t still work on modern harvesters. While trying to look up some old research I’d read about this, I came across this January 2010 post by a Project Honey Pot admin:

We’ve run tests on different munging techniques and find that they are still surprisingly effective. We have a page that has a set of differently munged addresses. The ones protected by Javascript have yet to receive a single message. Even simple things like using ASCII character encoding to hide the @ sign, or adding spaces to the addresses, is surprisingly effective at stopping harvesting.

Whether to munge or not is kind of a religious war, but I see this as pretty convincing evidence that munging isn’t obsolete just yet. Of course this or any other single prevention strategy isn’t a “solution”, but mitigation of the inevitable is still arguably worthwhile, especially for people without the luxury of having top notch admins run their mail server.

Using jQuery Before It’s Loaded

 

It’s better to include scripts like jQuery at the end of the BODY, but this makes its methods inaccessible earlier in the page (e.g. inside a WordPress post). What you can do is use a script like the one below to queue DOMReady functions before jQuery loads.

(function (w) {
    if (w.$) // jQuery already loaded, we don't need this script
        return;
    var _funcs = [];
    w.$ = function (f) { // add functions to a queue
        _funcs.push(f);
    };
    w.defer$ = function () { // move the queue to jQuery's DOMReady
        while (f = _funcs.shift())
            $(f);
    };
})(window);

Minified:

Setup

  1. Link to the script in the HEAD or at least before your typical page content area
  2. Link to jQuery at the end of BODY
  3. Below jQuery, include: <script>defer$()</script>

Now in the BODY you can use $(function(){ ... }); to queue up a function as if jQuery were already loaded. And, thanks to the fact that Javascript identifiers are referenced at run-time, you can call any other jQuery functions inside your queued function.

With some modifications you can use this pattern for any library with a similar DOMReady implementation.

Tiny Email Munging Script

 

I’ve seen a lot of these that are bloated/less effective/inaccessible, so I might as well put this out there. It’s simple enough to modify if you’re comfortable with Javascript.

Markup: <a href="mailto:john{@}example{.}org">john{@}example{.}org</a>

(function(){
  var a, i = 0, o = this.onload;
  onload = function(){
    o && o(); // run the old window.onload if existed
    while (a = document.getElementsByTagName("a").item(i++))
      if (0 == a.href.indexOf("mailto:")) {
        a.href = a.href.replace(/[{}]/g, "");
        a.innerHTML = a.innerHTML.replace(/{(.)}/g, "$1");
      }
  };
})();

Minified 234B:

for jQuery 150B: