New TOC for dart-by-example page

src/site/articles/web-ui/spec.markdown

 ---
 layout: article
 title: "Web UI Specification"
 rel:
   author: siggi-cherem
 description: "A detailed reference guide of how to use Web UI for declarative modern web apps."
 has-permalinks: true
 ---
 {% comment %}
 
@@ skipping 81 matching lines @@
 <aside>
 <div class="alert alert-info">
 <strong>Status:</strong> It should be allowed to declare element tags anywhere,
 not just in the body of an HTML page. See
 <a href="https://github.com/dart-lang/web-ui/issues/197">Issue
 #197</a> for details.
 </div>
 </aside>
 
 #### Appearance
+{:.no_toc}
 
 Every component inherits from existing tags.
 This includes tags corresponding to
 standard DOM elements or previously defined components. For example, you can
 extend `div`, `span`, `button`, `x-my-button`, etc. The base tag for the
 component is specified in the `extends` attribute. The idea is that a component
 can override and compose the appearance and behavior of its base tag. It is a
 common practice to use `span` as the base tag if you intend to define the
 entire appearance of a component yourself.
 
@@ skipping 26 matching lines @@
 <div class="alert alert-info">
 <strong>NOTE:</strong> scoped <code>style</code> is not supported yet in the
 current implementation of the the Web UI compiler, and a lot of details are
 missing in this specification. Learn more at the <a
 href="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html#styles">web
 components specification article</a>.
 </div>
 </aside>
 
 #### Behavior
+{:.no_toc}
 
 The behavior of a component is declared directly in Dart code. The `<script>`
 tag declares the code associated with the component.
 It must be specified unless
 a component has no behavior and its code can be assumed to be an empty class.
 If the tag is present, it must use the `type="application/dart"` attribute to
 indicate that the code is written in Dart.
 
 Whether you write code inline or you include it via a `src` attribute, the code
 must be a valid Dart library. In such a library you must define a class
