In a post a few months back, I discussed how custom elements needed an easy way to fill in slots defined by their base classes. The capable folks on Google’s Blink team have now fixed this problem with a small but critical Shadow DOM change, and I wanted to take a moment to walk through an example of how the feature works and explain why this is so cool.

What does “filling in a slot” mean, and why does it matter? The crux of the issue, for us to be able to share web components, I need to be able to create a new web component that defines some, but not all, of its appearance. I need be able to define certain places that you can fill in with your content. Those are the slots: points of visible user interface extensibility.

Example: a series of page templates

The post linked above offers a simple button example, but let’s walk through a more realistic example using a series of page templates. (If you have Google Chrome Canary installed, you can follow along with a live demo.) These sample templates will span a range of general-purpose to very specific. For the sake of clarity, the examples are overly simple, and are intended just to convey a sense of how such templates might be used to build a simple online store app. The same principles shown here could easily be extended to arbitrarily complex interfaces.

A page-with-toolbar

We start with a completely general-purpose <page-with-toolbar> element that defines a page with a toolbar. For the sake of argument, let’s suppose there’s something fancy about the presentation here — perhaps the toolbar starts out at one size, and then, as the user scrolls, the toolbar becomes smaller and permanently docked at the top of the page. Regardless of what exactly makes this interesting, let’s assume that interesting stuff entails web ninja tricks the average designer or developer doesn’t have the time to learn or implement for themselves. Significantly, some aspect of the toolbar behavior requires real code, not just CSS styling.This user interface pattern is completely general-purpose, so perhaps this template is found in an online library of general-purpose web components. The key extensibility feature here is that the element defines two slots which consumers of the <page-with-toolbar> element can fill in: a toolbar slot at the top, and a main content slot.

A store-page partially fills in a page-with-toolbar

This second image shows a <store-page> element that forms the standard base for all pages in our hypothetical online store. This element subclasses (extends) the general-purpose <page-with-toolbar> element above, so it automatically picks up the structure defined by that element and the fancy toolbar behavior. The designer of the store app can fill in some of that structure with elements that should be visible on every page in the store, such as a Home button and the story name. That is, the designer can partially fill in the slots defined by the base class: after adding the standard elements they want on every page, they can define new slots that can be filled in by instances or subclasses. The designer can also add visual styling and any behavior that should be available on every page in the app. When complete, this page both extends the above element, and is itself extensible. The element is specific to this company, but could be used by any team at the company working on their online store.

A product-page partially fills a store-page

The third image shows a <product-page> element. This extends the <store-page> element above to create a template for any page specifically in the app’s Products area. It fills in the toolbar slot with buttons that are only available on product pages. It also partially fills in the main content slot with a header for the product name. Finally, it adds any styling and behavior shared only by pages in the Products area. This product page element is still extensible, but an increasing portion of its interface and behavior are constrained.

A completed instance of product-page

Finally, we have an example of a filled-in <product-page> element. Presumably the app fills in the page by obtaining product data and used that to populate various elements on the page (e.g., using data binding). Now the whole page has been filled in.

By factoring our app’s design this way, we’ve created a good separation of concerns. The <page-with-toolbar> element doesn’t have to know anything about online stores. Conversely, the <store-page> element doesn’t have to know anything fancy toolbar behavior. The <product-page> designers don’t even need to know where the toolbar behavior comes from — all they need to know is that they get it for free. If the team at the company that owns the <store-page> element later decides to change the toolbar behavior, they can do so without the people who own the <product-page> element needing to do anything.

How does this work?

Until recently, it wasn’t possible for a custom element to fill in slots defined by a base class this way. An element’s template could contain a <shadow> element to ask its base class to render its stuff, but there wasn’t an easy way to pass content to the base class. Over the past couple of months, the Blink folks working on Shadow DOM features have just addressed this shortcoming with a new feature in the Shadow DOM spec and its Blink implementation. Technically speaking, the spec now allows a custom element to distribute nodes into a <shadow> insertion point and then reproject those nodes into an older shadow root.

To see an example of how this works, see the live demo. At the time of this post, you’ll need to use Google Canary. You’ll also need to open chrome://flags and check “Enable experimental Web Platform features”. But this feature will likely make its way into production Chrome in the not-so-distant future, and get polyfilled by the Polymer project for other browsers.

You can look through the code for the complete story, but the gist is this: if your element puts stuff inside a <shadow>, then that stuff will be passed to the base class as content. In our <page-with-toolbar> example element, the template contains a bit for the toolbar that looks like this:

<polymer-element name=”page-with-toolbar”>
<template>
  …
  <div id=”toolbar”>
    <content select=”.toolbar”></content>
  </div>
  …
</template>
</polymer-element>

That <content select=”.toolbar”> bit creates a slot that can be filled in by instances — or by subclasses. When our <store-page> element subclasses <page-with-toolbar>, it fills in that slot:

<polymer-element name=”store-page” extends=”page-with-toolbar”>
<template>
  <shadow>
    <span class=”toolbar”>
      <button>Home</button>
      <content select=”.toolbar”></content>
    </span>
    …
  </shadow>
</template>
</polymer-element>

Everything inside the store-page’s <shadow> will look to the page-with-toolbar base class like regular content. The page-with-toolbar’s toolbar slot will grab the span with class=”toolbar”, so the store-page’s Home button ends up in the toolbar. This lets store-page fill in the toolbar slot defined by page-with-toolbar.

So that store-page itself can be extended, it in turn redefines that toolbar slot. Any toolbar buttons defined by subclasses of store-page (like the Add to Cart and Buy Now buttons in our product-page example) will get picked up by store-page’s toolbar slot, which is nestled inside page-with-toolbar’s toolbar slot.

