<commit_before>WORK IN PROGRESS

# Polymer 0.8 Primer

Table of Contents:

* [Feature layering](#feature-layering)
* [Polymer micro features](#polymer-micro)
* [Polymer mini features](#polymer-mini)
* [Polymer standard features](#polymer-standard)
* [Migration notes](#migration-notes)

<a name="feature-layering"></a>
# Feature layering

Polymer 0.8 is currently layered into 3 sets of features provided as 3 discrete HTML imports, such that an individual element developer can depend on a version of Polymer whose feature set matches their tastes/needs.  For authors who opt out of the more opinionated local DOM or data-binding features, their element's dependencies would not be payload- or runtime-burdened by these higher-level features, to the extent that a user didn't depend on other elements using those features on that page.  That said, all features are designed to have low runtime cost when unused by a given element.

Higher layers depend on lower layers, and elements requiring lower layers will actually be imbued with features of the highest-level version of Polymer used on the page (those elements would simply not use/take advantage of those features).  This provides a good tradeoff between element authors being able to avoid direct dependencies on unused features when their element is used standalone, while also allowing end users to mix-and-match elements created with different layers on the same page.

Below is a description of the current Polymer layers and included features, followed by individual feature guides.

## polymer-micro.html
Bare-minum Custom Element sugaring

| Feature | Usage 
|---------|-------
| [Custom element constructor](#element-constructor) | Polymer.Class({ … });
| [Custom element registration](#register-element) | Polymer({ is: ‘...’,  … }};
| [Bespoke constructor support](#bespoke-constructor) | constructor: function() { … }
| [Basic lifecycle callbacks](#basic-callbacks) | created, attached, detached, attributeChanged
| [Native HTML element extension](#type-extension) | extends: ‘…’
| [Publish API](#published-api) | published: { … }
| [Attribute deserialization to property](#attribute-deserialization) | published: { \<property>: \<Type> }
| [Set boolean host attributes](#host-attributes) | hostAttributes: [ … ]
| [Module registry](#module-registry) | modularize, using
| [Prototype Mixins](#prototype-mixins) | mixins: [ … ]

## polymer-mini.html
Custom Elements with Templates stamped into "local DOM"

| Feature | Usage 
|---------|-------
| [Template stamping into local DOM](#template-stamping) | \<dom-module>\<template>...\</template>\</dom-module>
| [DOM (re-)distribution](#dom-distribution) | \<content>
| [Local & light tree API](#dom-api)	| localDom, lightDom
| [Bottom-up callback after configuration](#ready-method) | ready: function() { … }
| [Top-down callback after distribution](#configure-method) | configure: function() { … }

## polymer.html (standard)
Custom elements with declarative data binding, events, and property nofication

| Feature | Usage 
|---------|-------
| [Local node marshalling](#node-marshalling) | this.$.\<id>
| [Event listener setup](#event-listeners)| listeners: { ‘\<node>.\<event>’: ‘function’, ... }
| [Annotated event listener setup](#annotated-listeners) | \<element on-[event]=”function”>
| [Key listener setup](#key-listeners) | keyPresses: { '\<char>' | \<code>: ‘function’, … }
| [Property change callbacks](#change-callbacks) | bind: { \<property>: ‘function’ }
| [Declarative property binding](#property-binding) | \<element prop=”{{property|path}}”
| [Computed properties](#computed-properties) | compute: { \<property>: ‘function(\<property>)’ }
| [Path change notification](#set-path) | setPathValue(\<path>, \<value>)
| [Utility functions](#utility-functions) | toggleClass, toggleAttribute, fire, async, …
| [Attribute-based layout](#layout-html) | layout.html (layout horizontal flex ...)

<a name="polymer-micro"></a>
# Polymer Micro Features

<a name="element-constructor"></a>
## Custom Element Constructor

The most basic Polymer API is `Polymer.Class({...})`, which takes an object expressing the prototype of your custom element, chains it to Polymer's `Base` prototype (which provides value-add features described below), and returns a constructor that can be passed to `document.regsterElement()` to register your element with the HTML parser, and after which can be used to instantiate new instances of your element via code.<commit_msg>Escape pipes in feature usage description.<commit_after>WORK IN PROGRESS

# Polymer 0.8 Primer

Table of Contents:

* [Feature layering](#feature-layering)
* [Polymer micro features](#polymer-micro)
* [Polymer mini features](#polymer-mini)
* [Polymer standard features](#polymer-standard)
* [Migration notes](#migration-notes)

<a name="feature-layering"></a>
# Feature layering

Polymer 0.8 is currently layered into 3 sets of features provided as 3 discrete HTML imports, such that an individual element developer can depend on a version of Polymer whose feature set matches their tastes/needs.  For authors who opt out of the more opinionated local DOM or data-binding features, their element's dependencies would not be payload- or runtime-burdened by these higher-level features, to the extent that a user didn't depend on other elements using those features on that page.  That said, all features are designed to have low runtime cost when unused by a given element.

Higher layers depend on lower layers, and elements requiring lower layers will actually be imbued with features of the highest-level version of Polymer used on the page (those elements would simply not use/take advantage of those features).  This provides a good tradeoff between element authors being able to avoid direct dependencies on unused features when their element is used standalone, while also allowing end users to mix-and-match elements created with different layers on the same page.

Below is a description of the current Polymer layers and included features, followed by individual feature guides.

## polymer-micro.html
Bare-minum Custom Element sugaring

| Feature | Usage 
|---------|-------
| [Custom element constructor](#element-constructor) | Polymer.Class({ … });
| [Custom element registration](#register-element) | Polymer({ is: ‘...’,  … }};
| [Bespoke constructor support](#bespoke-constructor) | constructor: function() { … }
| [Basic lifecycle callbacks](#basic-callbacks) | created, attached, detached, attributeChanged
| [Native HTML element extension](#type-extension) | extends: ‘…’
| [Publish API](#published-api) | published: { … }
| [Attribute deserialization to property](#attribute-deserialization) | published: { \<property>: \<Type> }
| [Set boolean host attributes](#host-attributes) | hostAttributes: [ … ]
| [Module registry](#module-registry) | modularize, using
| [Prototype Mixins](#prototype-mixins) | mixins: [ … ]

## polymer-mini.html
Custom Elements with Templates stamped into "local DOM"

| Feature | Usage 
|---------|-------
| [Template stamping into local DOM](#template-stamping) | \<dom-module>\<template>...\</template>\</dom-module>
| [DOM (re-)distribution](#dom-distribution) | \<content>
| [Local & light tree API](#dom-api)	| localDom, lightDom
| [Bottom-up callback after configuration](#ready-method) | ready: function() { … }
| [Top-down callback after distribution](#configure-method) | configure: function() { … }

## polymer.html (standard)
Custom elements with declarative data binding, events, and property nofication

| Feature | Usage 
|---------|-------
| [Local node marshalling](#node-marshalling) | this.$.\<id>
| [Event listener setup](#event-listeners)| listeners: { ‘\<node>.\<event>’: ‘function’, ... }
| [Annotated event listener setup](#annotated-listeners) | \<element on-[event]=”function”>
| [Key listener setup](#key-listeners) | keyPresses: { '\<char>' \| \<code>: ‘function’, … }
| [Property change callbacks](#change-callbacks) | bind: { \<property>: ‘function’ }
| [Declarative property binding](#property-binding) | \<element prop=”{{property\|path}}”
| [Computed properties](#computed-properties) | compute: { \<property>: ‘function(\<property>)’ }
| [Path change notification](#set-path) | setPathValue(\<path>, \<value>)
| [Utility functions](#utility-functions) | toggleClass, toggleAttribute, fire, async, …
| [Attribute-based layout](#layout-html) | layout.html (layout horizontal flex ...)

<a name="polymer-micro"></a>
# Polymer Micro Features

<a name="element-constructor"></a>
## Custom Element Constructor

The most basic Polymer API is `Polymer.Class({...})`, which takes an object expressing the prototype of your custom element, chains it to Polymer's `Base` prototype (which provides value-add features described below), and returns a constructor that can be passed to `document.regsterElement()` to register your element with the HTML parser, and after which can be used to instantiate new instances of your element via code.
{'fraction_non_alphanumeric': 0.13494270775392145, 'fraction_numerical': 0.0013349649571698743, 'mean_word_length': 5.021433355659745, 'pattern_counts': {'":': 0, '<': 53, '<?xml version=': 0, '>': 51, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6008091', 'n_tokens_mistral': 2473, 'n_tokens_neox': 2281, 'n_words': 928}