@@ skipping 200 matching lines @@
 interactive element, such as input boxes and text areas.
 
 If data bindings are used within a component, the associated Dart expressions
 are resolved in the scope of the class associated with the component (see more
 details [above](#template-scope)). If data bindings are used directly on
 the body of an HTML page, these expressions are evaluated in the context of the
 main script associated with that page (more details
 [later](#top-level-templates)).
 
 #### Binding in content
+{:.no_toc}
 
 You can introduce a data binding in a text node
 by using expressions of the form
 `{{'{{'}}exp}}` as nodes in your HTML. For example, a component with the
 following template:
 
 {% prettify html %}
 {% raw %}
 <element name='x-example2'>
  <template><span>one {{x}} tree</span></template>
@@ skipping 20 matching lines @@
 than what you initially intended to happen.
 
 The program generated by the Web UI compiler will evaluate a
 binding expression to a value,  call [`toString()`][tostring] on it and place
 the result as a text node where the binding was found. This means that if your
 content has some HTML tags in it, the content is automatically escaped. For
 instance, if we use `x='<span>two</span>'`, the result will be `<span>one
 &lt;span&gt;two&lt;/span&gt; three</span>`
 
 On occasions, you may want to inject HTML fragments directly in the page.
-You can do so by creating an instance of `SafeHtml` (see 
+You can do so by creating an instance of `SafeHtml` (see
 [`package:web_ui/safe_html.dart`][safehtml]). If your content happen to
 be an instance of `SafeHtml`, then the data will not be escaped.
 
 **Note:** Use `SafeHtml` carefully. In particular, you can easily
 make your application exploitable through cross-site scripting (XSS) attacks if
 you allow arbitrary user data to be placed unescaped in your page. In practice,
 you should only use it when you know that the HTML is valid and safe.
 
 <aside>
 <div class="alert alert-info">
 <strong>Status:</strong> `SafeHtml` is available but very primitive at this
 point. This type should evolve,
 and maybe one day it could be integrated as part
 of the `dart:html` APIs.
 </div>
 </aside>
 
 #### Binding in attributes
+{:.no_toc}
 
 You can also use `{{'{{'}}expression}}` bindings in the middle of HTML
 attributes. An attribute written as `foo="{{'{{'}}exp}}"` will be initialized
 with the value of `exp`. Like bindings in content nodes, expressions are
 [watched](#watchers) for changes and attributes will be updated in place when
 expressions' changes are detected.  At runtime, attribute values will be updated
 using an assignment directly on the HTML element property corresponding to that
 attribute. Bindings of the form `attribute="{{'{{'}}exp}}"` are assigned
 directly, however bindings of the form `attribute="abc {{'{{'}}exp}} xyc"` will
 perform string interpolation.
@@ skipping 66 matching lines @@
 </element>
 {% endraw %}
 {% endprettify %}
 
 
 * style attributes: you can pass either a `String` or a `Map<String, String>` as
   a binding to `style` attributes. When using a map, we track changes to
   the map keys and values and update actual style of the element accordingly.
 
 #### Binding interactive elements
+{:.no_toc}
 
 Bindings can also be used to monitor user modifications on interactive elements,
 such as input boxes, text areas, and radio buttons. We do so by binding an
 interactive element with a Dart assignable value, such as a field or a property
 with a getter and setter. Unlike the bindings we discussed above, these bindings
 operate in two directions: changes in the Dart value are reflected in the UI,
 but also changes from the user in the UI are reflected directly in the Dart
 value. Because of their bidirectional nature, we refer to these bindings as
 _two-way data bindings_. Two-way data bindings are expressed with an attribute
 of the form `bind-property="assignableValue"`, where _property_ is the
 associated property in the HTML element that we are monitoring, and
 _assignableValue_ is a Dart assignable value. This is the current list of
 two-way bindings supported by Web UI:
 
 | | Interactive element          |  | Attribute      |  | Description                                |  | Event that triggers an update |
-|-| :-----------                 |- | :--------      |- | :-------                                   |- | :------ | 
+|-| :-----------                 |- | :--------      |- | :-------                                   |- | :------ |
 | | `<textarea>`                 |  | `value`        |  | The current value in the textarea element  |  | `input`  |
 | | `<input type="text">`        |  | `value`        |  | The current value in the input box         |  | `input`  |
 | | `<input type="checkbox">`    |  | `checked`      |  | Whether the checkbox is checked            |  | `change` |
 | | `<input type="radio">`       |  | `checked`      |  | Whether a radio button is checked          |  | `change` |
 | | `<input name="group" type="radio" value="option">`       |  | `value`        |  | Whether a value matches the radio button's value |  | `change` |
 | | `<select>`                   |  | `selected-index`|  | Selected option index on the dropdown list |  | `change` |
 | | `<select>`                   |  | `value`        |  | Selected option value on the dropdown list |  | `change` |
 |=| ===============              |= | =========      |= | ========                                   |= | == |
 
 Under the hood two-way bindings are implemented by using a [watcher](#watchers)
@@ skipping 36 matching lines @@
 
 <aside>
 <div class="alert alert-info">
   <strong>Status:</strong> More interactive elements need to be supported.
 </div>
 </aside>
 
 
 
 #### Watchers
+{:.no_toc}
 
 As hinted in the previous sections, data bindings are reactive. We would like
 the UI to be updated automatically whenever a Dart expression used in a data
 binding changes. Watchers provide a way to implement this functionality. Their
 implementation is available under `package:web_ui/watcher.dart`. For
 each expression used in a data binding, we create a watcher. These watchers are
 inactive until the special method `dispatch` in the watcher's library is
 invoked. The `dispatch` method will iterate over all active watchers and fire
 events on any watcher whose value has changed.
 
@@ skipping 24 matching lines @@
 
 Portions of the template can be conditionally hidden using template
 conditionals. Web UI supports two different ways to express conditionals. You
 can make a document fragment conditionally visible by declaring it within a
 conditional `<template>` element node, or you can make an element and its
 children conditionally visible by using a conditional attribute
 in the element. Next, we discuss each of these approaches and when it is
 appropriate to [use one or the other](#which-conditional).
 
 #### The conditional element node {#conditional-template}
+{:.no_toc}
 
 A template conditional element is a `<template>` tag containing a special
 attribute of the form `instantiate="if expression"`, where `expression` is a
 valid Dart expression, just like any [data binding expression](#data-binding).
 Alternatively, instead of `instantiate="if exp"` you can write `if="exp"`.
 
 <aside>
 <div class="alert alert-info">
-<strong>Note:</strong> 
+<strong>Note:</strong>
 The final syntax for conditionals is not finalized. In particular, currently
 only <code>instantiate="if ..."</code> is part of the MDV specification.
 However, Web UI supports both <code>instantiate="if ..."</code> and
 <code>if="..."</code> and it will later provide feedback whenever one is
 deprecated in favor of the other.
 </div>
 </aside>
 
 Consider this concrete example:
 
@@ skipping 39 matching lines @@
 </div>
 here
 Unconditional portion 2
 {% endprettify %}
 
 Note that the contents of the initial template are not within the template
 tag anymore, they got added directly as siblings. This behavior is
 intentional. Template nodes are intended to be inert, and they are mainly used
 as a declaration. This matches closely the semantics of [MDV][mdv] templates.
 
-A benefit of this semantics is that the resulting HTML is often closer to 
+A benefit of this semantics is that the resulting HTML is often closer to
 what the developer intended to say. For example, a template of the form:
 
 {% prettify html %}
 <ul>
   <li> item 1
   <template instantiate="if showItem2">
     <li> item 2
   </template>
 </ul>
 {% endprettify %}
@@ skipping 34 matching lines @@
 {% prettify html %}
 {% raw %}
 <element name='x-example'>
  <!-- invalid: we need an extra template here. -->
  <template instantiate="if true">this is invalid</template>
 </element>
 {% endraw %}
 {% endprettify %}
 
 #### The conditional attribute. {#conditional-attribute}
+{:.no_toc}
 
 An alternative syntax to create conditional content is to use a conditional
 attribute on an arbitrary element. This is especially useful in contexts where
 you are not allowed to insert a `<template>` element (such as tables).
 
 You can express a conditional by adding two attributes to any element, an empty
 `template` attribute, and a `instantiate="if ..."` attribute. For example, in
 the following code, `item 2` will only be visible if `showItem2` is true.
 
 {% prettify html %}
@@ skipping 39 matching lines @@
 
 <aside>
 <div class="alert alert-info">
 <strong>Note:</strong> These semantics might change in the near future. The
 placeholder in this case seems redundant when the condition is true - we could
 simply reuse the placeholder node to render the contents within it.
 </div>
 </aside>
 
 #### Conditional element vs. attribute {#which-conditional}
+{:.no_toc}
 
 The main difference between conditional template nodes and conditional
 attributes is that the former makes the contents of the template node
 conditionally visible, while the latter makes the actual node conditionally
 visible.
 
 This difference is especially noticeable when making plain text nodes
 conditionally visible. For example, the following template:
 
 {% prettify html %}
@@ skipping 56 matching lines @@
 
 Loops make it possible to iterate over a collection and repeat portions of a
 template with each iteration. Just like [conditionals](#conditionals),
 there are
 also 2 ways to express loops.
 You can repeat a fragment by declaring it within a
 iterate `<template>` element node, or you can repeat the body of an element by
 using an iterate attribute on the element.
 
 #### The iterate element node {#iterate-template}
+{:.no_toc}
 
 A template iterate element is a `<template>` tag containing a special attribute
 of the form `iterate="identifier in expression"`, where `expression` evaluates
 to a collection, and `identifier` is a new variable that will be visible to the
 body of the iterate element. For instance, in the following example:
 
 {% prettify html %}
 {% raw %}
 <ul>
   <li> header
@@ skipping 33 matching lines @@
   <li> footer
 </ul>
 {% endprettify %}
 
 See the sections above on [conditionals](#conditionals) for more details on why
 children of the template node are appended directly as siblings of the
 placeholder node, and to understand what implications this has during app
 development.
 
 #### The iterate attribute {#iterate-attribute}
+{:.no_toc}
 
 An alternative syntax to do template iterations is
 to use an `iterate` attribute
 directly on an element. This is especially useful to iterate on table rows or
 columns, where you are not allowed to use `<template>` tags.
 
 The runtime semantics of iterate attributes are different than iterate template
 nodes. The placeholder node and the iteration element are basically the same.
 The node is always present, but its contents are modified depending on the
 values found in the collection. For example, the following template:
@@ skipping 22 matching lines @@
 {% endprettify %}
 
 <aside>
 <div class="alert alert-info">
 <strong>Note:</strong> In the future a single attribute will be enough, we
 intent to remove the extra <code>template</code> attribute.
 </div>
 </aside>
 
 #### Iterate element vs. attribute {#which-loop}
+{:.no_toc}
 
 The main difference between iterate template nodes and iterate attributes is
 that the former appends the repeated contents
 as siblings of the iteration node,
 while the latter appends them as children of
 the element containing the iterate attribute.
 
 This difference is especially noticeable when you want to create a list with a
 header and a footer. This is supported by template nodes as follows:
 
@@ skipping 174 matching lines @@
 [dart-scope-rules]: http://www.dartlang.org/docs/spec/latest/dart-language-specification.html#h.jb82efuudrc5
 [project]: https://github.com/dart-lang/web-ui/
 [mdv]: http://code.google.com/p/mdv/
 [sd]: http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html
 [shadow-el]: http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html#shadow-element
 [wc]: http://dvcs.w3.org/hg/webcomponents/raw-file/tip/explainer/index.html
 [wcappendix]: http://dvcs.w3.org/hg/webcomponents/raw-file/tip/explainer/index.html#appendix-b-html-elements
 [tostring]: http://api.dartlang.org/docs/bleeding_edge/dart_core/Object.html#toString
 [safehtml]: https://github.com/dart-lang/web-ui/blob/master/lib/safe_html.dart
 [elemevents]: http://api.dartlang.org/docs/releases/latest/dart_html/Element.html