Conclusion

Sometimes tiny differences in fundamental features, like this refinement to the <shadow> behavior, can open up new realms of possibility. While it doesn’t look like much, when combined with subclassing, you’ve just been given a powerful new tool for creating custom web elements. You’ll be able to create a wide range of new general-purpose elements that can be filled in by other people to suit their needs, and you’ll be able to fill in general-purpose elements created by others to suit your own needs. This is a huge step towards a vibrant ecosystem of web user interface components.

Beyond the expanded capabilities enabled here, I’m personally excited to see this change because I’ve been advocating for it for so long. I made a pitch for this on a visit to Google back in May 2012, and have promoted the idea in various forums since then. Other people like Scott Miles at Google also lobbied for the same thing. Special thanks are owed to Scott and to Dominic Cooney for contributing their own weight behind this idea and building the momentum required to make it happen; to Blink developer Hayato Ito for his work updating the spec and implementing the feature in Blink; and to Dimitri Glazkov for his careful oversight of the Shadow DOM spec. This is one spec change that was totally worth the trouble!

Just an update to the experimental Quetzal project I posted about last month. I’ve learned quite a bit, and have changed course on two significant points, and thought I’d share a bit about my experiences with others who might be contemplating the creation of a framework or UI component library on top of web components.

A limitation of the current web component architecture

So far, the greatest challenge in replicating the range of expression in QuickUI’s UI components has been the inability to easily define HTML custom element subclasses that can fill in base class insertion points. To their credit, Google’s Blink (rendering engine) and Polymer (web component framework) teams have been responsive on that point. In response to a Polymer discussion board thread related to that post, a bug has been filed to allow one to distribute content nodes into a <shadow> insertion point. Unless you’re already experimenting with Shadow DOM, this entire issue undoubtedly seems quite arcane, but rest assured, fixing this one problem would open up a lot of important new territory.

I’m sincerely hoping this proposal is adopted. In the meantime, I’ve been using a workaround to simulate the effects of that proposal. That unfortunately broke in a recent Polymer update, but such setbacks are to be expected when building on shifting sand.

Trying Polymer elements

I’ve spent some time experimenting with Polymer’s own element layer, and last month decided to try adopting it. My first cut at creating custom elements for Quetzal was based directly on Polymer’s lower levels, which take care of polyfilling (emulating) various web component standards. I’m now trying to use the higher-level Polymer elements layer, which provides a richer framework for creating custom elements, and adds a number of features to simplify common component tasks. These features are not part of any web component standard, but by virtue of being done by Google, will nevertheless probably become a common feature of the web component landscape.

There are still a number of QuickUI features that have no parallel in standard web components or Polymer elements, but most of those missing features appear to be things which I could implement on top of Polymer elements. For example, a <quetzal-element> base class could provide those missing features, making it easy for new element classes to obtain them. Aside from the critical limitation mentioned above, it now appears to me that most (hopefully, all) of QuickUI could likely be implemented as Polymer elements.

With that change, the latest Quetzal iteration recreates a handful of QuickUI Catalog elements as Polymer elements. So far, this approach feels acceptable, and it would obviously be a big advantage to leave most of the heavy lifting to the Polymer team, and focus on actually creating new custom elements.

Some notes on switching to Polymer elements:

• Using HTML to declare an element template feels quite verbose and cumbersome compared to QuickUI’s use of CoffeeScript’s concise JavaScript object format. If you haven’t tried CoffeeScript, it improves over plain JavaScript object syntax by using indentation instead of requiring tons of curly braces and commas. Using HTML feels comparatively ponderous and noisy, and to me all that noise makes custom element source files somewhat less legible. Still, HTML is the lingua franca of the web, and using a standard confers a huge advantage over a proprietary format, however efficient it might be. At some point, the Polymer team says they’ll support an imperative JavaScript means to define custom elements, but for now I’m guessing the vast majority of custom elements will use HTML, so that’s what I want to try.
• Speaking of standard formats, one aspect of Polymer that’s recently changed is that the top-level tag used to define a new element is now <polymer-element>, instead of the standard <element>. While Polymer elements are now just as locked into the Polymer framework as before, this change makes it feel like I’m no longer using a web standard — it feels like just another proprietary UI framework that happens to use XML/HTML as its format. It’s surprising what a difference this small change makes. Using <element> simply felt better.

Going back to plain JavaScript

Switching the top-level component container to HTML instead of script has also prompted me to give up CoffeeScript, at least for now. I actually tried using a combination of CoffeeScript and HTML, but it felt like I was working against the grain, and I ended up giving up on that approach.

Going from CoffeeScript back to plain JavaScript is an excruciating experience. Oliver Wendell Holmes said, “Man’s mind, once stretched by a new idea, never regains its original dimensions.” I think the programming language analogue here is: once your brain has been expanded by a language that lets you more clearly express your intensions, trying to cram your brain back into the tiny box of a less expressive language is unbelievably painful.

Every single time I have to write a JavaScript loop instead of a CoffeeScript list comprehension, or type “function() {}.bind(this)” instead of just “=>”, I physically wince a bit. JavaScript just feels gross, it looks gross, it is gross.

That said, JavaScript is the standard. One thing I’ve learned from QuickUI is that if you’re trying to build a community around a common library, creating that library in a programming language with a narrow audience dramatically limits the rate at which you can grow. One commenter named “jokester” offered on my original Quetzal post: “I’ll unfortunately not contribute to a project coded in CoffeeScript.” Regardless of the advantages I believe CoffeeScript offers to developers, I’d rather allow orders of magnitude more people to contribute in the standard JavaScript language they’re already proficient in.

