Skip to content

added guts of custom elements semantics section #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Dec 8, 2014
Merged

added guts of custom elements semantics section #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7be4d5e
custom element semantics
stevefaulkner Dec 8, 2014
8e3ead1
added link
stevefaulkner Dec 8, 2014
99ef437
added text to code example
stevefaulkner Dec 8, 2014
d8f4612
chnaged example name to taco-button
stevefaulkner Dec 8, 2014
2cfbaac
filling out example
stevefaulkner Dec 8, 2014
caba906
filled out the examples
stevefaulkner Dec 8, 2014
6b342b3
code style
stevefaulkner Dec 8, 2014
80bafab
added code style
stevefaulkner Dec 8, 2014
3728645
added pretty code css
stevefaulkner Dec 8, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions assets/styles/spec.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,3 +249,31 @@ text {
opacity:0.8;
text-align:right;
}
.example {
background: none repeat scroll 0 0 #fcfcfc;
border-color: #c0c0c0;
border-left: 0.25em solid #c0c0c0;
color: #222222;
display: block;
margin-left: 1em;
padding-bottom: 0.5em;
padding-left: 1em;
}

div.example:before {
content: "Code Example: ";
font-weight: bolder;
}

p.note {
background: none repeat scroll 0 0 #e9fbe9;
border-color: #52e052;
border-left: 0.25em solid #52e052;
font-style:normal;
font-weight:normal;
font-size:medium;
color: #000000;


}
p.note:before {font-weight:bold;}
49 changes: 49 additions & 0 deletions spec/custom/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ <h2 id="toc">Table of Contents</h2>
</li>
<li><a href="#parsing">Parsing Custom Elements</a></li>
<li><a href="#es6">Custom Elements and ECMAScript 6</a></li>
<li><a href="#semantics">Custom Element Semantics</a></li>
<li><a href="#appendix-a">Appendix A: All Algorithms in One Diagram</a></li>
<li><a href="#acknowledgements" class="no-number">Acknowledgements</a></li>
</ol>
Expand Down Expand Up @@ -215,6 +216,7 @@ <h3 id="enqueuing-and-invoking-callbacks">Enqueuing and Invoking Callbacks</h3>
<dd><var>QUEUE</var>, an <a href="#dfn-element-queue">element queue</a></li>
<dt>Output</dt>
<dd>None</dd>
</dl>
<ol>
<li>For each <a href="#dfn-custom-element">custom element</a> <var>ELEMENT</var> in <var>QUEUE</var></a>:
<ol>
Expand Down Expand Up @@ -754,6 +756,53 @@ <h2 id="es6">Custom Elements and ECMAScript 6</h2>
</ol>
</div>

