WHATWG Wiki - User contributions [en]

Component Model Strawman: Element Registration

2011-10-29T01:37:21Z

Morrita:

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
document.tags.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are executed over a global object.
Before the evaluation, <tt>HTMLRegistrar.registering</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = document.tags.registering.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
The <tt>creator</tt> callback is invoked as a constructor.

The creator callback is expected to have <tt>HTMLElement.prototype</tt> in its prototype chain.
If it doesn't, agents set <tt>creator.prototype</tt> to <tt>HTMLElement.prototype</tt>.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { document.tags.bless(this); };
document.head.appendChild(element);
// Shorter form.
document.tags.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
document.tags.registering.creator = function() {
document.tags.bless(this);
};
</script>
</element>
</head>

</pre>

Using class syntax, we could also write like this:

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
constructor() { HTMLElement.call(this); }
};

document.tags.registering.creator = Comment;
</script>
</element>

// Imperative
class Comment : HTMLElement {
constructor() { HTMLElement.call(this); }
};

document.tags.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
document.tags.registering.creator = function() { document.tags.bless(this); };
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object, which is set as a <tt>creator</tt> callback.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
document.tags.registering.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup() {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
document.tags.registering.setup = function(shadow) {
// Can setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=ConstructorOnly]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
void bless(any self);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

=== The getter ===

The getter returns HTMLRegistrationElement whose <tt>name</tt> attribute
matches <tt>name</tt> parameter. unless returns null.

The getter can be used like this:

<pre>

var newCommentElement = document.elements["x-comment"].create();

</pre>

=== The <tt>register</tt> method ===

The <tt>HTMLRegistrar#register</tt> method is a shortcut for
following:

<pre>

var element = document.createElement("element");
element.name = name;
element.creator = creator;
document.head.appendChild(element);

</pre>

=== The <tt>bless</tt> method ===

=== The <tt>registering</tt> attribute ===

For each <tt>script</tt> block which is a child of <tt>element</tt> is executed,
The <tt>HTMLRegistar#registering</tt> is set to the <tt>element</tt> element.

Component Model

2011-10-28T19:48:00Z

Morrita:

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 comprehensive support for creating DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, isolated widgets, such as Like/+1 buttons, and built-in HTML elements themselves. 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.

Strawman pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Decorators Decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Element_Registration Element Registration]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Styling Styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Isolation Isolation]

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]]
* [[Component_Model_Declarative_Syntax | Component Model Declarative Syntax]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]
* [[Component_Model_Progressive_Enhancement | Component Model Progressive Enhancement]]
* [[Custom_Tags_Analysis | Custom Tags Analysis]]