Anyway, that’s about the state of things. This Quetzal project is still just an experiment, and doesn’t do much useful yet, but it’s proving a good way to learn.

At last week’s Google I/O 2012 conference, Chrome engineers Alex Komoroske and Dimitri Glazkov gave a talk called, The Web Platform’s Cutting Edge, a good overview of Web Components and custom elements in particular. The demo code shown in that presentation does point to an issue with the current Web Components spec that could seriously constrain the ease with which components can be written and shared. I’ll lay out the case here in hopes this problem can be fixed at an early stage.

But first: A word of appreciation

Authoring a spec for a new standard like Web Components is generally a thankless task, as is the tireless work of promulgating the standard through presentations like the one at Google I/O. So, before saying anything else: a big Thank You to Alex and Dimitri for their work on HTML Templates, Custom Elements, and Shadow DOM. Everything which follows is meant to support your work, not put it down.

Background of the problem

As I’ve blogged about before, I’m a passionate fan of web UI components and believe they will transform UI development. The ability to define new elements for HTML is something designers and developers have long wanted but, until now, could only dream about. In the demo, Alex and Dimitri use Chrome’s early implementation of the proposed spec to create custom elements. They elegantly combine these elements to produce a custom UI component for a user poll:

This poll user interface is a large component comprised of sub-components for accordions (or, later in the demo, tabs) and the big iconic choice buttons in the poll for “Semantics”, “Offline & Storage”, etc. All these components are defined with declarative markup.

I enthusiastically agree with the presenters that declarative HTML, including the ability to define custom elements, results in UI code that can be easier to read than a comparable imperative solution in JavaScript. And to its credit, most of the demo code shown in the presentation is self-explanatory.

However, one aspect of the code really jumped out at me as a serious limitation of the current spec: a component host can only pass a single DOM content subtree to the component. As I’ll try to show, I believe that could seriously limit the degree to which a component can expose a meaningful API.

Consider the markup behind those big “choice” buttons. Each choice component includes an icon, a short text summary used as a label, and longer descriptive text that appears in a tooltip on hover. You can think of that per-choice data as, in effect, three public properties of the choice component:

<element name=”x-choice” extends=”div” constructor=”ChoiceControl”>
    <template>
        <div id=”choice”>
            <div id=”icon” class=”mask”></div>
            <content select=”h3:first-of-type”></content>
            <aside>
                <content select=”*”></content>
            </aside>
        </div>
    </template>
    …
</element>

The code above makes use of the proposed <content> element to select specific portions of the DOM tree (using CSS selectors) and incorporate them into the component’s shadow DOM. With that in place, the code for the overall poll component (i.e., the choice host) can instantiate choice buttons with the following markup:

<x-choice value=”semantics”>
    <h3>Semantics</h3>
    <p>Giving meaning to structure, semantics are front and…</p>
</x-choice>
<x-choice value=”offline-storage”>
    <h3>Offline & Storage</h3>
    <p>Web apps can start faster and work even if there is no…</p>
</x-choice>
…

So the first code fragment effectively defines a choice component with three public properties (although these aren’t actually class properties). The second code fragment shows the creation of two instances of that choice component, filling in two of the three choice properties. It’s not shown where the icon property is filled in, but it’s presumably done through styling.

All looks fine so far, but there are some serious issues lurking here.

Problems

The root issue here is that, as currently speced, Web Components can only accept a single DOM-valued content property via markup. This leads to a profusion of problems:

1. Asking developers to tease apart component content will mean work for devs, and produce inconsistent results.

   Why, exactly, is the choice component using the <h3> tag to specify the text label for the button? Because this component has two textual properties, and the current Web Components spec only lets the developer pass one DOM content subtree to a component. So the component’s author developer has to somehow let the component’s users pack more than one property into the content, and then the dev has to crack that content to extract those properties. The question of how to crack that single content subtree into multiple properties is left entirely up to the developer.

   The tool given to the developer for this purpose is CSS selectors, which at first glance seems powerful. Unfortunately, it’s also a recipe for inconsistency. Every developer will have the freedom—and chore—to approach this problem their own way, guaranteeing the emergence of a handful of different strategies, plus a number of truly bizarre solutions.

   It’s as if you were programming in a system where functions could only accept a single array. As it turns out, we already have a good, common example of a such a system: command line applications. Every command-line application has some main() function that’s handed a single array of command line options, and the application has to decide what to do with them. Although conventions eventually arose with respect to the order and meaning of arguments, there’s still a wide variety of approaches. Some apps rely on argument position, some rely on single-letter flags (“-a”), some rely on full-word named parameters (“–verbose”), some have idiosyncratic microgrammars (e.g., chmod permissions), and many applications support a rich combination of all these approaches.

   Parsing arguments is tedious, boring work. In the early days, a developer throwing an app together might do the absolute minimum work necessary. The result was often inconsistent or incomplete argument support. The dev might eventually be forced to hack on their app until they finally had a roughly functional command line parser. These days, developers can rely on language features, or libraries like Python’s argparse, to “crack” the argument array into a meaningful structure which can be more easily inspected. In particular, it’s invaluable to a developer to be able to directly inspect specific arguments by name.

   The use of CSS selectors does remove some of this tedium, but it still leaves devs without a consistent way to refer to component properties by name, thereby leaving the door wide open for inconsistency. A dev might decide to use DOM structure, HTML tags, element classes, or a combination of all of these to demarcate properties. This will make it much harder for devs to share components, to swap out one component for another, and so on. It would be better if we could learn from the command-line argument example now and head off this inconsistency.

