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

From WHATWG Wiki
Jump to navigation Jump to search
No edit summary
Line 50: Line 50:
</pre>
</pre>


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


The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
The <tt>HTMLRegistrationElement</tt> provide a pair of lifecycle callbacks
for the element instance creation including the tree construction.
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.  
The first callback, <tt>creator</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.
<tt>creator</tt> callback should return new element instance which matches the registered element specification.


<pre>
<pre>
Line 63: Line 63:
var element = document.createElement("element");
var element = document.createElement("element");
element.name = "x-comment";
element.name = "x-comment";
element.create = function() { return new HTMLElement("x-comment"); };
element.creator = function() { return new HTMLElement("x-comment"); };
document.head.appendChild(element);
document.head.appendChild(element);
// Shorter form.
// Shorter form.
Line 72: Line 72:
   <element name="x-comment">
   <element name="x-comment">
     <script>
     <script>
     HTMLRegistrationElement.current.create = function() {
     HTMLRegistrationElement.current.creator = function() {
       return new HTMLElement("x-comment");
       return new HTMLElement("x-comment");
     };
     };
Line 93: Line 93:
     };
     };


     HTMLRegistrationElement.current.create = Comment;
     HTMLRegistrationElement.current.creator = Comment;
     </script>
     </script>
   </element>
   </element>
Line 104: Line 104:
     };
     };


     HTMLRegistrationElement.current.create = function() { return new Comment(); };
     HTMLRegistrationElement.current.creator = function() { return new Comment(); };
     </script>
     </script>
   </element>
   </element>
Line 116: Line 116:
</pre>
</pre>


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


<pre>
<pre>
Line 123: Line 123:
     <script>
     <script>
     var element = this;
     var element = this;
     HTMLRegistrationElement.current.create = function() {
     HTMLRegistrationElement.current.creator = function() {
       return new HTMLElement(element.name);
       return new HTMLElement(element.name);
     };
     };
Line 131: Line 131:
</pre>
</pre>


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


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


<pre>
<pre>
Line 142: Line 142:
<head>
<head>
   <element name="x-comment"  
   <element name="x-comment"  
     create="function() { new HTMLElement('x-comment'); }">
     creator="function() { new HTMLElement('x-comment'); }">
   </element>
   </element>
</head>
</head>
Line 152: Line 152:
<pre>
<pre>


   <element name="x-comment" create="Comment">
   <element name="x-comment" creator="Comment">
     <script>
     <script>
     class Comment : HTMLElement {
     class Comment : HTMLElement {
Line 210: Line 210:




   <element name="x-comment" create="Comment">
   <element name="x-comment" creator="Comment">
     <script>
     <script>
     class Comment : HTMLElement {
     class Comment : HTMLElement {
Line 271: Line 271:
<pre>
<pre>
[Callback=AcceptConstructor]
[Callback=AcceptConstructor]
interface HTMLRegistrationCreateCallback {
interface HTMLRegistrationCreatorCallback {
  HTMLElement create();
  HTMLElement create();
};
};
Line 283: Line 283:
interface HTMLRegistrationElement {
interface HTMLRegistrationElement {
   attribute String name;
   attribute String name;
   attribute HTMLRegistrationCreateCallback create;
   attribute HTMLRegistrationCreatorCallback creator;
   attribute HTMLRegistrationSetupCallback setup;
   attribute HTMLRegistrationSetupCallback setup;
};
};
</pre>
</pre>
= <tt>HTMLRegistrar</tt> and <tt>document.elements</tt> =
<tt>HTMLRegistrar</tt> is an object oriented way to access registered element definitions.

Revision as of 19:07, 27 October 2011

Overview

With the Element Registration mechanism. 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 name="x-comment"></element>
</head>

Scripting

The script element

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


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

The creator callback

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

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


// 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() { ... });

<!-- Markup API -->
<head>
  <element name="x-comment">
    <script>
    HTMLRegistrationElement.current.creator = 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 three markup and one imperative examples have same meaning.


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

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

<!-- Markup 2 -->
  <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);

If no creator callback is given, its default behavior is something like this:


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

The creator attribute

A creator callback can also be set by the creator attribute on element 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 creator property of the element element.


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

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


  <element name="x-comment" creator="Comment">
    <script>
    class Comment : HTMLElement {
       ....
    };
    </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 name="x-comment">
    <script>
     ...
     HTMLRegistrationElement.current.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();
}

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


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

Styling

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



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

Shadow Tree Construction and the template element

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


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

HTMLRegistrationElement interface

[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;
};

HTMLRegistrar and document.elements

HTMLRegistrar is an object oriented way to access registered element definitions.