Discussion pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Discussion Main discussion page with open questions]
* [http://wiki.whatwg.org/wiki/Component_Model_Discussion:_Rendering Rendering-specific discussion]
* [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page about CSS and styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Isolation_Brainstorming brainstorming page about isolation and confinement]
* [http://wiki.whatwg.org/wiki/Component_Model_Decorator_Brainstorming brainstorming page about decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_IDL_Brainstorming brainstorming page about IDLs and communication across boundaries]

=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://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html DOM4]. 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 shadow DOM tree nodes cross this boundary during event dispatch;
* document DOM tree has no access to nodes in the shadow DOM tree.

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 ([http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-renameNode Document.renameNode]) 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://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#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://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#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>
partial 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, life cycle, 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 Strawman: Isolation

2011-10-28T19:33:20Z

Morrita:

= Overview =

= Loading an External HTML Resource =

The element registration and template definition also can be done in an external, separate HTML resource.
Author can define a set of elements inside the external HTML and use it in different HTML pages.

Effective markup vocabulary for the external HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element name="x-comment">..</element>
</head>
</html>

</pre>

== The host document ==

The document which hosts an external HTML file is called a "host document".
Any HTML document can host be a host document.

If author add a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt> to a apge,
the page hosts the linked HTML resource.

In this example, the document hosts <tt>comment.html</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

= Shared Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a shared resource.
That means, agents insert <tt>head</tt> children of the hosted document
into the host document's <tt>head</tt>.
Each script execution inside hosted HTML shares the global object with its host document.

In this example, the host document eventually has an <tt>element</tt> element named <tt>x-comment</tt>.

<pre>


<html>
<head>
<element name="x-comment">..</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
<script>
var shouldNotNull = document.querySelector("element[name=x-comment]");
</script>
</head>
</html>

</pre>

= Confined Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a confined resource.

A confined resource has its document object. Any scripts inside the confined resource
are run on its own global object.

Conceptually, a confined resource is similar to a document in a cross-domain frame.
For example, the script on the confined resource can make a XMLHttpRequest to its own domain, instead of the host domain.

<pre>


<html>
<head>
<element name="x-comment">
<script>
console.log(document.location.toString()); // prints the url of comment.html
<script>
</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

== Registered Elements in a Confined Resource ==

The host document recognize an element name which is registered in the hosting confined documents, not only

Component Model Strawman: Isolation

2011-10-28T18:21:52Z

Morrita:

= Overview =

= Loading an External HTML Resource =

The element registration and template definition also can be done in an external, separate HTML resource.
Author can define a set of elements inside the external HTML and use it in different HTML pages.

Effective markup vocabulary for the external HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element name="x-comment">..</element>
</head>
</html>

</pre>

== The host document ==

The document which hosts an external HTML file is called a "host document".
Any HTML document can host be a host document.

If author add a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt> to a apge,
the page hosts the linked HTML resource.

In this example, the document hosts <tt>comment.html</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

= Shared Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a shared resource.
That means, agents insert <tt>head</tt> children of the hosted document
into the host document's <tt>head</tt>.
Each script execution inside hosted HTML shares the global object with its host document.

In this example, the host document eventually has an <tt>element</tt> element named <tt>x-comment</tt>.

<pre>


<html>
<head>
<element name="x-comment">..</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
<script>
var shouldNotNull = document.querySelector("element[name=x-comment]");
</script>
</head>
</html>

</pre>

= Confined Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a confined resource.

A confined resource has its document object. ANy scripts inside the confined resource
are run on its own global object.

<pre>


<html>
<head>
<element name="x-comment">
<script>
console.log(document.location.toString()); // prints the url of comment.html
<script>
</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

Component Model Strawman: Isolation

2011-10-28T17:48:29Z

Morrita:

Component Model Strawman: Isolation

2011-10-28T17:31:54Z

Morrita: /* Loading an External HTML Resource */

= Overview =

= Loading an External HTML Resource =

The element registration and template definition are also done in a separate HTML.
Effective markup vocabulary for the defining HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

Component Model Strawman: Isolation

2011-10-28T17:31:22Z

Morrita: /* Loading a HTML Resource */

= Overview =

= Loading an External HTML Resource =

The element registration and template definition are also done in a separate HTML.
Effective markup vocabulary for the defining HTML is limited.
Agents only recognize the first head element and its descendant.

<pre>

<html>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

Component Model Strawman: Isolation

2011-10-27T22:49:34Z

Morrita: /* Loading a HTML Resource */

= Overview =

= Loading a HTML Resource =

The element registration and template definition are also done in a separate HTML.
Effective markup vocabulary for the defining HTML is limited.
Agents only recognize the first head element and its descendant.

<pre>

<html>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

Component Model Strawman: Declarative Syntax

2011-10-27T21:12:42Z

Morrita: /* Shadow DOM Template */

= Element Registration =

Moved to [[Component_Model_Strawman:_Element_Registration]]

= Isolation =

Moved to [[Component_Model_Strawman:_Isolation]]

Component Model Strawman: Declarative Syntax

2011-10-27T21:12:25Z

Morrita: /* Isolation */

Component Model Strawman: Isolation

2011-10-27T20:46:50Z

Morrita: /* Loading a HTML Resource */

Component Model Strawman: Isolation

2011-10-27T20:44:04Z

Morrita: /* Loading a HTML Resource as a Component Definition */

= Overview =

= Loading a HTML Resource =

The element registration and template definition are also done in a separate HTML.
Effective markup vocabulary for the defining HTML is limited.
Agents only recognize a head element as a child of the root element when the HTML document is loaded as required.

<pre>

<html>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

Component Model Strawman: Isolation

2011-10-27T20:43:34Z

Morrita:

= Overview =

= Loading a HTML Resource as a Component Definition =

The element registration and template definition are also done in a separate HTML.
Effective markup vocabulary for the defining HTML is limited.
Agents only recognize a head element as a child of the root element when the HTML document is loaded as required.

<pre>

<html>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

Component Model Strawman: Declarative Syntax

2011-10-27T20:43:29Z

Morrita: /* Standalone Form */

= Element Registration =

Moved to [[Component_Model_Strawman:_Element_Registration]]

= Shadow DOM Template =

An initial shape of new shadow tree can be defined using a <tt>template</tt> element.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
</template>
</head>

</pre>

A <tt>template</tt> is instantiated through

* <tt>ShadowRoot</tt> constructor and
* <tt>shadow-template</tt> CSS property.

== The ShadowRoot constructor ==

The <tt>ShadowRoot</tt> constructor accepts a <tt>template</tt> element to instantiate.

<pre>
..
this.shadow = new ShadowRoot(this, document.getElementById(“comment-template”));
..
</pre>

== The shadow-template CSS property (brainstorming) ==

The template for shadow root also can be applied using CSS property.

<pre>

.comment {
shadow-template: url('#comment-template');
}

</pre>

Note that imperatively-applied shadows always supersede shadows from the styling.
Also, there is no way to access style-originated shadows from the scripting environment.

== The Instantiation Event and Scripting ==

Even though the <tt>template</tt> can be used to define an extra visual representation for an element,
It would be useful if author can attach a script for the template-generated shadow tree.

The <tt>template</tt> element generates an <tt>instantiation</tt> event for
each template instantiation. Authors can listen it to setup event handlers for
generated elements by the template. The event doesn't bubble, and it isn't cancelable.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
</template>
<script>
var e = document.getElementById("comment-template");
e.addEventListener("instantiation", function(evt) {
evt.root.querySelector("div").addEventListener("click", function(evt) { ... });
});
</script>
</head>

</pre>

A <tt>template</tt> element also allows a <tt>script</tt> element as a child,
whose script block can access <tt>HTMLTemplateElement.current</tt> to refer the enclosing <tt>template</tt> element.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
<script>
HTMLTemplateElement.current.addEventListener("instantiation", function(evt) {
evt.root.querySelector("div").addEventListener("click", function(evt) { ... });
});
</script>
</template>
</head>

</pre>

= Isolation =

== Standalone Form ==

Moved to [[Component_Model_Strawman:_Isolation]]

== Shared definition ==

In the default, these definitions are coming into the host document.
That means a providing HTML doesn’t have its own document nor the global object. Agents use these of the host document.

== Isolated definition ==

If the <tt>rel</tt> attribute contains the term <tt>isolate</tt>, the linked HTML is loaded as a separate document object.
The script inside the document is given a separate global object.

For the host document, there is no way to access the loaded document directly.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

[[User:Rolandsteiner|RolandSteiner]] Should we make <tt>isolate</tt> an attribute on <tt>link</tt> rather than a <tt>rel</tt> value? As Dimitri mentioned, this could be useful in general and would allow us to branch it off into a separate spec.

[[User:Morrita|Morrita]] Any declarative syntax is a part of other spec. This is cross-cutting view of multiple proposals. moved out confined declaration to standalone attribute. I have no idea how this works for other types of linked resources though.

Component Model Strawman: Element Registration

2011-10-27T19:34:57Z

Morrita: /* The script element */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are executed over a global object.
Before the evaluation, <tt>HTMLRegistrar.registering</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = document.elements.registering.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
document.elements.registering.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

document.elements.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
document.elements.registering.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
document.elements.registering.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
document.elements.registering.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

=== The getter ===

The getter returns HTMLRegistrationElement whose <tt>name</tt> attribute
matches <tt>name</tt> parameter. unless returns null.

The getter can be used like this:

<pre>

var newCommentElement = document.elements["x-comment"].create();

</pre>

=== The <tt>register</tt> method ===

The <tt>HTMLRegistrar#register</tt> method is a shortcut for
following:

<pre>

var element = document.createElement("element");
element.name = name;
element.creator = creator;
document.head.appendChild(element);

</pre>

=== The <tt>registering</tt> attribute ===

For each <tt>script</tt> block which is a child of <tt>element</tt> is executed,
The <tt>HTMLRegistar#registering</tt> is set to the <tt>element</tt> element.

Component Model Strawman: Element Registration

2011-10-27T19:29:33Z

Morrita: /* HTMLRegistrar and document.elements */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrar.registering</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = document.elements.registering.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
document.elements.registering.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

document.elements.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
document.elements.registering.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
document.elements.registering.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
document.elements.registering.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

=== The getter ===

The getter returns HTMLRegistrationElement whose <tt>name</tt> attribute
matches <tt>name</tt> parameter. unless returns null.

The getter can be used like this:

<pre>

var newCommentElement = document.elements["x-comment"].create();

</pre>

=== The <tt>register</tt> method ===

The <tt>HTMLRegistrar#register</tt> method is a shortcut for
following:

<pre>

var element = document.createElement("element");
element.name = name;
element.creator = creator;
document.head.appendChild(element);

</pre>

=== The <tt>registering</tt> attribute ===

For each <tt>script</tt> block which is a child of <tt>element</tt> is executed,
The <tt>HTMLRegistar#registering</tt> is set to the <tt>element</tt> element.

Component Model Strawman: Element Registration

2011-10-27T19:21:38Z

Morrita: /* The creator callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrar.registering</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = document.elements.registering.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
document.elements.registering.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

document.elements.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
document.elements.registering.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
document.elements.registering.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
document.elements.registering.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

Component Model Strawman: Element Registration

2011-10-27T19:21:10Z

Morrita: /* The script element */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrar.registering</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = document.elements.registering.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

document.elements.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
document.elements.registering.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
document.elements.registering.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
document.elements.registering.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

Component Model Strawman: Element Registration

2011-10-27T19:19:44Z

Morrita: /* The element element and HTMLRegistrationElement */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
document.elements.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

document.elements.registering.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

document.elements.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
document.elements.registering.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
document.elements.registering.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
document.elements.registering.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

Component Model Strawman: Element Registration

2011-10-27T19:17:01Z

Morrita: /* HTMLRegistrar and document.elements */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLRegistrationCreatorCallback creator);
readonly attribute HTMLRegistrationElement registering;
};

