diff --git a/.gitignore b/.gitignore index f673b87d58..bcd6f8be2e 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,6 @@ build # Dev directories /app/bower_components /node_modules +/scripts/node_modules +/scripts/temp +/scripts/*_analysis.json diff --git a/app/2.0/docs/devguide/custom-elements.md b/app/2.0/docs/devguide/custom-elements.md index 65b754d843..3e169fc90f 100644 --- a/app/2.0/docs/devguide/custom-elements.md +++ b/app/2.0/docs/devguide/custom-elements.md @@ -52,6 +52,8 @@ Polymer adds a set of features to the basic custom element: * Creating shadow DOM trees for element instances based on a supplied template. * A data system that supports data binding, property change observers, and computed properties. + + ## Custom element lifecycle {#element-lifecycle} The custom element spec provides a set of callbacks called "custom element reactions" that allow you @@ -218,33 +220,8 @@ by any pending lifecycle callbacks. Element upgrades allow you to place elements in the DOM while deferring the cost of initializing them. It's a progressive enhancement feature. -Elements have a *custom element state* that takes one of the following values: - - - -* "uncustomized". The element does not have a valid custom element name. It is either a built-in - element (`

`, ``) or an unknown element that cannot become a custom element - (``) -* "undefined". The element has a valid custom element name (such as "my-element"), but has not - been defined. -* "custom". The element has a valid custom element name and has been defined and upgraded. -* "failed". An attempt to upgrade the element failed (for example, because the class was invalid). - -The custom element state isn't exposed as a property, but you can style elements depending on -whether they're defined or undefined. - -Elements in the "custom" and "uncustomized" state are considered "defined". In CSS you can use the -`:defined` pseudo-class selector to target elements that are defined. You can use this to provide -placeholder styles for elements before they're upgraded: - -``` -my-element:not(:defined) { - background-color: blue; -} -``` - -**`:defined` is not supported by the Custom Elements polyfill.** See the [documentation on styling](style-shadow-dom#style-undefined-elements) for a workaround. -{.alert .alert-warning} +To avoid showing unstyled content, you can add styles for elements that haven't upgraded yet. For +details, see [Style undefined elements](style-shadow-dom#style-undefined-elements). ## Extending other elements {#extending-elements} diff --git a/app/2.0/docs/devguide/registering-elements.md b/app/2.0/docs/devguide/registering-elements.md index 6e1bb716ca..994202fd3e 100644 --- a/app/2.0/docs/devguide/registering-elements.md +++ b/app/2.0/docs/devguide/registering-elements.md @@ -133,7 +133,7 @@ customElements.define('x-class', XClass); ``` The `mixinBehavior` function also mixes in the Legacy APIs, the same as if you extended -`Polymer.LegacyElement`. These APIs are required since since hybrid behaviors depend on them. +`Polymer.LegacyElement`. These APIs are required since hybrid behaviors depend on them. ## Define an element in the main HTML document {#main-document-definitions} diff --git a/app/2.0/docs/devguide/style-shadow-dom.md b/app/2.0/docs/devguide/style-shadow-dom.md index ff191a1ede..8df03fafc9 100644 --- a/app/2.0/docs/devguide/style-shadow-dom.md +++ b/app/2.0/docs/devguide/style-shadow-dom.md @@ -512,6 +512,8 @@ class myElement extends Polymer.Element(){ } ``` +[See an example on Plunker](http://plnkr.co/edit/vWS9PIBTTbKHxRnJyT7T?p=preview) + ### Style directional text with the :dir() selector The `:dir()` CSS selector allows for styling text specific to its orientation diff --git a/app/3.0/docs/api/classes/Polymer.Debouncer.html b/app/3.0/docs/api/classes/Polymer.Debouncer.html deleted file mode 100644 index e922b276b2..0000000000 --- a/app/3.0/docs/api/classes/Polymer.Debouncer.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Debouncer" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Debouncer{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/classes/Polymer.FlattenedNodesObserver.html b/app/3.0/docs/api/classes/Polymer.FlattenedNodesObserver.html deleted file mode 100644 index 71ddbdb917..0000000000 --- a/app/3.0/docs/api/classes/Polymer.FlattenedNodesObserver.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.FlattenedNodesObserver" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.FlattenedNodesObserver{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.ArraySelector.html b/app/3.0/docs/api/elements/Polymer.ArraySelector.html deleted file mode 100644 index d02223dbcc..0000000000 --- a/app/3.0/docs/api/elements/Polymer.ArraySelector.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = " (Polymer.ArraySelector)" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - (Polymer.ArraySelector){% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.CustomStyle.html b/app/3.0/docs/api/elements/Polymer.CustomStyle.html deleted file mode 100644 index 7b9d82b100..0000000000 --- a/app/3.0/docs/api/elements/Polymer.CustomStyle.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = " (Polymer.CustomStyle)" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - (Polymer.CustomStyle){% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.DomBind.html b/app/3.0/docs/api/elements/Polymer.DomBind.html deleted file mode 100644 index 689ab58aee..0000000000 --- a/app/3.0/docs/api/elements/Polymer.DomBind.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = " (Polymer.DomBind)" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - (Polymer.DomBind){% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.DomIf.html b/app/3.0/docs/api/elements/Polymer.DomIf.html deleted file mode 100644 index ccee359162..0000000000 --- a/app/3.0/docs/api/elements/Polymer.DomIf.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = " (Polymer.DomIf)" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - (Polymer.DomIf){% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.DomModule.html b/app/3.0/docs/api/elements/Polymer.DomModule.html deleted file mode 100644 index 6b783bc658..0000000000 --- a/app/3.0/docs/api/elements/Polymer.DomModule.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = " (Polymer.DomModule)" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - (Polymer.DomModule){% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.DomRepeat.html b/app/3.0/docs/api/elements/Polymer.DomRepeat.html deleted file mode 100644 index 61a60dd668..0000000000 --- a/app/3.0/docs/api/elements/Polymer.DomRepeat.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = " (Polymer.DomRepeat)" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - (Polymer.DomRepeat){% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/Polymer.Element.html b/app/3.0/docs/api/elements/Polymer.Element.html deleted file mode 100644 index a469c09620..0000000000 --- a/app/3.0/docs/api/elements/Polymer.Element.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Element" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Element{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/elements/array-selector.html b/app/3.0/docs/api/elements/array-selector.html new file mode 100644 index 0000000000..68512eece8 --- /dev/null +++ b/app/3.0/docs/api/elements/array-selector.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "array-selector Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}array-selector – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/elements/custom-style.html b/app/3.0/docs/api/elements/custom-style.html new file mode 100644 index 0000000000..a77cadc138 --- /dev/null +++ b/app/3.0/docs/api/elements/custom-style.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "custom-style Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}custom-style – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/elements/dom-bind.html b/app/3.0/docs/api/elements/dom-bind.html new file mode 100644 index 0000000000..aaec1809a0 --- /dev/null +++ b/app/3.0/docs/api/elements/dom-bind.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "dom-bind Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}dom-bind – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/elements/dom-if.html b/app/3.0/docs/api/elements/dom-if.html new file mode 100644 index 0000000000..71adb1c7b9 --- /dev/null +++ b/app/3.0/docs/api/elements/dom-if.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "dom-if Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}dom-if – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/elements/dom-module.html b/app/3.0/docs/api/elements/dom-module.html new file mode 100644 index 0000000000..eb9b38c992 --- /dev/null +++ b/app/3.0/docs/api/elements/dom-module.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "dom-module Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}dom-module – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/elements/dom-repeat.html b/app/3.0/docs/api/elements/dom-repeat.html new file mode 100644 index 0000000000..1910540aa0 --- /dev/null +++ b/app/3.0/docs/api/elements/dom-repeat.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "dom-repeat Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}dom-repeat – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/index.html b/app/3.0/docs/api/index.html index c2c395bf85..abfc51c874 100644 --- a/app/3.0/docs/api/index.html +++ b/app/3.0/docs/api/index.html @@ -1,7 +1,559 @@ {% set markdown = "true" %} -{% set title = "Polymer" %} +{% set title = "Polymer API Docs" %} {% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer{% endblock %} +{% block title %} Polymer API Reference {% endblock %} {% block content %} - -{% endblock %} \ No newline at end of file + + +