2. HTML semantics are nearly meaningless when used to identify parameters.

   In the Google I/O demo, the developer of the choice component elected to use HTML tags within the single content subtree to identify properties. In this case, they decided that the first <h3> element in the content would identify the summary text, and everything else would be used as the longer text description.

   But why use <h3> for this purpose? The W3C spec says a heading tag like <h3> should be used to, “briefly describe the topic of the section it introduces”. These choices aren’t introducing sections, so that can’t be the the case here. Neither is this <h3> being used to reflect the rank of an element in a hierarchical document structure.

   In all likelihood, the <h3> is used here, as it often is in practice, to mean something like, “somewhat prominent, but not too prominent”. Visually this usually translates to, “bold text, a little bigger than the body text”. At least, that seems to be how <h3> is being used in this component.

   There’s nothing really wrong with that, but it’s clearly arbitrary. Other developers might easily make a different decision. Later, in the very same demo, the code for the poll component accepts the text label for a different Voting button through the use of a <label> element. So in one place in this app, a button’s label is specified with an <h3>, but elsewhere in the same app, a button’s label is specified with a <label>. I don’t think this reflects any particular negligence on the part of the demo’s developers. I think it’s a latent issue in any scheme that relies on HTML elements for something than the original purpose. Perhaps the code’ s developers did have some reason in mind for using <label> in one place and <h3> in another, but the point is that the reason is not obvious to another party looking at the code.

   The same arbitrary nature of tag choice here applies to use of the <aside> tag to identify the choice description. Try this: show the poll screen shot above to 3 web developers, and ask them which HTML tag they would use to specify the tooltip that should appear when the user mouses over a choice button. I’d be surprised if even one of them picked the <aside> tag. Is the tooltip content here really, as the W3C description says for the <aside> element, “tangentially related to the content around the aside element, and which could be considered separate from that content”? Well, not really. But, maybe; that’s a debatable point. The fact it’s debatable is what’s at issue here.

   In contrast, here’s a tautological statement which wouldn’t generate debate: the choice description in the tooltip is the choice description in the tooltip. The local semantics here aren’t in question. So it’s a shame the property can’t be described in contextual terms like “description”, or “tooltip”.

   The fact that the component is using HTML elements to identify arguments appears sensible, but in practice will be nearly meaningless. Every single time a dev needs to create a new component property, they’ll pick from the 100-odd HTML elements. Their selection may depend on their experience, their mood, the phase of the moon, and which handful of HTML elements they haven’t already used for other properties on the same component. It’s highly likely a different developer (or the same developer on a different day) would make a different selection of HTML elements for the same properties.

   Imagine an object-oriented programming language that forced you to give class properties one of 100 sanctioned property names: “index”, “count”, “name”, etc. Evereyone’s classes would look consistent, but it would be an utterly false consistency. That’s effectively what we’ll get if component authors are forced to choose HTML tags to identify component properties.

3. Use of CSS selectors hinders a developer’s ability to add new properties.

   Suppose the author of this component needs to add a new property to this choice component. Maybe they want to add a “More about this choice” link to each choice; this link should navigate to another page with more details on that poll choice. Following the example of the <h3> for the choice summary, they decide to define this link property by extracting the first <a> tag in the content to be the link to the “More about this choice” page.

   Perhaps, following their use of the “h3:first-of-type” selector above, they decide to pick out this <a> tag with the similar CSS selector “a:first-of-type”. If they do so, this component author will inadvertently screw up any component user who happened to include an <a> tag somewhere in the description. Suppose a user of this component has already created some code for a choice like this:

   <x-choice value=”semantics”>
       <h3>Semantics</h3>
       <p>
           Semantics in <a href=”…”>HTML5</a> applications…
       </p>
   </x-choice>

   The “a:first-of-type” selector for the “More about this choice” link will accidentally pick up the existing link, thereby breaking this use of the component. The component author could issue a “Breaking Change” notice, warning everyone to include an <a> tag before the choice description. But even that wouldn’t help someone who, for whatever reason, needed to embed an <a> inside of the <h3>.

   The use of selectors here could be made more robust by using the child selector “>”, as in “> h3:first-of-type”. But this gets verbose, and again, isn’t likely to be a universal convention, and inconsistent use of the child selector will only add to the confusion. The fundamental problem is that using CSS selectors for this purpose is inherently fragile.

4. Arbitrary parameter structure is brittle.

   The fragility of using CSS selectors remains even if one tries to avoid the use of arbitrary HTML elements. Suppose you decide to use element position to identify components. You’ll still up a component which is hard to update.

   Here, a relevant case study is the existing of positional function parameters in most programming languages. To take just one example, consider JavaScript functions. Suppose you’ve defined a function with three parameters: “function foo(a, b, c) {…}”. If you now want to add a new parameter “d”, you have to add it to the end of the argument list to avoid breaking existing users of your function. This can easily produce a function whose parameter order feels unnatural. And to use the new “d” parameter, a function caller must supply the intermediate arguments a, b, and c, even if those are irrelevant to the function call at hand.

   To avoid these problems, programming languages tend to eventually evolve named function parameters. Functions with named parameters are inherently more future-proof and, importantly, allow callers to only specify the parameters they care about.

   The lesson of positional function parameters applies to trying to parse component properties out of the DOM content subtree. Having learned this lesson in countless programming languages, it would be nice to just jump straight to a reasonable solution which allowed for named component properties. While CSS selectors represent a powerful parsing tool, much of that power is completely unnecessary in this context — and some people will inevitably put that extra power to poor use.