</pre>

Component Model Strawman: Element Registration

2011-10-27T19:15:43Z

Morrita: /* HTMLRegistrar and document.elements */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.
It provides a keyed-collection like access to each registered element.
It also provides some utility method which helps idiomatic element registration and its use.

The object exists per document, and is accessible through the <tt>Document#elements</tt> property.

<pre>

[NoInterfaceObject]
interface HTMLRegistrar {
getter HTMLRegistrationElement (DOMString name);
void register(DOMString name, [Optional] HTMLElementRegisrationCreateCallback callback);
};

</pre>

Component Model Strawman: Element Registration

2011-10-27T19:10:38Z

Morrita: /* HTMLRegistrationElement interface */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
HTMLElement create();
};
</pre>

<tt>HTMLRegistrationElement#create()</tt> instantiates an registered element instance.

* TODO: The parameters of create() should match to the standard element constructor parameter list.

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.

Component Model Strawman: Element Registration

2011-10-27T19:07:25Z

Morrita:

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>creator</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>creator</tt> is invoked when an agent need a new element instance of the registered element.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.creator = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>creator</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.creator = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>creator</tt> attribute ===

A <tt>creator</tt> callback can also be set by the <tt>creator</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>creator</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
creator="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" creator="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreatorCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreatorCallback creator;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =

