A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.
To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).
Component Model Strawman: Element Registration: Difference between revisions
| Line 27: | Line 27: | ||
</pre> | </pre> | ||
== The <tt>create</tt> callback == | == 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 | The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks | ||
| Line 104: | Line 125: | ||
</pre> | </pre> | ||
== The <tt>setup</tt> callback == | === The <tt>setup</tt> callback === | ||
The second lifecycle callback, <tt>setup</tt> is called after an instance creation. | The second lifecycle callback, <tt>setup</tt> is called after an instance creation. | ||
Revision as of 20:03, 26 October 2011
Overview
With the Element Registration. page authors can tell new element names and its behavior to agents.
The element element and HTMLRegistrationElement
The HTMLRegistrationElement represents an author-registered element definition.
Here is the simplest example which registeres an element named "x-comment" whose instance implements HTMLElement
// Imperative API
var element = document.createElement("element");
element.name = "x-comment";
document.head.appendChild(element);
// Shorter form.
HTMLRegistrationElement.register("x-comment");
<!-- Markup API -->
<head>
<element for="x-comment"></element>
</head>
Scripting
The script element
The element element allows script elements in its children. These script blocks are invoked as a function, whose receiver(this) is bound to enclosing element element. These script blocks can be used for providing lifecycle callback definitions for the registering element.
<head>
<element for="x-comment">
<script>
var shouldBeXComment = this.name;
<script>
</element>
</head>
The create callback
The HTMLRegistrationElement provide a pair of lifecycle callbacks for the element instance creation including the tree construction.
The first callback, create is invoked when an agent need a new element instance of the registered element. create callback should return new element instance which matches the registered element specification.
// 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() { ... });
<!-- Markup API -->
<head>
<element for="x-comment">
<script>
this.create = function() { return new HTMLElement("x-comment"); };
</script>
</element>
</head>
If the callback function has HTMLElement in its prototype chain, it is invoked as a constructor. Thus following two markup and one imperative examples have same meaning.
<!-- Markup 1 -->
<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};
this.create = Comment;
</script>
</element>
<!-- Markup 2 -->
<element for="x-comment">
<script>
class Comment : HTMLElement {
....
};
this.create = function() { return new Comment(); };
</script>
</element>
// Imperative
class Comment : HTMLElement {
...
};
HTMLRegistrationElement("x-comment", Comment);
If no create callback is given, its default behavior is something like this:
<element for="x-comment">
<script>
var element = this;
this.create = function() { return new HTMLElement(element.name); };
</script>
</element>
The setup callback
The second lifecycle callback, setup 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 setup, 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.
// Imperative API
var element = document.createElement("element");
...
element.setup = function() { this.shadow = new ShadowRoot(this); ...; };
...
<!-- Markup API -->
<head>
<element for="x-comment">
<script>
...
this.setup = function() {
// "this" points the newly created element instance.
this.shadow = new ShadowRoot(this);
...;
};
</script>
</element>
</head>
If no setup callback is given by the author, agent invokes the default behavior. It is something like this:
function defaultSetup() {
if (this.setup instanceof Function)
this.setup();
}
HTMLRegistrationElement interface
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
HTMLElement create();
}:
[Callback]
interface HTMLRegistrationSetupCallback {
void setup(HTMLElement);
}:
[Constructor]
interface HTMLRegistrationElement {
attribute String name;
attribute HTMLRegistrationCreateCallback create;
attribute HTMLRegistrationSetupCallback setup;
};