+
+
+ + polymer-element.js + +
+ + +
+ + + +
+

elements/

+ + +
+
+ + array-selector.js + +
+ + +
+ + + +
+
+ + custom-style.js + +
+ + +
+ + + +
+
+ + dom-bind.js + +
+ + +
+ + + +
+
+ + dom-if.js + +
+ + +
+ + + +
+
+ + dom-module.js + +
+ + +
+ + + +
+
+ + dom-repeat.js + +
+ + +
+ +
+ + + + +
+

mixins/

+ + +
+
+ + dir-mixin.js + +
+ + +
+ + + +
+
+ + disable-upgrade-mixin.js + +
+ + +
+ + + +
+
+ + element-mixin.js + +
+ + +
+ + + +
+
+ + gesture-event-listeners.js + +
+ + +
+ + + +
+
+ + mutable-data.js + +
+ + +
+ + + +
+
+ + properties-changed.js + +
+ + +
+ + + +
+
+ + properties-mixin.js + +
+ + +
+ + + +
+
+ + property-accessors.js + +
+ + +
+ + + +
+
+ + property-effects.js + +
+ + +
+ + + +
+
+ + strict-binding-parser.js + +
+ + +
+ + + +
+
+ + template-stamp.js + +
+ + +
+ +
+ + + + +
+

utils/

+ + +
+
+ + array-splice.js + +
+ + +
+ + + +
+
+ + case-map.js + +
+ + +
+ + + +
+
+ + debounce.js + +
+ + +
+ + + +
+
+ + flattened-nodes-observer.js + +
+ + +
+ + + +
+
+ + flush.js + +
+ + +
+ + + +
+
+ + gestures.js + +
+ + +
+ + + +
+
+ + html-tag.js + +
+ + +
+ + + +
+
+ + import-href.js + +
+ + +
+ + + +
+
+ + mixin.js + +
+ + +
+ + + +
+
+ + path.js + +
+ + +
+ + + +
+
+ + render-status.js + +
+ + +
+ + + +
+
+ + resolve-url.js + +
+ + +
+ + + +
+
+ + settings.js + +
+ + +
+ + + +
+
+ + style-gather.js + +
+ + +
+ + + +
+
+ + templatize.js + +
+ + +
+ +
+ + + + +
+