<h2 id="semantics">Custom Element Semantics</h2>
<p>The default <a href="http://www.w3.org/TR/html/dom.html#semantics-0">semantics</a> of a <a href="#dfn-custom-element">custom element</a> is dependent upon the form in which it is instiantated:</p>
<ul>
<li>by default a <a href="#dfn-custom-tag">custom tag</a> has no special meaning at all. It <a href="http://www.w3.org/TR/html/dom.html#represents">represents</a> its children.</li>
<li>by default a <a href="#dfn-type-extension">type extension</a> inherits the semantics of the element type it extends.</li>
</ul>
<h3>Custom Tag Semantics</h3>
<p>By default a <a href="#dfn-custom-tag">custom tag</a> has no special meaning at all. It <a href="http://www.w3.org/TR/html/dom.html#represents">represents</a> its children.</p>
<p>For example a custom tag, could be named <em>taco-button</em> but it does not express the semantics of a HTML <a href="http://www.w3.org/TR/html/forms.html#the-button-element"><code>button</code></a> element simply due to its name. As instaniated a custom tag conveys a similar amount of semantics as a HTML <a href="http://www.w3.org/TR/html/grouping-content.html#the-div-element"><code>div</code></a> or <code><a href="http://www.w3.org/TR/html/text-level-semantics.html#the-span-element">span</a></code> element. The addition of visual styling and scripted events to the <em>taco-button</em> could provide hints as to the semantics and expected interaction behaviours of the custom element for <em>some</em> users, but for the semantics to be formally expressed, developers must convey the role, states and properties of the element to browser APIs.</p>
<pre><code class="prettyprint">&lt;!-- taco-button represents a span with a fancy name -->
&lt;taco-button&gt;&lt;/taco-button&gt;</code>
</pre>
<p>The addition of a <code><a href="http://www.w3.org/TR/html/editing.html#attr-tabindex">tabindex</a></code> attribute to the <em>taco-button</em> element provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).</p>
<pre><code class="prettyprint">
&lt;!-- taco-button represents a focusable span with a fancy name -->
&lt;taco-button <mark>tabindex=&quot;0&quot;</mark>&gt;&lt;/taco-button&gt;</code>
</pre>
<p>The addition of a <a href="http://rawgit.com/w3c/aria/master/aria/aria.html#dfn-accessible-name"></a> text label to the <em>taco-button</em> element provides an <a href="http://rawgit.com/w3c/aria/master/aria/aria.html#dfn-accessible-name">Accessible Name</a> for the element.</p>
<pre><code class="prettyprint">
&lt;!-- taco-button represents a focusable span with a fancy name and a text label -->
&lt;taco-button tabindex=&quot;0&quot;&gt;<mark>Eat Me</mark>&lt;/taco-button&gt;
or
&lt;taco-button tabindex=&quot;0&quot; <mark>aria-label=&quot;Eat Me&quot;</mark>&gt;&lt;/taco-button&gt;</code>
</pre>
<p>The addition of keyboard event handlers to the <em>taco-button</em> element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.</p>
<p class="note">The addition of in line event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all.</p>
<pre><code class="prettyprint">
&lt;!-- taco-button represents focusable span with a fancy name, a text label and button like event handling -->
&lt;taco-button tabindex=&quot;0&quot; <mark>onclick=&quot;alert('tasty eh?');&quot;</mark>
<mark>onkeypress=&quot;if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};&quot;</mark>&gt;Eat Me&lt;/taco-button&gt;</code>
</pre>
<p>The addition of an ARIA <a href="http://rawgit.com/w3c/aria/master/aria/aria.html#button"><code>role="button"</code></a> conveys the <em>taco-button</em> element's role semantics, which enables users to successfully interact with the control using the expected <code>button</code> interaction behaviours (pressing the <kbd>space</kbd> or <code>enter</code> keys to activate).</p>
<pre><code class="prettyprint">
&lt;!-- taco-button represents a focusable button with a text label and button like event handling -->
&lt;taco-button <mark>role=&quot;button&quot;</mark> tabindex=&quot;0&quot; onclick=&quot;alert('tasty eh?');&quot;
onkeypress=&quot;if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};&quot;&gt;Eat Me&lt;/taco-button&gt;</code></pre>
<h3>Type Extension Semantics </h3>
<p>By default a <a href="#dfn-type-extension">type extension</a> inherits the semantics of the element type it extends.</p>
<p>For example a type extension, could extend the HTML <a href="http://www.w3.org/TR/html/forms.html#the-button-element"><code>button</code></a> element. As instaniated it would inherit the <code>button</code> element's name, role, states and properties, built in focus and keyboard interaction behaviours. </p>
<pre><code class="prettyprint">&lt;!-- taco-button represents a button with an accesssible name of &quot;Eat Me!&quot; -->
&lt;button <mark>is=&quot;taco-button&quot;</mark>&gt;Eat Me!&lt;/taco-button&gt;</code>
</pre>
<p>To provide the desired <em>taco-button</em> feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the <a href="http://www.w3.org/TR/html/forms.html#the-button-element"><code>button</code></a> element.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this informative content? Maybe mark it as such? I am not sure, this is necessary. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added note

<pre><code class="prettyprint">&lt;!-- taco-button represents a button -->
&lt;button is=&quot;taco-button&quot; <mark>onclick=&quot;alert('tasty eh?');&quot;</mark>&gt;Eat Me!&lt;/taco-button&gt;</code>
</pre>
<p class="note">TO DO </p>
<h2 id="appendix-a">Appendix A: All Algorithms in One Diagram</h2>

<div class="informative">
Expand Down