Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces support for creating custom DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, and encapsulated Like/+1 buttons. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Related links:
* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | use cases]]. This section explains component model basics by studying each property.

==Extensibility==

The component model enables creation of new types of DOM elements by allowing the use of existing DOM elements in Javascript prototype chain. For example, here's how you would create a new sub-type of HTMLElement:
<code>
<pre>
function LayoutManagerPanel() {
HTMLElement.call(this);
}

LayoutManagerPanel.prototype = Object.create(HTMLElement.prototype);

// ...

// 1) Will not be able to add instances of LayoutManagerPanel to document without this call.
// 2) First parameter specifies the tagName of the element being registered and must be a string prefixed with "x-".
Element.register("x-layout-manager-panel", LayoutManagerPanel);

// ...

var panel = new LayoutManagerPanel();
document.body.appendChild(panel);
// or
document.body.innerHTML = "<x-layout-manager-panel></x-layout-manager-panel>";
</pre>
</code>

The resulting <code>panel</code> instance is a Javascript object that is a valid DOM element, which can be added to the DOM tree. You can then extend this object using standard Javascript prototype inheritance.

Required Building Blocks:
* [[#Constructable_DOM_Types | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://www.w3.org/TR/domcore/ DOM Core]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard Javascript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
The common API surface and the ability to extend it serves as a natural API boundary for framework authors, enabling interoperability.

Required Building Blocks:
* [[#Constructable_DOM_Types | Constructable DOM Types]]

==Encapsulation==
Encapsulation refers to ability of the component to hide its implementation details and state from the document. To enable hiding of the implementation details, the component model provides a way to build a DOM tree that is not accessible from the document DOM tree, but is rendered as part of the document. This DOM tree, associated with the component is the [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that no information about the shadow DOM tree crosses this boundary. Additionally, the boundary serves as a convenient style application lever, giving the component a choice of letting (or not letting) document CSS affect the shadow DOM tree.

Every DOM element instance may only have (or ''host'') one shadow DOM tree. A shadow tree is instantiated by creating an instance of the <code>ShadowRoot</code> object, which takes a reference to the hosting element as a parameter. Attempting to create more than one instance for the same element throws an exception:

<code>
<pre>
function LayoutManagerPanel() {
HTMLElement.call(this);
var shadow = new ShadowRoot(this);
var shadow2 = new ShadowRoot(this); // throws an exception.
// ...
}
</pre>
</code>

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

Being DOM objects, components fit naturally into the document DOM tree and support all of its composition properties. In addition, the <code>content</code> element allows controlling interaction between shadow and document DOM trees. A <code>content</code> element specifies places where immediate document tree children of the component are rendered ''inside'' the shadow tree.

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<x-dock-layout-panel>
<h1 class="north">On Gardens</h1>
<ul class="west">
<li>Automatic Gardens</li>
<li>Gardening on minefields</li>
</ul>
<p>I love gardening.</p>
<div class="south">Written by Chauncey Gardiner.</div>
</x-dock-layout-panel>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#shadow-root>
<div class="north">
<content includes=".north">
</div>
<div>
<div class="west">
<content includes=".west">
</div>
<div class="east">
<content>
</div>
</div>
<div class="south">
<content includes=".south">
</div>
<#shadow-root>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<x-dock-layout-panel>
<div class="north">
<h1 class="north">On Gardens</h1>
</div>
<div>
<div class="west">
<ul class="west">
<li>Automatic Gardens</li>
<li>Gardening on minefields</li>
</ul>
</div>
<div class="east">
<p>I love gardening.</p>
</div>
</div>
<div class="south">
<div class="south">Written by Avid Gardener.</div>
</div>
</x-dock-layout-panel>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | Content Element]]

==Desugaring==
The component model also explains pretty well how the native HTML elements are built and dispels some of the magic associated with the "DOM object vs. Javascript object" juxtaposition.

Allowing DOM elements to participate in the Javascript inheritance chain makes DOM elements more approachable and easier to work with.

Complex DOM elements that are rendered with more than one CSS box (and aren't specified in terms of CSS, like [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | Content Element]]

==Performance==
Considering the way Web works, the component model must allow decoupling of the instantiation and the declaration of the components in order to provide reasonable performance characteristics. It's an unfortunate, but necessary requirement. In other words, we must be able to handle situations where a component instance is created before it is declared. Here's an simple example:

<code>
<pre>
// somewhere in view.js
...
document.body.innerHTML = '<div class="awesome"><x-layout><x-spring-panel>...</x-spring-panel></x-layout>';

...
// somewhere in layout.js
Element.register('x-layout', Layout);
Element.register('x-spring-panel', SpringPanel);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. Given that asynchronous, deferred or lazy-loading of script are all common performance techniques in today's Web, we must do better than block or throw an exception in such cases.

The component model offers this solution:

When an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced (think [http://www.w3.org/TR/domcore/#dom-node-replacechild replaceChild] with the extra work of transferring children, attributes, and children) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://www.w3.org/TR/domcore/#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://www.w3.org/TR/domcore/#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of Javascript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
[Supplemental]
interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

The API surface of the component model lends itself well to proper confinement. Here's an approach that could be used to provide it (very early brainstorming):

* Confinement is not tied to the component model. Instead, it's a new twist on the method of loading scripts. A script could be loaded as usual or it could be ''confined'', or loaded into its own context.

* When confined, a script has its own global and document objects. These objects only reveal some safe limited subset of the actual document objects. Think of it as a same-origin iframe with restrictions on document and window.

* You can communicate with the main document using <code>window.postMessage</code>.

* The confined document DOM tree is always empty. Attempting to insert into it throws exceptions.

* ... except when you append to elements in shadow DOM. That's right, you can do <code>Element.register</code> and <code>new ShadowRoot</code> in the confined document.

* Whenever you register an element, it registers ''in the main document'' as well. Creating an instance of a component from an confined document produces a functional DOM element shell that proxies to the actual element in the confined document.

Proposed API: introduce a new <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Use Case Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, lifecycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

Component Model

2011-08-23T17:37:05Z

Dglazkov: /* Comparison With Existing Specs and Implementations */

Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces support for creating custom DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, and encapsulated Like/+1 buttons. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Related links:
* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | use cases]]. This section explains component model basics by studying each property.

==Extensibility==

The component model enables creation of new types of DOM elements by allowing the use of existing DOM elements in Javascript prototype chain. For example, here's how you would create a new sub-type of HTMLElement:
<code>
<pre>
function LayoutManagerPanel() {
HTMLElement.call(this);
}

LayoutManagerPanel.prototype = Object.create(HTMLElement.prototype);

// ...

// 1) Will not be able to add instances of LayoutManagerPanel to document without this call.
// 2) First parameter specifies the tagName of the element being registered and must be a string prefixed with "x-".
Element.register("x-layout-manager-panel", LayoutManagerPanel);

// ...

var panel = new LayoutManagerPanel();
document.body.appendChild(panel);
// or
document.body.innerHTML = "<x-layout-manager-panel></x-layout-manager-panel>";
</pre>
</code>

The resulting <code>panel</code> instance is a Javascript object that is a valid DOM element, which can be added to the DOM tree. You can then extend this object using standard Javascript prototype inheritance.

Required Building Blocks:
* [[#Constructable_DOM_Types | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://www.w3.org/TR/domcore/ DOM Core]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard Javascript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
The common API surface and the ability to extend it serves as a natural API boundary for framework authors, enabling interoperability.

Required Building Blocks:
* [[#Constructable_DOM_Types | Constructable DOM Types]]

==Encapsulation==
Encapsulation refers to ability of the component to hide its implementation details and state from the document. To enable hiding of the implementation details, the component model provides a way to build a DOM tree that is not accessible from the document DOM tree, but is rendered as part of the document. This DOM tree, associated with the component is the [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that no information about the shadow DOM tree crosses this boundary. Additionally, the boundary serves as a convenient style application lever, giving the component a choice of letting (or not letting) document CSS affect the shadow DOM tree.

Every DOM element instance may only have (or ''host'') one shadow DOM tree. A shadow tree is instantiated by creating an instance of the <code>ShadowRoot</code> object, which takes a reference to the hosting element as a parameter. Attempting to create more than one instance for the same element throws an exception:

<code>
<pre>
function LayoutManagerPanel() {
HTMLElement.call(this);
var shadow = new ShadowRoot(this);
var shadow2 = new ShadowRoot(this); // throws an exception.
// ...
}
</pre>
</code>

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

Being DOM objects, components fit naturally into the document DOM tree and support all of its composition properties. In addition, the <code>content</code> element allows controlling interaction between shadow and document DOM trees. A <code>content</code> element specifies places where immediate document tree children of the component are rendered ''inside'' the shadow tree.

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<x-dock-layout-panel>
<h1 class="north">On Gardens</h1>
<ul class="west">
<li>Automatic Gardens</li>
<li>Gardening on minefields</li>
</ul>
<p>I love gardening.</p>
<div class="south">Written by Chauncey Gardiner.</div>
</x-dock-layout-panel>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#shadow-root>
<div class="north">
<content includes=".north">
</div>
<div>
<div class="west">
<content includes=".west">
</div>
<div class="east">
<content>
</div>
</div>
<div class="south">
<content includes=".south">
</div>
<#shadow-root>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<x-dock-layout-panel>
<div class="north">
<h1 class="north">On Gardens</h1>
</div>
<div>
<div class="west">
<ul class="west">
<li>Automatic Gardens</li>
<li>Gardening on minefields</li>
</ul>
</div>
<div class="east">
<p>I love gardening.</p>
</div>
</div>
<div class="south">
<div class="south">Written by Avid Gardener.</div>
</div>
</x-dock-layout-panel>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | Content Element]]

==Desugaring==
The component model also explains pretty well how the native HTML elements are built and dispels some of the magic associated with the "DOM object vs. Javascript object" juxtaposition.

Allowing DOM elements to participate in the Javascript inheritance chain makes DOM elements more approachable and easier to work with.

Complex DOM elements that are rendered with more than one CSS box (and aren't specified in terms of CSS, like [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | Content Element]]

==Performance==
Considering the way Web works, the component model must allow decoupling of the instantiation and the declaration of the components in order to provide reasonable performance characteristics. It's an unfortunate, but necessary requirement. In other words, we must be able to handle situations where a component instance is created before it is declared. Here's an simple example:

<code>
<pre>
// somewhere in view.js
...
document.body.innerHTML = '<div class="awesome"><x-layout><x-spring-panel>...</x-spring-panel></x-layout>';

...
// somewhere in layout.js
Element.register('x-layout', Layout);
Element.register('x-spring-panel', SpringPanel);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. Given that asynchronous, deferred or lazy-loading of script are all common performance techniques in today's Web, we must do better than block or throw an exception in such cases.

The component model offers this solution:

When an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced (think [http://www.w3.org/TR/domcore/#dom-node-replacechild replaceChild] with the extra work of transferring children, attributes, and children) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://www.w3.org/TR/domcore/#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://www.w3.org/TR/domcore/#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of Javascript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
[Supplemental]
interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

The API surface of the component model lends itself well to proper confinement. Here's an approach that could be used to provide it (very early brainstorming):

* Confinement is not tied to the component model. Instead, it's a new twist on the method of loading scripts. A script could be loaded as usual or it could be ''confined'', or loaded into its own context.

* When confined, a script has its own global and document objects. These objects only reveal some safe limited subset of the actual document objects. Think of it as a same-origin iframe with restrictions on document and window.

* You can communicate with the main document using <code>window.postMessage</code>.

* The confined document DOM tree is always empty. Attempting to insert into it throws exceptions.

* ... except when you append to elements in shadow DOM. That's right, you can do <code>Element.register</code> and <code>new ShadowRoot</code> in the confined document.

* Whenever you register an element, it registers ''in the main document'' as well. Creating an instance of a component from an confined document produces a functional DOM element shell that proxies to the actual element in the confined document.

Proposed API: introduce a new <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, lifecycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

2011-08-23T16:19:44Z

Dglazkov: Created page with 'Here are the guidelines for understanding the problem of and developing specification for the Component Model =Approach== # Capture requirements as [[Compo...'

Here are the guidelines for understanding the problem of and developing specification for the [[Component_Model | Component Model]]

=Approach==
# Capture requirements as [[Component_Model_Use_Cases | use cases]];
# Study use cases and extract a set of [[Component_Model#Properties | desired properties]] for these use cases;
# Come with a design that satisfies all desired properties;
# Extrude [[Component_Model#Building_Blocks | building blocks]] out of the design;
# Iterate until [[#Success_Criteria | success criteria]] is reached.

=Success criteria==
* The use cases:
** reasonably cover a set of component model needs on the Web.
* The properties:
** completely describe the set of use cases;
** are orthogonal to each other.
* The building blocks:
** satisfy all desired properties;
** follow the component model [[#Design_Priniciples | design principles]].

=Design Principles==
* '''Reuse existing mechanisms''' as much as possible, gently extending them if necessary;
* Study popular patterns in existing Web frameworks and '''pave the cowpaths''' when appropriate;
* Encourage '''each building block to stand on its own''' merits.