legacy/

+ + +
+
+ + class.js + +
+ + +
+ + + +
+
+ + legacy-element-mixin.js + +
+ + +
+ + + +
+
+ + mutable-data-behavior.js + +
+ + +
+ + + +
+
+ + polymer-fn.js + +
+ + +
+ + + +
+
+ + polymer.dom.js + +
+ + +
+ + + +
+
+ + templatizer-behavior.js + +
+ + +
+ +
+ + +
+{% endblock %} diff --git a/app/3.0/docs/api/legacy/class.html b/app/3.0/docs/api/legacy/class.html new file mode 100644 index 0000000000..b2ea537554 --- /dev/null +++ b/app/3.0/docs/api/legacy/class.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "class Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}class – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/legacy/legacy-element-mixin.html b/app/3.0/docs/api/legacy/legacy-element-mixin.html new file mode 100644 index 0000000000..ae309e1e72 --- /dev/null +++ b/app/3.0/docs/api/legacy/legacy-element-mixin.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "legacy-element-mixin Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}legacy-element-mixin – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/legacy/mutable-data-behavior.html b/app/3.0/docs/api/legacy/mutable-data-behavior.html new file mode 100644 index 0000000000..52686274be --- /dev/null +++ b/app/3.0/docs/api/legacy/mutable-data-behavior.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "mutable-data-behavior Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}mutable-data-behavior – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/legacy/polymer-fn.html b/app/3.0/docs/api/legacy/polymer-fn.html new file mode 100644 index 0000000000..2880993733 --- /dev/null +++ b/app/3.0/docs/api/legacy/polymer-fn.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "polymer-fn Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}polymer-fn – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/legacy/polymer.dom.html b/app/3.0/docs/api/legacy/polymer.dom.html new file mode 100644 index 0000000000..077cbda348 --- /dev/null +++ b/app/3.0/docs/api/legacy/polymer.dom.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "polymer Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}polymer – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/legacy/templatizer-behavior.html b/app/3.0/docs/api/legacy/templatizer-behavior.html new file mode 100644 index 0000000000..4147523f2b --- /dev/null +++ b/app/3.0/docs/api/legacy/templatizer-behavior.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "templatizer-behavior Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}templatizer-behavior – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/Polymer.ArraySelectorMixin.html b/app/3.0/docs/api/mixins/Polymer.ArraySelectorMixin.html deleted file mode 100644 index 89d721ab56..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.ArraySelectorMixin.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.ArraySelectorMixin" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.ArraySelectorMixin{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.ElementMixin.html b/app/3.0/docs/api/mixins/Polymer.ElementMixin.html deleted file mode 100644 index c04d5a211a..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.ElementMixin.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.ElementMixin" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.ElementMixin{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.GestureEventListeners.html b/app/3.0/docs/api/mixins/Polymer.GestureEventListeners.html deleted file mode 100644 index 4139fc199c..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.GestureEventListeners.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.GestureEventListeners" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.GestureEventListeners{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.LegacyElementMixin.html b/app/3.0/docs/api/mixins/Polymer.LegacyElementMixin.html deleted file mode 100644 index 9c0d368041..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.LegacyElementMixin.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.LegacyElementMixin" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.LegacyElementMixin{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.MutableData.html b/app/3.0/docs/api/mixins/Polymer.MutableData.html deleted file mode 100644 index f8007dfb07..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.MutableData.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.MutableData" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.MutableData{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.OptionalMutableData.html b/app/3.0/docs/api/mixins/Polymer.OptionalMutableData.html deleted file mode 100644 index 29515c7795..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.OptionalMutableData.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.OptionalMutableData" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.OptionalMutableData{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.PropertyAccessors.html b/app/3.0/docs/api/mixins/Polymer.PropertyAccessors.html deleted file mode 100644 index 593f9fd573..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.PropertyAccessors.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.PropertyAccessors" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.PropertyAccessors{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.PropertyEffects.html b/app/3.0/docs/api/mixins/Polymer.PropertyEffects.html deleted file mode 100644 index fd1422eb94..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.PropertyEffects.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.PropertyEffects" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.PropertyEffects{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/Polymer.TemplateStamp.html b/app/3.0/docs/api/mixins/Polymer.TemplateStamp.html deleted file mode 100644 index d770504d40..0000000000 --- a/app/3.0/docs/api/mixins/Polymer.TemplateStamp.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.TemplateStamp" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.TemplateStamp{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/mixins/dir-mixin.html b/app/3.0/docs/api/mixins/dir-mixin.html new file mode 100644 index 0000000000..3a4696905d --- /dev/null +++ b/app/3.0/docs/api/mixins/dir-mixin.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "dir-mixin Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}dir-mixin – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/disable-upgrade-mixin.html b/app/3.0/docs/api/mixins/disable-upgrade-mixin.html new file mode 100644 index 0000000000..2487ab4540 --- /dev/null +++ b/app/3.0/docs/api/mixins/disable-upgrade-mixin.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "disable-upgrade-mixin Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}disable-upgrade-mixin – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/element-mixin.html b/app/3.0/docs/api/mixins/element-mixin.html new file mode 100644 index 0000000000..56ab8e1014 --- /dev/null +++ b/app/3.0/docs/api/mixins/element-mixin.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "element-mixin Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}element-mixin – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/gesture-event-listeners.html b/app/3.0/docs/api/mixins/gesture-event-listeners.html new file mode 100644 index 0000000000..d8d63d1bba --- /dev/null +++ b/app/3.0/docs/api/mixins/gesture-event-listeners.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "gesture-event-listeners Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}gesture-event-listeners – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/mutable-data.html b/app/3.0/docs/api/mixins/mutable-data.html new file mode 100644 index 0000000000..4d455621b6 --- /dev/null +++ b/app/3.0/docs/api/mixins/mutable-data.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "mutable-data Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}mutable-data – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/properties-changed.html b/app/3.0/docs/api/mixins/properties-changed.html new file mode 100644 index 0000000000..5a6580134a --- /dev/null +++ b/app/3.0/docs/api/mixins/properties-changed.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "properties-changed Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}properties-changed – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/properties-mixin.html b/app/3.0/docs/api/mixins/properties-mixin.html new file mode 100644 index 0000000000..64d9c77995 --- /dev/null +++ b/app/3.0/docs/api/mixins/properties-mixin.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "properties-mixin Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}properties-mixin – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/property-accessors.html b/app/3.0/docs/api/mixins/property-accessors.html new file mode 100644 index 0000000000..4569f059ab --- /dev/null +++ b/app/3.0/docs/api/mixins/property-accessors.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "property-accessors Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}property-accessors – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/property-effects.html b/app/3.0/docs/api/mixins/property-effects.html new file mode 100644 index 0000000000..5e232509c8 --- /dev/null +++ b/app/3.0/docs/api/mixins/property-effects.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "property-effects Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}property-effects – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/strict-binding-parser.html b/app/3.0/docs/api/mixins/strict-binding-parser.html new file mode 100644 index 0000000000..987d2964d6 --- /dev/null +++ b/app/3.0/docs/api/mixins/strict-binding-parser.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "strict-binding-parser Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}strict-binding-parser – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/mixins/template-stamp.html b/app/3.0/docs/api/mixins/template-stamp.html new file mode 100644 index 0000000000..9550f4fd4c --- /dev/null +++ b/app/3.0/docs/api/mixins/template-stamp.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "template-stamp Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}template-stamp – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/namespaces/Polymer.ArraySplice.html b/app/3.0/docs/api/namespaces/Polymer.ArraySplice.html deleted file mode 100644 index d2b666c1e9..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.ArraySplice.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.ArraySplice" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.ArraySplice{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Async.animationFrame.html b/app/3.0/docs/api/namespaces/Polymer.Async.animationFrame.html deleted file mode 100644 index 084a7fad74..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Async.animationFrame.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Async.animationFrame" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Async.animationFrame{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Async.html b/app/3.0/docs/api/namespaces/Polymer.Async.html deleted file mode 100644 index 358eb4cec7..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Async.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Async" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Async{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Async.idlePeriod.html b/app/3.0/docs/api/namespaces/Polymer.Async.idlePeriod.html deleted file mode 100644 index dffe61afbc..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Async.idlePeriod.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Async.idlePeriod" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Async.idlePeriod{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Async.microTask.html b/app/3.0/docs/api/namespaces/Polymer.Async.microTask.html deleted file mode 100644 index ef1d2c954d..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Async.microTask.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Async.microTask" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Async.microTask{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Async.timeOut.html b/app/3.0/docs/api/namespaces/Polymer.Async.timeOut.html deleted file mode 100644 index 1fa84f4119..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Async.timeOut.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Async.timeOut" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Async.timeOut{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.CaseMap.html b/app/3.0/docs/api/namespaces/Polymer.CaseMap.html deleted file mode 100644 index 25767f020d..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.CaseMap.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.CaseMap" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.CaseMap{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Gestures.html b/app/3.0/docs/api/namespaces/Polymer.Gestures.html deleted file mode 100644 index 2310ba00e3..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Gestures.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Gestures" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Gestures{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Path.html b/app/3.0/docs/api/namespaces/Polymer.Path.html deleted file mode 100644 index fe39adeb49..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Path.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Path" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Path{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.RenderStatus.html b/app/3.0/docs/api/namespaces/Polymer.RenderStatus.html deleted file mode 100644 index bbdbf0f1a1..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.RenderStatus.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.RenderStatus" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.RenderStatus{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.ResolveUrl.html b/app/3.0/docs/api/namespaces/Polymer.ResolveUrl.html deleted file mode 100644 index 891dc64423..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.ResolveUrl.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.ResolveUrl" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.ResolveUrl{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.StyleGather.html b/app/3.0/docs/api/namespaces/Polymer.StyleGather.html deleted file mode 100644 index 5a39cbba13..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.StyleGather.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.StyleGather" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.StyleGather{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.Templatize.html b/app/3.0/docs/api/namespaces/Polymer.Templatize.html deleted file mode 100644 index 6064153c5e..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.Templatize.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.Templatize" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.Templatize{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.dom.html b/app/3.0/docs/api/namespaces/Polymer.dom.html deleted file mode 100644 index 73371c65e6..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.dom.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.dom" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.dom{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.settings.html b/app/3.0/docs/api/namespaces/Polymer.settings.html deleted file mode 100644 index b7593ec3cc..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.settings.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.settings" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.settings{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/namespaces/Polymer.telemetry.html b/app/3.0/docs/api/namespaces/Polymer.telemetry.html deleted file mode 100644 index aed80911b4..0000000000 --- a/app/3.0/docs/api/namespaces/Polymer.telemetry.html +++ /dev/null @@ -1,7 +0,0 @@ -{% set markdown = "true" %} -{% set title = "Polymer.telemetry" %} -{% extends "templates/base-devguide.html" %} -{% block title %} API Reference - Polymer.telemetry{% endblock %} -{% block content %} - -{% endblock %} \ No newline at end of file diff --git a/app/3.0/docs/api/polymer-element.html b/app/3.0/docs/api/polymer-element.html new file mode 100644 index 0000000000..9701b91d55 --- /dev/null +++ b/app/3.0/docs/api/polymer-element.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "polymer-element Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}polymer-element – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/array-splice.html b/app/3.0/docs/api/utils/array-splice.html new file mode 100644 index 0000000000..49723e4b81 --- /dev/null +++ b/app/3.0/docs/api/utils/array-splice.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "array-splice Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}array-splice – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/case-map.html b/app/3.0/docs/api/utils/case-map.html new file mode 100644 index 0000000000..8b86e29f13 --- /dev/null +++ b/app/3.0/docs/api/utils/case-map.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "case-map Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}case-map – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/debounce.html b/app/3.0/docs/api/utils/debounce.html new file mode 100644 index 0000000000..0d43d33763 --- /dev/null +++ b/app/3.0/docs/api/utils/debounce.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "debounce Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}debounce – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/flattened-nodes-observer.html b/app/3.0/docs/api/utils/flattened-nodes-observer.html new file mode 100644 index 0000000000..e13b83697f --- /dev/null +++ b/app/3.0/docs/api/utils/flattened-nodes-observer.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "flattened-nodes-observer Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}flattened-nodes-observer – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/flush.html b/app/3.0/docs/api/utils/flush.html new file mode 100644 index 0000000000..f1e7af9495 --- /dev/null +++ b/app/3.0/docs/api/utils/flush.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "flush Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}flush – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/gestures.html b/app/3.0/docs/api/utils/gestures.html new file mode 100644 index 0000000000..3ddb12f5c0 --- /dev/null +++ b/app/3.0/docs/api/utils/gestures.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "gestures Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}gestures – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/html-tag.html b/app/3.0/docs/api/utils/html-tag.html new file mode 100644 index 0000000000..160d831fbd --- /dev/null +++ b/app/3.0/docs/api/utils/html-tag.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "html-tag Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}html-tag – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/import-href.html b/app/3.0/docs/api/utils/import-href.html new file mode 100644 index 0000000000..fdb9df800e --- /dev/null +++ b/app/3.0/docs/api/utils/import-href.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "import-href Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}import-href – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/mixin.html b/app/3.0/docs/api/utils/mixin.html new file mode 100644 index 0000000000..9c46815cd4 --- /dev/null +++ b/app/3.0/docs/api/utils/mixin.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "mixin Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}mixin – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/path.html b/app/3.0/docs/api/utils/path.html new file mode 100644 index 0000000000..aa9e827f8b --- /dev/null +++ b/app/3.0/docs/api/utils/path.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "path Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}path – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/render-status.html b/app/3.0/docs/api/utils/render-status.html new file mode 100644 index 0000000000..44a7e5c1cf --- /dev/null +++ b/app/3.0/docs/api/utils/render-status.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "render-status Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}render-status – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/resolve-url.html b/app/3.0/docs/api/utils/resolve-url.html new file mode 100644 index 0000000000..250aa12ad0 --- /dev/null +++ b/app/3.0/docs/api/utils/resolve-url.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "resolve-url Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}resolve-url – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/settings.html b/app/3.0/docs/api/utils/settings.html new file mode 100644 index 0000000000..8374931c7c --- /dev/null +++ b/app/3.0/docs/api/utils/settings.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "settings Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}settings – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/style-gather.html b/app/3.0/docs/api/utils/style-gather.html new file mode 100644 index 0000000000..4134baae97 --- /dev/null +++ b/app/3.0/docs/api/utils/style-gather.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "style-gather Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}style-gather – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/api/utils/templatize.html b/app/3.0/docs/api/utils/templatize.html new file mode 100644 index 0000000000..fcb44f03ef --- /dev/null +++ b/app/3.0/docs/api/utils/templatize.html @@ -0,0 +1,10 @@ +{% set markdown = "true" %} +{% set title = "templatize Module" %} +{% extends "templates/base-devguide.html" %} +{% block title %}templatize – API Reference{% endblock %} +{% block content %} + +{% endblock %} diff --git a/app/3.0/docs/devguide/custom-css-properties.md b/app/3.0/docs/devguide/custom-css-properties.md index 765c56c9d2..2e9ec47335 100644 --- a/app/3.0/docs/devguide/custom-css-properties.md +++ b/app/3.0/docs/devguide/custom-css-properties.md @@ -4,355 +4,437 @@ title: Use custom properties -The author of a Polymer element can provide custom CSS properties that you can use to style the appearance of the element in your application. +Custom CSS properties allow you to define a CSS variable and use it in your styles. -Custom properties allow CSS authors to define cascading CSS variables, which are accepted by all CSS properties. +## Basic syntax for custom CSS properties -CSS variables can be used outside the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. A CSS author assigns values to a custom property, and then uses the `var()` function to use these values elsewhere in the stylesheet. +To set the value of a custom CSS property: -This makes editing your CSS much easier and less prone to author error. +```css +element { + --custom-color: blue; +} +``` -For example, the [`` element](https://www.webcomponents.org/element/PolymerElements/paper-checkbox) provides custom properties for styling the colors, spacing and size of the checkbox and its label. +To use the custom CSS property to create a style: -As a developer, you can use these properties to style `` elements in your applications. +```css +element { + color: var(--custom-color); +} +``` -When you create your own custom elements, you can use custom properties to build an interface for the users of your element so they can style it. +You can use custom CSS properties outside of the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. For example: -### Use a custom properties API to style an element +```html + + + + + +