<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.

Component Model Strawman: Element Registration

2011-10-27T18:59:20Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>create</tt> attribute ===

A <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element.
Once the attribute value is set, that is invoked as an expression.
The expression should return a function object.
And the returned function object is set to <code>create</code> property of the <tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

This is especially useful if you have a class-style constructor. It can be given like this.

<pre>

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T18:53:32Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

HTMLRegistrationElement.current.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:17:40Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() {
return new HTMLElement(element.name);
};
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:16:56Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() {
return new HTMLElement("x-comment");
};
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:12:02Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment" create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:11:17Z

Morrita: /* Shadow Tree construction and the template element */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree Construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:10:24Z

Morrita: /* The setup callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

So if we define <tt>setup</tt> for the registered element, it will be called
as a <tt>setup</tt> callback.

<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
setup(shadow) {
// should be called.
}
}
</script>
</element>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:07:20Z

Morrita: /* The setup callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this);
...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:07:03Z

Morrita: /* The setup callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() {
this.shadow = new ShadowRoot(this); ...;
};
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:03:11Z

Morrita: /* Shadow Tree construction and the template element */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
HTMLRegistrationElement.current.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:02:19Z

Morrita: /* HTMLRegistrationElement interface */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
};

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
};

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T01:01:40Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element. The attribute value is invoked as an expression and
should return a function object.
The returned function object is set to <code>create</code> property of the
<tt>element</tt> element.