5. Subclasses will compete for parameters with their base classes.

   The above situations quickly deteriorate further when one envisions extending an existing component via subclassing. Subclassing is a crucial means of efficiency in component development, in which the behavior of one component can be specialized for new purposes. As just one case, over 33% of the controls in the QuickUI Catalog are subclasses of other Catalog controls. For example, both DateComboBox and ListComboBox extend ComboBox, which itself extends PopupSource. This separation of concerns is vital to keep the code clean, organized, and maintainable.

   Such subclasses would likely become unworkable as Web Components, because each level of the class hierarchy will be competing with its ancestors and descendants as they all tried to extract properties from the single DOM content subtree permitted by the Web Components spec. If the choice class extracts an <h3> element from the content, then that element is effectively invisible to the <content> selectors of its subclasses. (Or, if you let subclasses have first shot at the content, then the elements they pull out are effectively invisible to their base classes.)

   This significantly complicates point #3 above (using CSS selectors to pull out properties from the DOM content subtree makes it hard to add new properties). Consider a subclass of the choice component above called, say, special-choice. Perhaps the author of special-choice has decided to use the HTML <h4> element to identify a particular property. Now the author of the base choice component decides to add a new property, and elects to use <h4> for this purpose themselves. This has the effect of breaking the special-choice subclass. Obviously, such naming conflicts can arise in regular OOP classes, but here the likelihood of conflict is much greater because of the highly constrained vocabulary of HTML elements.

   Using DOM structure to select properties (point #4, above) is even more brittle when one considers subclasses. If a component class decides to use DOM element position to select content for a given property, and someone creates a subclass that likewise uses element position, the original base class’ API is effectively frozen. Suppose the base class defines a <content> element with selector “:nth-child(3)” , and the subclass goes ahead and uses a <content> with selector “:nth-child(4)”. How is the base class supposed to add support for a new property now? They can’t use position 4, because a subclass is already using that.

   The situation could be worked around by requiring not just specific tags, but also specific class names, but this has problems of its own (see below).

   As currently drafted, the Web Components spec seems highly likely to close off the possibility of rich component hierarchies. Most component developers will probably elect to just copy-and-paste useful code from other developers, rather than subclassing them, to preserve the ability to modify their components in the future.

6. Class names could help identify properties, but will probably just complicate everything.

   One way to skirt the problems above is to use HTML element classes to identify properties by class name, and reference these classes in the CSS selectors. If you gave up on specific HTML tags, and just used a <div> and a named element class for all properties, the second code fragment above could look like this:

   <x-choice value=”semantics”>
      <div class=”summary”>Semantics</div>
      <div class=”description”>Giving meaning to structure…</div>
   </x-choice>
   <x-choice value=”offline-storage”>
       <div class=”summary”>Offline & Storage</div>
       <div class=”description”>Web apps can start faster…</div>
   </x-choice>
   …

   This could potentially work if everyone agreed to always using an element class name to identify a property, and consistently applied those classes to a single element type (likely <div>) which everyone agreed upon would stand for “parameter”.

   Unfortunately, the more likely result is that throwing element class names into the mix will just complicate everything further. Some devs will write their components that way, but others will insist the use of HTML elements as shown above. Some will require the use of both specific HTML elements and specific class names. E.g., the choice component’s summary property will be forced to be identified with <h3.summary> to avoid possible conflicts with other <h3> elements in the content. This would be verbose and, worse, as a component user you’d have to remember and specify two things, when one should be sufficient.

7. Invisible component APIs foreclose the possibility of inspection and reflection.

   The choice component in this example effectively presents its hosts with an external API that allows the host to fill in two text properties. Unfortunately, that API is implicit in the design of the <content> elements and their selectors. That makes it hard to programmatically understand what a component is doing.

   At design time, there’s no easy way to statically analyze the code to inspect what those <content> elements are actually being used for. You could potentially parse the HTML to find the <content> elements, then parse their CSS selectors, but that still wouldn’t give you any hints as to what those <content> elements were being used for. At least a formal property name gives you a real idea as to its purpose.

   And at runtime, there would be no easy way to ask a choice component instance questions about which properties it supports: “How many properties do you have?”, or “Do you have a ‘description’ property?” Such run-time inspection of a component’s API (also known as reflection) can be a powerful tool.

   In this very presentation, Google’s developers point toward the benefits of programmatic inspection when they observe that giving web developers the ability to create new custom elements (via the <element> tag) will open new possibilities in researching possible improvements to HTML itself. For example, researchers could statically inspect Web Components actually used by production web sites to determine, for example, the names of the most common custom elements. That in turn could help guide the formal adoption of new HTML elements in future versions of the language itself.

   That’s just one example of what’s possible when APIs are explicit. Such explicitness should be extended beyond component names to cover component property names as well.

A proposal to fix this: Support multiple, named, DOM-valued component properties

All the issues above could be eliminated or dramatically improved if the Web Components spec were amended to let developers create components that accept multiple, named, DOM-valued properties. (Presumably, this support would actually be added to HTML Templates, used by both <element> and <decorator> elements.)

Here are some possible syntax suggestions:

• Proposal A: Use a consistent tag for component properties.

  A convention of using <div> elements to hold properties (see point #6 above) is a bit odd, because the <div> tag is used simply as a placeholder. The convention could be improved by formalizing a new element specifically for this purpose. Perhaps the existing <param> tag, currently limited to use within <object> elements, could be given new life by being repurposed for use within components. Its definition would need to be extended to support a closing </param> tag form that could encapsulate a DOM subtree:

  <x-choice value=”semantics”>
      <param name=”summary”>Semantics</param>
      <param name=”description”>Giving meaning to …</param>
  </x-choice>
  <x-choice value=”offline-storage”>
      <param name=”summary”>Offline & Storage</param>
      <param name=”description”>Web apps can start …</param>
  </x-choice>
  …

  If <param> can’t be redefined this way, then a new tag like <property> could be created.

  If HTML semantics zealots insist on mapping component content to HTML elements, it’d be possible to let define a component author identify a backing HTML semantic tag that should be used to treat the property’s content for search and other purposes. E.g., syntax within the <element> definition would indicate that the “summary” property should be backed by an <h3> element. This is exactly the way that the <element> tag’s “extends” attribute is already spec’ed to work. The author indicates that an <x-choice> element is backed by a <div>.

  In the exact same way, the author could indicate that a <param> (or <property>) of name=”summary” should be backed by an <h3>. As noted above, the particular choice of backing HTML element might be inconsistent or meaningless, but at least use of a backing element confines the problem to a much smaller audience. That is, the component users shouldn’t need to know that summary property behaves like an <h3>, just like they don’t have to know that an <x-choice> behaves like a <div>. Rather, that would be something only the component author would need to concern themselves with.

• Proposal B: Expand data- attributes to support data- elements

  HTML developers can already attach arbitrary string data to HTML elements as data- attributes (that is, element attributes prefixed with “data-”). Web Components could build on this precedent to allow data- elements that specify DOM subtrees nested within the component’s content. For example:

  <x-choice value=”semantics”>
      <data-summary>Semantics</data-summary>
      <data-description>Giving meaning to …</data-description>
  </x-choice>
  <x-choice value=”offline-storage”>
      <data-summary>Offline & Storage</data-summary>
      <data-description>Web apps can start …</data-description>
  </x-choice>
  …

  In the case where the property values are pure text, a <data-foo> element could be interchangeable with the corresponding data-foo attribute within the component tag. So one could also write:

  <x-choice value=”semantics” data-summary=”Semantics”>
      <data-description>Giving meaning to …</data-description>
  </x-choice>
  <x-choice value=”offline-storage” data-summary=”Offline & Storage”>
      <data-description>Web apps can start …</data-description>
  </x-choice>
  …

  The data- element form would only need to be used when specifying a real DOM subtree with subelements; otherwise, the data- attribute form could be used.

• Proposal C (preferred): Let developers define custom property elements

  The above approach could be tightened further by dropping HTML’s historic obsession with restricting the set of tags. By dropping by the “x-“ in the custom element tag, and the “data-“ in the custom property tag, we end up with something much cleaner:

  <choice value=”semantics”>
      <summary>Semantics</summary>
      <description>Giving meaning to structure, …</description>
  </choice>
  <choice value=”offline-storage”>
      <summary>Offline & Storage</summary>
      <description>Web apps can start faster …</description>
  </choice>
  …

  As with the data- element approach above, this custom property element approach could also support the use of a data- attribute on the element tag itself when specifying a simple string property value.

  The cleanliness of the code above comes at the cost of an ambiguity: if you can define your own element tags and property tags, how does the parser know which is which? In the code above, is <summary> a property of <choice>, or is it a custom element in its own right? One resolution would be a precedence rule, e.g., if <summary> is a child of a parent that has a summary property, then treat it as a property, otherwise instantiate it as a custom element. Another resolution would be to follow what Microsoft did with XAML’s property element syntax: allow (or require) the property to be written as <choice-summary>.

  As noted above, if HTML powers that be insist on mapping component content to a fixed set of HTML elements, that could  be handled by letting a component author indicate the HTML element which should be used to back each property. Again, that would relegate the problem to something that only the component author would have to worry about. The writer of the code above that hosts the choice component wouldn’t have to obsess over the question of why <aside> was picked instead of <label>; that detail would only be visible by reading the code for the choice component. The host author only has to deal with <summary>, which has local meaning.

  In any event, the above code sample is clean, and should serve as a goal. Such code would be a joy to write — and read. It moves HTML definitively towards the creation of domain-specific languages, which is where it should go.

  It’s somewhat absurd that we can only define markup terms according to global consensus. That’s like waiting for a programming language committee to approve the names of your classes. The web will move forward at a much faster pace if we can let individual problem domains (online stores, news sites, social networks, games, etc.) define their own tags, with semantics they care about and can agree upon. As the aforementioned uses of <aside> and <label> illustrate, forcing developers to use HTML elements may give the appearance of consistent semantics, but that consistency is merely a facade. In contrast, letting polling organizations define the meaning of a <summary> property for a <choice> component could produce meaningful consistency within that industry.

There’s still time to fix this

In their presentation, Alex and Dimitri indicated that their goal is not to spec out a complete replacement for web UI frameworks. Rather, the goal of their work is to lay a solid foundation on top of which great web UI frameworks can be built by others. In this light, it is hoped that the Web Components spec can be amended to support multiple, named, DOM-valued properties — because that’s exactly the foundation a great web UI framework is going to need.

The QuickUI framework, at least, is more expressive with regard to component content than is possible within the current Web Components spec. That is to say, the existing Catalog of QuickUI controls (and the many others controls written in the service of specific QuickUI-based applications) could not be ported to the current Web Components spec. Or, perhaps, those controls could be ported — but then, for the reasons given above, the collection would then become so brittle that its evolution would come to a halt. That would be a shame.

To be sure, the Google team, and the others working on Web Components, are smart folks, and it’s likely they’ve already given at least some thought to the problems raised in this post. But more input, particularly when informed by real application experience by potential users of a standard, is always valuable in weighing decisions about what should go into the standard. And it’s in that spirit that this post is written.

If you yourself have worked with component frameworks, and have experiences that bear on this issue, please share them with the folks at Google. A good forum for feedback might be the Web Components page on Google+. (Be sure to thank everyone for their work!)

As indicated in the earlier overview comparing QuickUI and Web Components, one significant difference between the two frameworks is that QuickUI allows code to run when a control’s content() property is set, while the Web Components spec does not currently allow for this. This post will attempt to begin making the case for the need for this feature, starting with an analysis of how that feature is used in QuickUI controls today.

The largest public body of QuickUI controls is QuickUI Catalog, which as of this writing includes 76 open source controls that handle a variety of common user interface tasks or serve as demonstrations of how to achieve common behaviors in controls. Of the 76 published controls:

• 32 controls include code that runs when their content() property is set. Since the base Control class already provides a default content() property, these controls are overriding that base implementation. (In some cases, like PopupSource, the class’ content() property override is itself overridden by a subclass like ComboBox.)
• Of the above 32 controls, 23 use their content() property override to delegate content to a sub-element. This is the standard approach in QuickUI for a control to incorporate content from its host. (For a working example, see this jsFiddle, in which a UserTile control delegates its content to a span inside the control. This topic is also covered in the second portion of the QuickUI JavaScript tutorial.) This is roughly analogous to what Web Components spec accomplishes with the proposed <content> element.
• 12 controls (of the 76 in the catalog) are text box variations that delegate their content() property to a text box: either an <input> element of type “text” or a <textarea>. For example, the content() of a ListComboBox will be placed inside an <input>. Historically, HTML input fields have insisted on handling the field’s value through a string “value” property, whereas an element’s content is a DOM subtree. Despite the difference in data type, in many cases the distinction between “value” and “content” feels somewhat arbitrary. The convenience of a content property is just as interesting to a control that wants to render that content in a text box. For example, if a combo box is going to hold a list of animal names, it’s nice to be able to set the default content of that combo box in markup as:<ListComboBox>Dog</ListComboBox>. Naturally, this translation is lossy: if one passes a DOM subtree into such a control’s content() property, it’s to be expected that it will only preserve the subtree’s text. Nevertheless, it is highly useful to be able to define controls that render their primary content in text boxes.
• 20 of the controls override their content() property to perform work whenever the content changes. The following table summarizes these 20 cases:

To summarize, these controls are doing the following types of work when their content changes:

• Adjust its dimensions or the dimensions of some subelements (e.g., AutoSizeTextBox, Menu).
• Layout contents to achieve results not directly supported in HTML and CSS (e.g., PackedColumns, PanelWithOverflow).
• Transform or manipulate the content before rendering it (e.g., Repeater, ColorSwatch).
• Update its own subelements based on the content (e.g., TabSet, SlidingPagesWithDots).
• Validating content (e.g., ValidatingTextBox, and its subclasses like DateTextBox).

Such controls represent a significant percentage of the QuickUI Catalog — approximately 25% — and it’s very likely that similar results would be found in other QuickUI-based projects. And in addition to the scenarios listed above, other scenarios likely exist in which a control wants to perform work when its content changes.

Overall, this pass through the QuickUI Catalog suggests that many interesting user interface components have a need to perform work when their content is set — to do something more than passively hold the content they’re passed. At this point, it’s not exactly whether the aforementioned QuickUI controls could be successfully ported to Web Components as the spec currently stands, which would be unfortunate. (As stated in the previous post, a long-term vision for the QuickUI framework is that controls created in QuickUI can be transitioned to a Web Components foundation in the future.)

It’s possible that a component could use forthcoming support for DOM mutation observers could be used to track changes to its own content, but whether this would work, or work well, is not yet known. A control could also force its host to invoke some method on the control whenever the host changes the control’s content, but that would be unfortunate; it would place extra work on the developer, and a host’s failure to properly notify the control that its contents have changed could lead to subtle bugs.

This post is the first in a series looking at the relationship between QuickUI and Web Components. This post will kick things off by laying out some basic points of a vision for how these two technologies might co-evolve.

The Web Components effort spearheaded by Google is a vital effort towards promoting component-based user interface design for web-based apps. Componentized user interfaces may radically transform the web industry. It will take some time for the spec to be finished and agreed upon, and then still more time for the technology to make its way into users’ hands. It is hoped that QuickUI can serve as a bridge to the world of Web Components, act as a reference point for work on the emerging spec, and provide services and component libraries that speed the creation of Web Component-based apps.

QuickUI and Web Components have the same goal

Both frameworks address the same fundamental objective: let web designers and developers create better applications faster through the creation and use of modular, reusable, and extensible user interface elements. QuickUI calls such elements “controls” and the Web Components spec calls them “components”, but in this context the terms are essentially interchangeable.

There are obviously differences in approach. QuickUI is built on JavaScript and jQuery, while Web Components is native code and browser- and library-agnostic. The Web Components framework, by virtue of being part of the browser, can do many things which a JavaScript library like QuickUI cannot. There are some obvious performance benefits to doing things in native code. It’s also possible for the browser to enforce a high degree of component isolation by preventing a Web Component’s host from knowing what’s going on inside the component. Such isolation is crucial for a component platform, because it leads to a proper separation of concerns. A component author can make many modifications to the inner workings of a component without fear that hosts of that component are inappropriately depending on a particular implementation. QuickUI can only maintain such separation of concerns by convention and by proffering services that make it easier for developers to use controls in a modular way than not.

Despite their differences, fundamentally these two web user interface frameworks are more compatible than not. This opens up the possibilities which follow.

QuickUI and Web Components should be interoperable

Based on the current Web Components spec, in theory it should be straightforward for a QuickUI control to host a Web Component, and vice versa. That can provide a degree of future-proof resiliency to a team that wants to build with QuickUI today. But it should be possible to do better than that…

QuickUI itself will someday be built on top of the Web Components foundation

Given the performance and modularity benefits of Web Components, and the reasonably close alignment of goals, it appears that it should be possible to eventually have QuickUI controls be Web Components.

Currently, the lowest levels of the quickui.js runtime provides services such as creating control subclasses and instantiating controls. These low-level services would be provided by a Web Components-enabled browser instead. The QuickUI runtime could potentially detect whether the user’s browser supports Web Components and, if so, create controls as Web Components wrapped by jQuery. On legacy browsers (all today’s released browser versions, going back to IE 8), the QuickUI runtime would continue to create controls as regular DOM elements wrapped by jQuery.

QuickUI can provide useful features beyond those which have been standardized

Standards, by their nature, advance slowly. Even once QuickUI is built on top of Web Components, QuickUI can continue to evolve at a faster pace to meet the needs of web designers and developers. QuickUI can be the “running code” in the maxim that Internet standards evolve from Rough consensus, running code.

QuickUI is also designed explicitly for jQuery developers, whereas the Web Components spec must be library-agnostic. In the same way that jQuery developers currently find it much easier to write an interactive UI in jQuery than by doing direct DOM manipulation, they will also find creating controls (components) easier in QuickUI than using only the low-level services offered by the browser. For example, a QuickUI control is already a jQuery instance, so a developer can immediately and directly manipulate a control using all the facilities in jQuery. As another example, QuickUI’s services for creating properties generate jQuery-style getter/setter functions which are automatically chainable, and can be applied to a collection of elements in a single call.

QuickUI may serve as a reference for work on Web Components

As a 4+ year-old web user interface framework, there’s already a considerable degree of hard-earned knowledge baked into the QuickUI framework. These lessons can be considered as the various parties working on Web Components flesh out the details of that spec. It’s in this role of QuickUI as a reference point that some of the important lessons from QuickUI will be covered in future posts on this blog.

QuickUI lets teams create componentized web user interfaces today

Many of the benefits of building a user interface with components can be achieved by a team using QuickUI today. As summarized on the QuickUI home page, those benefits include the abilities to:

• Better organize and maintain UI code.
• Use custom controls to provide optimized user interactions or a particular visual aesthetic.
• To begin developing, in the course of one project, a library of reusable UI that can accelerate a team’s future projects.
• Share common UI solutions across teams and organizations so those solutions don’t need to be created from scratch each time.

Investment in QuickUI apps today can be preserved when Web Components arrive

This is a vision, not a legal commitment. The Web Components spec is still in flux and evolving entirely outside the control of anyone working on QuickUI, so it’s impossible to promise how things will work in the future. Still, it’s plausible that a team could begin creating a web user interface in QuickUI today, and as Web Component-enabled browsers arrive and gain use, the team could automatically (or, at least, easily) transition to that better foundation to improve the performance and reliability of their apps.

The QuickUI Catalog will evolve into the web’s best open library of reusable user interface components

To an extent, the QuickUI Catalog of common, ready-to-use controls is somewhat independent of the underlying QuickUI foundation. At the most abstract level, these are user interface patterns that can be found in many applications on many platforms. Even if obstacles prevent QuickUI controls from being built as Web Components, the existing JavaScript code base for the Catalog would give one a huge headstart in creating an equivalent library of Web Components. And if the vision outlined here comes to pass, the Catalog’s collection of components — and user interfaces built with them — should be able to transition smoothly to a Web Components foundation.

Next steps: investigation of framework differences

While the above points lay out a vision for the coevolution of QuickUI and Web Components, many details remain which must be investigated before such a vision can come to pass. While the goals of the two frameworks are generally aligned, the design principles underlying the two have significant differences. For example, QuickUI’s core design principles seem to place greater emphasis on extensibility — creating a new control class by extending an existing class — than does the current Web Components spec. Such differences could lead to irreconcilable incompatibilities, which would represent lost opportunity.

The hope is that any issues can be teased out of the Web Components spec early enough and either worked around or submitted for consideration so that they may hopefully be addressed. Some key issues warranting further investigation are:

1. A significant fraction of QuickUI controls override their base class’ content() property setter function in order to perform work when a host sets a control’s content. This is done for a variety of reasons: to partially fill in a component’s DOM tree (a sort of user interface currying); to transform content before displaying it; to recalculate layout; or to perform other operations dependent upon the content. This is not currently supported in the Web Components spec. An analysis of the QuickUI Catalog controls on this topic is underway to produce a set of common use cases.
2. A QuickUI subclass maintains an is-a relationship with its base class. The <shadow> element in the Web Components spec may lead to subclasses that effectively maintain more of a has-a relationship with their parent class. It’s not immediately clear, for example, how one could define a base class and a subclass that meet all these conditions: a) both use the same root element (e.g., <button>), b) both are independently instantiable, c) the subclass can host base class elements (e.g., via <shadow>), and d) the subclass is a JavaScript instanceof (is-a) of the base class. These conditions often arise when extending an existing control class, and QuickUI control classes can meet all of them.
3. The Web Components proposal minimizes the impact on the HTML language itself, but one repercussion of this appears to be that component classes can’t define custom properties that can be set through markup. As currently understood, the spec calls for hosts to pass values to components exclusively through a single content tree. The component class must then prise apart this content through a “select=” attribute so that it can incorporate content subelements into different parts of the component.This is roughly analogous to the way command-line apps must parse their text arguments, with both the flexibility and the potential for great inconsistency that go with that. In this context, such flexibility may create significant complications for the creation and maintenance of subclasses, as varying levels of the class hierarchy impose different demands on the content. Overall, this doesn’t feel as specific or clean as the compound property syntax in a language like XAML (or QuickUI Markup), in which a control class can define custom properties that may be set as string attributes, through nested subelements, or through property setter functions.

As these issues are investigated more deeply, the results of those investigations will be posted here.