Demonstrating basic use of custom properties

+ + +``` + +[See it on Plunker](http://plnkr.co/edit/AjZm3o?p=preview) -To use the interface of custom properties provided by an element author, look at the element's API documentation. +In the code sample above, the visual theme can be changed by editing the values of the custom properties. This makes it easier to create consistent themes, and your code will be less prone to error. -For a good example, visit the [`` API documentation](https://www.webcomponents.org/element/PolymerElements/paper-checkbox/paper-checkbox) +## Use the custom CSS properties provided by a Polymer element -This code sample inserts a `` element with its default styling: +The author of a Polymer element can provide custom CSS properties that you can use to style the appearance of the element in your application. This way, you don't need to know how the element's code works. -[See it on Plunker](http://plnkr.co/edit/if8IardvWBwZ2uMZIlgI?p=preview) +For example, suppose someone has authored two elements, `` and ``, which can be used together to create layouts in columns or rows, like so: ```html - - - - + + flex item 1 + flex item 2 + flex item 3 + +``` + +In the documentation for `flex-container`, you notice that the author has provided a custom CSS property, `--flex-direction`, to control whether the `flex-items` are laid out in a column or a row. You can assign your own value to `--flex-direction` in your app: -Check me +index.html { .caption} + +```html + + + + + + + + + + + + flex item 1 + + flex item n + + + ``` -Notice that: +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) -* The checkbox label defaults to Times New Roman. This is true of any web page with no style info. -* The checkbox receives default colors from the paper-element theme. +**Custom CSS properties inherit.** In the code sample above, the value of `--flex-direction` is set in the `html` CSS rule. Since `flex-container` is a child of `html`, `flex-container` inherits this value. +{.alert} -The style properties of the `` element are configurable with the custom CSS properties that the element author has provided for us. +To find out about the custom CSS properties an element provides, see the element's documentation. -To use a custom property of a custom element, create a style rule using this syntax: +For examples of Polymer elements that provide extensive styling options with custom CSS properties, see the [API documentation for the `paper-ui-elements`](https://www.webcomponents.org/collection/PolymerElements/paper-ui-elements). + +## Provide custom CSS properties to users of your elements + +When you create Polymer elements, you can use custom CSS properties in your style rules. Users of your elements can then set values for the custom CSS properties, and control the appearance of your elements without needing to know how your code works. + +For example, suppose you are creating two elements, `` and ``, which can be used together to create layouts in columns or rows: ```html -paper-checkbox { - --paper-checkbox-checked-color: red; + + flex item 1 + flex item 2 + flex item 3 + +``` + +You can use a custom CSS property to control the flex direction of ``: + +flex-container.js (your code) { .caption } + +```js +/* ... */ +class FlexContainer extends PolymerElement { + static get template () { + return html` + + + `; + } } +/* ... */ ``` -[See it on Plunker](http://plnkr.co/edit/u41sHRHAWtYiYyjWnFlP?p=preview) +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) -The paper elements provide a consistent way to configure styles across elements when using the paper element set, with variables. +Users can then assign their own value to `--flex-direction` like so: -We can use variables to configure the custom CSS properties in ``: +index.html (user's code) { .caption } ```html - +... ``` -## Create custom properties +If you provide documentation for the custom properties your element provides, users don't need to know any implementation details. See [Documenting your elements](/{{{polymer_version_dir}}}/docs/tools/documentation) for more information, or take a look at the [documentation for the Polymer `paper-ui-elements`](https://www.webcomponents.org/collection/PolymerElements/paper-ui-elements) for examples. -Rather than exposing the details of an element's internal implementation for -theming, an element author defines one or more custom CSS -properties as part of the element's API. +### Create default values for your CSS properties -These custom properties can be defined similarly to other standard CSS properties -and will inherit from the point of definition down the composed DOM tree, -similar to the effect of `color` and `font-family`. +You may want to provide default values for the CSS properties you use in your styles. -In the simple example below, the author of `` identified the need for -users of the toolbar to be able to change the color of the toolbar title. The -author exposed a custom property called `--my-toolbar-title-color` which is -assigned to the `color` property of the selector for the title element. Users -of the toolbar may define this variable in a CSS rule anywhere up the tree, and -the value of the property will inherit down to the toolbar where it is used if -defined, similar to other standard inheriting CSS properties. +To set a default value for a CSS property, use the following syntax: -Example: { .caption } +```css +div { + background-color: var(--theme-background, #e3f2fd); +} +``` -```html - - - - +To use a default value that is itself a custom property, use the following syntax: + +```css +div { + background-color: var(--theme-background, var(--default-light-blue)); +} ``` -Example usage of ``: { .caption } +## Inheritance and global styles + +Custom CSS properties inherit down the DOM hierarchy. In the code sample below, `` will inherit the custom properties defined for `div`, but not the custom properties defined for `span`. ```html - - - - + + + + + + + + + + + +
+ + flex item 1 + flex item 2 + flex item 3 + +
+ +

hello i am in a span

+ + + ``` -The `--my-toolbar-title-color` property only affects the color of the title -element encapsulated in ``'s internal implementation. In the -future the `` author can rename the `title` class or -restructure the internal details of `` without changing the custom -property exposed to users. +[See it on Plunker](http://plnkr.co/edit/mHpf7L?p=preview) -You can also include a default value in the `var()` function, to use in case the user -doesn't set the custom property: +You can use inheritance to define global custom CSS properties. In the code sample below, all nodes inherit the custom CSS properties defined for the top-level `html` element: -```css -color: var(--my-toolbar-title-color, blue); +index.html { .caption} + +```html +... + + + +... +
+ + flex item 1 + flex item 2 + flex item 3 + +
+ +

hello i am in a span

+ +... ``` -To include a default value that is a custom property, use this syntax: +[See it on Plunker](http://plnkr.co/edit/7rbXJY?p=preview) -```css -color: var(--my-color, var(--my-default-color)) -``` +Child elements that inherit global CSS properties can override them. For example, in the code sample above, `` inherited its custom CSS properties and fonts from the document-level styles for `html`. `` can override these properties: -Thus, custom CSS properties are a powerful way for element authors to -expose a theming API to their users in a way that naturally fits right alongside -normal CSS styling. +flex-item.js {.caption} -### Use custom CSS mixins +```js +static get template () { + return html` + + `; +} +``` -It may be tedious (or impossible) for an element author to predict every -CSS property that may be important for theming, let alone expose every -property individually. +[See it on Plunker](http://plnkr.co/edit/vlO7GV?p=preview) -CSS mixins are a proposal to fill this gap in functionality. To use CSS mixins, import the CSS mixins polyfill: +## Use custom CSS mixins -```html - - -``` +Using CSS mixins, you can define a set of CSS properties as a single custom property. -For backward compatibility, the `polymer.html` import includes the CSS mixins polyfill. No extra import is required when defining hybrid elements. +This is similar to defining a custom property with `var()`, but the value of the property is an object that defines one or more rules: -Using CSS mixins, an element author can define a set of CSS properties as a single custom property and then allow all properties in the set to be applied to a specific CSS rule -in an element's shadow DOM. The extension enables this with a mixin capability -that is analogous to `var`, but which allows an entire set of properties -to be mixed in. +```css +selector { + --mixin-name: { + /* rules */ + }; +} +``` Use `@apply` to apply a mixin: -
@apply --mixin-name;
+```css +selector { + @apply --mixin-name; +} +``` -Defining a mixin is just like defining a custom property, but the -value is an object that defines one or more rules: +Suppose we have two custom elements, `` and ``, which can be used together to create row or column layouts. -
selector {
-  --mixin-name: {
-    /* rules */
-  };
-}
+The author of the two elements uses a CSS mixin to apply theming information to both elements: -Example: { .caption } +flex-container.js {.caption} -```html - - - ... - + ... + `; +} ``` -Example usage of `my-toolbar`: { .caption } +flex-item.js { .caption} -```html - - - - + ... + `; +} ``` -## Use CSS inheritance +[See it on Plunker](http://plnkr.co/edit/glgUKv?p=preview) + +Users of `flex-item` can set values for the properties in the mixin: -If an element doesn't override styling information, that element inherits styles from its parent: +index.html {.caption} ```html - + + - - -

Check me

- ``` -## Create global styles - -Create global styles by styling the the html element of your document: +Note that any element using the `@apply` syntax must import the `@apply` polyfill: -```html - - - - +```js +// import CSS mixins polyfill +import '@webcomponents/shadycss/entrypoints/apply-shim.js'; ``` -Note that the font family is inherited, but the text color is not. This is because `` overrides the text color. +[See it in Plunker](http://plnkr.co/edit/glgUKv?p=preview) ### Custom property API for Polymer elements {#style-api} Polymer's custom property shim evaluates and applies custom property values once -at element creation time. In order to have an element (and its subtree) re- +at element creation time. In order to have an element (and its subtree) re- evaluate custom property values due to dynamic changes such as application of -CSS classes, call the [`updateStyles`](/2.0/docs/api/elements/Polymer.Element#method-updateStyles) +CSS classes, call the [`updateStyles`](/3.0/docs/api/elements/Polymer.Element#method-updateStyles) method on the element. To update _all_ elements on the page, you can also call `Polymer.updateStyles`. `updateStyles` can take a object with property/value pairs to update the current values of custom properties. -Example: { .caption } +Example { .caption } -```html - - - - -``` - -```html -this.updateStyles({ - '--some-custom-style': 'green', - '--another-custom-style': 'blue' -}); + } + static template get (){ + return html` + + My awesome app + + `; + } +} +customElements.define('x-custom', XCustom); ``` Occasionally an element needs to get the value of a custom property at runtime. This is handled @@ -367,15 +449,14 @@ if (ShadyCSS) { ``` Elements using the legacy API can use the -[`getComputedStyleValue`](/2.0/docs/api/mixins/Polymer.LegacyElementMixin#method-getComputedStyleValue) +[`getComputedStyleValue`](/3.0/docs/api/mixins/Polymer.LegacyElementMixin#method-getComputedStyleValue) instance method instead of testing for `ShadyCSS`. - ### Custom properties shim limitations Cross-platform support for custom properties is provided in Polymer by a JavaScript library that **approximates** the capabilities of the CSS Variables -specification *for the specific use case of theming custom elements*, while +specification *for the specific use case of theming custom elements*, while also extending it to add the capability to mixin property sets to rules as described above. For performance reasons, Polymer **does not attempt to replicate all aspects of native custom properties.** @@ -396,7 +477,7 @@ styles. For example, given this markup inside an element: -HTML: { .caption } +HTML { .caption } ```html
@@ -404,7 +485,7 @@ HTML: { .caption }
``` -CSS: { .caption } +CSS { .caption } ```css /* applies */ @@ -444,42 +525,37 @@ have the desired effect, since the dynamism is related to *application* of a cus Unlike normal CSS inheritance which flows from parent to child, custom properties in Polymer's shim can only change when inherited by a custom element from rules that set properties in scope(s) above it, or in a `:host` rule for -that scope. **Within a given element's local DOM scope, a custom property can -only have a single value.** Calculating property changes within a scope would be +that scope. **Within a given element's local DOM scope, a custom property can +only have a single value.** Calculating property changes within a scope would be prohibitively expensive for the shim and is not required to achieve cross-scope styling for custom elements, which is the primary goal of the shim. -```html - - - - + .container { + /* Setting the custom property here will not change */ + /* the value of the property for other elements in */ + /* this scope. */ + --custom-color: blue; + } + .child { + /* This will be always be red. */ + color: var(--custom-color); + } + +
+
I will be red
+
+ `; + } + customElements.define('my-element', MyElement); +} ``` #### Styling distributed elements not supported diff --git a/app/3.0/docs/devguide/custom-elements.md b/app/3.0/docs/devguide/custom-elements.md index 341a48b751..6d02ee7354 100644 --- a/app/3.0/docs/devguide/custom-elements.md +++ b/app/3.0/docs/devguide/custom-elements.md @@ -4,10 +4,6 @@ title: Custom element concepts -
-{% include 'outdated.html' %} -
- Custom elements provide a component model for the web. The custom elements specification provides: * A mechanism for associating a class with a custom element name. @@ -16,45 +12,37 @@ Custom elements provide a component model for the web. The custom elements speci * A callback invoked whenever one of a specified set of attributes changes on the instance. Put together, these features let you build an element with its own public API that reacts to state -changes. +changes. Polymer provides a set of features on top of the basic custom element specification. This document provides an overview of custom elements as they relate to Polymer. For a more detailed overview of custom elements, see: [Custom Elements v1: Reusable Web -Components](https://developers.google.com/web/fundamentals/getting-started/primers/customelements) +Components](https://developers.google.com/web/fundamentals/web-components/customelements) on Web Fundamentals. -To define a custom element, you create an ES6 class and associate it with the custom element name. +To define a custom element, you create an ES6 class and associate it with the custom element name. For the full set of Polymer features, extend the `PolymerElement` class: -``` -// Create a class that extends HTMLElement (directly or indirectly) -class MyElement extends HTMLElement { … }; +```js +import {PolymerElement} from '@polymer/polymer/polymer-element.js'; -// Associate the new class with an element name -window.customElements.define('my-element', MyElement); -``` + export class MyPolymerElement extends PolymerElement { + ... + } + customElements.define('my-polymer-element', MyPolymerElement); +``` -You can use a custom element just like you'd use a standard element: +Exporting the custom element class is optional, but recommended. +Import the element into an HTML file using ` -``` - Polymer adds a set of features to the basic custom element: * Instance methods to handle common tasks. * Automation for handling properties and attributes, such as setting a property based on the corresponding attribute. -* Creating shadow DOM trees for element instances based on a supplied `