<pre>

<head>
<element name="x-comment"
create="function() { new HTMLElement('x-comment'); }">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T00:07:50Z

Morrita: /* The setup callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element.

<pre>

<head>
<element name="x-comment" create="new HTMLElement('x-comment')">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
HTMLRegistrationElement.current.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T00:02:54Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element.

<pre>

<head>
<element name="x-comment" create="new HTMLElement('x-comment')">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-27T00:02:22Z

Morrita: /* The create callback */

= Overview =

With the Element Registration mechanism.
page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are evaluated over a global object.
Before the evaluation, <tt>HTMLRegistrationElement.current</tt> is set to the
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = HTMLRegistrationElement.current.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
HTMLRegistrationElement.current.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

The <tt>create</tt> callback can also be set by the <tt>create</tt> attribute on <tt>element</tt> element.

<pre>

<head>
<element name="x-comment" create="new HTMLElement('x-comment')">
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following three markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>


<element name="x-comment" create="Comment">
<script>
class Comment : HTMLElement {
....
};
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement.register("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
HTMLRegistrationElement.current.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction and the <tt>template</tt> element ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-26T23:47:30Z

Morrita: /* The script element */

Component Model Strawman: Isolation

2011-10-26T23:43:07Z

Morrita: Replaced content with 'Stub.'

Stub.

Component Model Strawman: Element Registration

2011-10-26T20:28:52Z

Morrita: /* Shadow Tree construction */

Component Model Strawman: Element Registration

2011-10-26T20:26:57Z

Morrita: /* Overview */

Component Model Strawman: Element Registration

2011-10-26T20:25:39Z

Morrita: /* The create callback */

= Overview =

With the Element Registration. page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are invoked as a function, whose receiver(<tt>this</tt>) is bound to
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = this.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element name="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-26T20:25:11Z

Morrita:

= Overview =

With the Element Registration. page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element name="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are invoked as a function, whose receiver(<tt>this</tt>) is bound to
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element name="x-comment">
<script>
var shouldBeXComment = this.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element name="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.

<pre>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element name="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element for="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element name="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element name="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element name="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-26T20:20:40Z

Morrita:

= Overview =

With the Element Registration. page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element for="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are invoked as a function, whose receiver(<tt>this</tt>) is bound to
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element for="x-comment">
<script>
var shouldBeXComment = this.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element for="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.

<pre>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element for="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element for="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element for="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== Shadow Tree construction ==

The <tt>element</tt> element helps to construct a shadow tree for newly created elements.
If <tt>element</tt> element has a <tt>template</tt> element as its child,
The agent creates shadow tree from the <tt>template</tt> element before invoking the <tt>setup</tt>
callback, then invokes it with the shadow root.

<pre>


<head>
<element for="x-comment">
<template>
<div>...</div>
</template>
<script>
...
this.setup = function(shadow) {
// setup using the shadow instance.
};
</script>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(ShadowRoot shadow = null);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Declarative Syntax

2011-10-26T20:09:04Z

Morrita: /* Element Registration */

= Element Registration =

Moved to [[Component_Model_Strawman:_Element_Registration]]

= Shadow DOM Template =

An initial shape of new shadow tree can be defined using a <tt>template</tt> element.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
</template>
</head>

</pre>

A <tt>template</tt> is instantiated through

* <tt>ShadowRoot</tt> constructor and
* <tt>shadow-template</tt> CSS property.

== The ShadowRoot constructor ==

The <tt>ShadowRoot</tt> constructor accepts a <tt>template</tt> element to instantiate.

<pre>
..
this.shadow = new ShadowRoot(this, document.getElementById(“comment-template”));
..
</pre>

== The shadow-template CSS property (brainstorming) ==

The template for shadow root also can be applied using CSS property.

<pre>

.comment {
shadow-template: url('#comment-template');
}

</pre>

Note that imperatively-applied shadows always supersede shadows from the styling.
Also, there is no way to access style-originated shadows from the scripting environment.

== The Instantiation Event and Scripting ==

Even though the <tt>template</tt> can be used to define an extra visual representation for an element,
It would be useful if author can attach a script for the template-generated shadow tree.

The <tt>template</tt> element generates an <tt>instantiation</tt> event for
each template instantiation. Authors can listen it to setup event handlers for
generated elements by the template. The event doesn't bubble, and it isn't cancelable.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
</template>
<script>
var e = document.getElementById("comment-template");
e.addEventListener("instantiation", function(evt) {
evt.root.querySelector("div").addEventListener("click", function(evt) { ... });
});
</script>
</head>

</pre>

A <tt>template</tt> element also allows a <tt>script</tt> element as a child,
whose script block can access <tt>HTMLTemplateElement.current</tt> to refer the enclosing <tt>template</tt> element.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
<script>
HTMLTemplateElement.current.addEventListener("instantiation", function(evt) {
evt.root.querySelector("div").addEventListener("click", function(evt) { ... });
});
</script>
</template>
</head>

</pre>

= Isolation =

== Standalone Form ==

The element registration and template definition are also done in a separate HTML.
Effective markup vocabulary for the defining HTML is limited.
Agents only recognize a head element as a child of the root element when the HTML document is loaded as required.

<pre>

<html>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

The standalone definition can be done by a script file.

<pre>

<html>
<head>
<link rel=”component” type=”text/javascript” href="comment.js">
</head>
</html>

</pre>

This is equivalent to linking to a HTML file of like:

<pre>

<html provide>
<head>
<script type=”text/javascript” src="comment.js"></script>
</head>
</html>

</pre>

== Shared definition ==

In the default, these definitions are coming into the host document.
That means a providing HTML doesn’t have its own document nor the global object. Agents use these of the host document.

== Isolated definition ==

If the <tt>rel</tt> attribute contains the term <tt>isolate</tt>, the linked HTML is loaded as a separate document object.
The script inside the document is given a separate global object.

For the host document, there is no way to access the loaded document directly.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

[[User:Rolandsteiner|RolandSteiner]] Should we make <tt>isolate</tt> an attribute on <tt>link</tt> rather than a <tt>rel</tt> value? As Dimitri mentioned, this could be useful in general and would allow us to branch it off into a separate spec.

[[User:Morrita|Morrita]] Any declarative syntax is a part of other spec. This is cross-cutting view of multiple proposals. moved out confined declaration to standalone attribute. I have no idea how this works for other types of linked resources though.

Component Model Strawman: Element Registration

2011-10-26T20:07:13Z

Morrita: /* The element element and HTMLRegistrationElement */

= Overview =

With the Element Registration. page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element for="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are invoked as a function, whose receiver(<tt>this</tt>) is bound to
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element for="x-comment">
<script>
var shouldBeXComment = this.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element for="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.

<pre>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element for="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element for="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== Styling ==

The <tt>element</tt> element also allows the <tt>style</tt> element as its children.
The style given by the element is a part of document stylesheet.
Authors can use the <tt>style</tt> element to provide the style for the registering element.

<pre>

<head>
<element for="x-comment">
<style>
x-comment {
color: gray;
}
</style>
</element>
</head>

</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(HTMLElement);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-26T20:03:25Z

Morrita: /* The element element and HTMLRegistrationElement */

= Overview =

With the Element Registration. page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element for="x-comment"></element>
</head>

</pre>

== Scripting ==

=== The <tt>script</tt> element ===

The <tt>element</tt> element allows <tt>script</tt> elements in its children.
These script blocks are invoked as a function, whose receiver(<tt>this</tt>) is bound to
enclosing <tt>element</tt> element. These script blocks can be used for providing
lifecycle callback definitions for the registering element.

<pre>

<head>
<element for="x-comment">
<script>
var shouldBeXComment = this.name;
<script>
</element>
</head>

</pre>

=== The <tt>create</tt> callback ===

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element for="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.

<pre>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element for="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

=== The <tt>setup</tt> callback ===

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element for="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(HTMLElement);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-26T19:53:56Z

Morrita: /* The create callback */

= Overview =

With the Element Registration. page authors can tell new element names and its behavior to agents.

= The <tt>element</tt> element and <tt>HTMLRegistrationElement</tt> =

The <tt>HTMLRegistrationElement</tt> represents an author-registered element definition.

Here is the simplest example which registeres an element named "x-comment" whose instance implements
<tt>HTMLElement</tt>

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");


<head>
<element for="x-comment"></element>
</head>

</pre>

== The <tt>create</tt> callback ==

The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.

The first callback, <tt>create</tt> is invoked when an agent need a new element instance of the registered element.
<tt>create</tt> callback should return new element instance which matches the registered element specification.

<pre>

// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment", function() { ... });


<head>
<element for="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>

</pre>

If the callback function has <tt>HTMLElement</tt> in its prototype chain,
it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.

<pre>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = Comment;
</script>
</element>


<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};

this.create = function() { return new Comment(); };
</script>
</element>

// Imperative
class Comment : HTMLElement {
...
};

HTMLRegistrationElement("x-comment", Comment);
</pre>

If no <tt>create</tt> callback is given, its default behavior is something like this:

<pre>

<element for="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>

</pre>

== The <tt>setup</tt> callback ==

The second lifecycle callback, <tt>setup</tt> is called after an instance creation.
If the instance is created by the agent's tree construction, it will be called as a part of the "close" phase.
On <tt>setup</tt>, the attributes and child elements for the element are already set by the agent.
So this callback is useful for building its visual like the shadow tree.

<pre>

// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...


<head>
<element for="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>

</pre>

If no <tt>setup</tt> callback is given by the author, agent invokes the default behavior.
It is something like this:

<pre>
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
</pre>

== HTMLRegistrationElement interface ==

<pre>
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:

[Callback]
interface HTMLRegistrationSetupCallback {
void setup(HTMLElement);
}:

[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};
</pre>

Component Model Strawman: Element Registration

2011-10-26T19:51:30Z

Morrita: /* The setup callback */