You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cf793f4
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: PRIMER.md
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -764,7 +764,7 @@ Example:
764
764
<aname="gesture-events"></a>
765
765
## Gesture events
766
766
767
-
Polymer will generate and fire a custom "gesture" event for certain user interactions automatically when a declarative listener is added for the event type. These events will fire consistenly on both touch and mouse environments, and so it is advised to listen for these events rather than their mouse- or touch-specific event counterparts for interoperability with both touch and desktop/mouse environments. For example, `tap` should be used instead of `click` for the most reliable cross-platform results.
767
+
Polymer will generate and fire a custom "gesture" event for certain user interactions automatically when a declarative listener is added for the event type. These events will fire consistently on both touch and mouse environments, and so it is advised to listen for these events rather than their mouse- or touch-specific event counterparts for interoperability with both touch and desktop/mouse environments. For example, `tap` should be used instead of `click` for the most reliable cross-platform results.
768
768
769
769
For convenience, calling `preventDefault` on gesture events will prevent the native event that generated that gesture. For example, calling `preventDefault` on a `tap` event will also call `preventDefault` on the `click` event that generated the `tap`.
770
770
@@ -1022,7 +1022,7 @@ Polymer({
1022
1022
<aname="array-observation"></a>
1023
1023
### Array observation
1024
1024
1025
-
Finally, mutations to arrays (e.g. changes resulting from calls to `push`, `pop`, `shift`, `unshift`, and `splice`, generally referred to as "splices") may be observed via the `observers` array by giving a path to an array followd by `.splices` as an argument to the observer function. The value received by the observer for the `splices` path of an array will be a change record containing `indexSplices` and `keySplices` arrays listing the set of changes that occurred to the array, either in terms of array indicies or "keys" used by Polymer for identifying array elements. Each `indexSplices` record contains a start `index`, array of `removed` items, and `addedCount` of items inserted. Each `keySplices` record contains an array of `added` and `removed` keys).
1025
+
Finally, mutations to arrays (e.g. changes resulting from calls to `push`, `pop`, `shift`, `unshift`, and `splice`, generally referred to as "splices") may be observed via the `observers` array by giving a path to an array followed by `.splices` as an argument to the observer function. The value received by the observer for the `splices` path of an array will be a change record containing `indexSplices` and `keySplices` arrays listing the set of changes that occurred to the array, either in terms of array indices or "keys" used by Polymer for identifying array elements. Each `indexSplices` record contains a start `index`, array of `removed` items, and `addedCount` of items inserted. Each `keySplices` record contains an array of `added` and `removed` keys).
1026
1026
1027
1027
```js
1028
1028
Polymer({
@@ -1290,7 +1290,7 @@ Example 5: Error / non-sensical state
1290
1290
1291
1291
As mentioned above, Polymer uses an event naming convention to achieve two-way binding. The act of two-way binding to a property using `target-prop={{hostProp}}` syntax results in Polymer adding a `<target-prop>-changed` event listener to the element by default. All properties of a Polymer element with `notify: true` send events using this convention to notify of changes.
1292
1292
1293
-
In order to two-way bind to native elements or non-Polymer elements that do not follow this event naming convention when notifying changes, you may specify a custom event name in the curley braces, delimited with `::`.
1293
+
In order to two-way bind to native elements or non-Polymer elements that do not follow this event naming convention when notifying changes, you may specify a custom event name in the curly braces, delimited with `::`.
1294
1294
1295
1295
Example:
1296
1296
@@ -1459,7 +1459,7 @@ Polymer provides an alternate binding annotation syntax to make it explicit when
1459
1459
</template>
1460
1460
```
1461
1461
1462
-
Values will be serialized according to type: Arrays/Objects will be `JSON.stringify`'ed, booleans will result in a non-valued attribute to be either set or removed, and `Dates` and all primitive types will be serialized using the value returned from `toString`.
1462
+
Values will be serialized according to type: Arrays/Objects will be `JSON.stringify`'ed, Booleans will result in a non-valued attribute to be either set or removed, and `Dates` and all primitive types will be serialized using the value returned from `toString`.
1463
1463
1464
1464
Again, as values must be serialized to strings when binding to attributes, it is always more performant to use property binding for pure data propagation.
1465
1465
@@ -1532,7 +1532,7 @@ In specific cases, it may be useful to keep an HTML attribute value in sync with
1532
1532
```
1533
1533
1534
1534
<a name="attribute-serialization'></a>
1535
-
Values will be serialized according to type; by default Arrays/Objects will be `JSON.stringify`'ed, booleans will result in a non-valued attribute to be either set or removed, and `Dates` and all primitive types will be serialized using the value returned from `toString`. The `serialize` method may be overridden to supply custom object serialization.
1535
+
Values will be serialized according to type; by default Arrays/Objects will be `JSON.stringify`'ed, Booleans will result in a non-valued attribute to be either set or removed, and `Dates` and all primitive types will be serialized using the value returned from `toString`. The `serialize` method may be overridden to supply custom object serialization.
1536
1536
1537
1537
<aname="computed-properties"></a>
1538
1538
## Computed properties
@@ -1580,7 +1580,7 @@ Computed properties are implicitly `readOnly`, and cannot be manually set.
1580
1580
</dom-module>
1581
1581
```
1582
1582
1583
-
Note that arguments to computing functions may be simple properties on the element, as well as all of the arguments types supported by `observers`, including [paths](#path-observation), [paths with wildcards](#deep-observation), and [paths to array splices](#array-observation). The arguments received in the comuting function will match those described in the sections referenced above.
1583
+
Note that arguments to computing functions may be simple properties on the element, as well as all of the arguments types supported by `observers`, including [paths](#path-observation), [paths with wildcards](#deep-observation), and [paths to array splices](#array-observation). The arguments received in the computing function will match those described in the sections referenced above.
1584
1584
1585
1585
<aname="annotated-computed"></a>
1586
1586
## Annotated computed properties
@@ -1694,7 +1694,7 @@ Generally, read-only properties should also be set to `notify: true` such that t
1694
1694
1695
1695
Shadow DOM (and its approximation via Shady DOM) bring much needed benefits of scoping and style encapsulation to web development, making it safer and easier to reason about the effects of CSS on parts of your application. Styles do not leak into the local DOM from above, and styles do not leak from one local DOM into the local DOM of other elements inside.
1696
1696
1697
-
This is great for *protecting* scopes from unwanted style leakage. But what about when you intentionally want to *customize* the style of a custom element's local DOM, as the user of an element? This often comes up under the umbrella of "theming". For example a "custom-checkbox" element that may interally use a `.checked` class can protect itself from being affected by CSS from other components that may also happen to use a `.checked` class. However, as the user of the checkbox you may wish to intentionally change the color of the check to match your product's branding, for example. The "protection" that Shadow DOM provides at the same time introduces a practical barrier to "theming" use cases.
1697
+
This is great for *protecting* scopes from unwanted style leakage. But what about when you intentionally want to *customize* the style of a custom element's local DOM, as the user of an element? This often comes up under the umbrella of "theming". For example a "custom-checkbox" element that may internally use a `.checked` class can protect itself from being affected by CSS from other components that may also happen to use a `.checked` class. However, as the user of the checkbox you may wish to intentionally change the color of the check to match your product's branding, for example. The "protection" that Shadow DOM provides at the same time introduces a practical barrier to "theming" use cases.
1698
1698
1699
1699
One solution the Shadow DOM spec authors provided to address the theming problem are the `/deep/` and `::shadow` combinators, which allow writing rules that pierce through the Shadow DOM encapsulation boundary. Although Polymer 0.5 promoted this mechanism for theming, it was ultimately unsatisfying for several reasons:
1700
1700
@@ -1885,7 +1885,7 @@ Example:
1885
1885
<aname="x-styling-limitations"></a>
1886
1886
### Custom Properties Shim - Limitations and API details
1887
1887
1888
-
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 also extending it to add the capability to mixin property sets to rules as described above. **It is important to note that this is not a full polyfill**, as doing so would be prohibitively expensive; rather this is a shim that is inspired by that specification and trades off aspects of the full dynamism possible in CSS with practicality and performance.
1888
+
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 also extending it to add the capability to mixin property sets to rules as described above. **It is important to note that this is not a full polyfill**, as doing so would be prohibitively expensive; rather this is a shim that is inspired by that specification and trades off aspects of the full dynamism possible in CSS with practicality and performance.
1889
1889
1890
1890
Below are current limitations of this system. Improvements to performance and dynamism will continue to be explored.
1891
1891
@@ -1938,7 +1938,7 @@ Below are current limitations of this system. Improvements to performance and d
1938
1938
--title-background: yellow;
1939
1939
}
1940
1940
```
1941
-
* 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 prohibitvely expensive for the shim and are not required to achieve cross-scope styling for custom elements, which is the primary goal of the shim.
1941
+
* 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 prohibitively expensive for the shim and are not required to achieve cross-scope styling for custom elements, which is the primary goal of the shim.
1942
1942
1943
1943
```html
1944
1944
<dom-module>
@@ -2241,7 +2241,7 @@ Example:
2241
2241
</dom-module>
2242
2242
```
2243
2243
2244
-
Note, since it is generally much faster to hide/show elements rather than create/destroy them, conditional templates are only useful to save initial creation cost when the elements being stamped are relatively heavyweight and the conditional may rarely (or never) be true in given useages. Otherwise, liberal use of conditional templates can actually *add* significant runtime performance overhead.
2244
+
Note, since it is generally much faster to hide/show elements rather than create/destroy them, conditional templates are only useful to save initial creation cost when the elements being stamped are relatively heavyweight and the conditional may rarely (or never) be true in given usages. Otherwise, liberal use of conditional templates can actually *add* significant runtime performance overhead.
2245
2245
2246
2246
Consider an app with 4 screens, plus an optional admin screen. If most users will use all 4 screens during normal use of the app, it is generally better to incur the cost of stamping those elements once at startup (where some app initialization time is expected) and simply hide/show the screens as the user navigates through the app, rather than re-create and destroy all the elements of each screen as the user navigates. Using a conditional template here may be a poor choice, since although it may save time at startup by stamping only the first screen, that saved time gets shifted to runtime latency for each user interaction, since the time to show the second screen will be *slower* as it must create the second screen from scratch rather than simply showing that screen. Hiding/showing elements is as simple as attribute-binding to the `hidden` attribute (e.g. `<div hidden$="{{!shouldShow}}">`), and does not require conditional templating at all.
2247
2247
@@ -2291,6 +2291,6 @@ Higher layers depend on lower layers, and elements requiring lower layers will a
2291
2291
2292
2292
* polymer-micro.html: [Polymer micro features](#polymer-micro) (bare-minum Custom Element sugaring)
2293
2293
* polymer-mini.html: [Polymer mini features](#polymer-mini) (template stamped into "local DOM" and tree lifecycle)
2294
-
* polymer.html: [Polymer standard features](#polymer-standard) (all other features: declarative data binding and event handlers, property nofication, computed properties, and the set of helper custom elements provided with Polymer)
2294
+
* polymer.html: [Polymer standard features](#polymer-standard) (all other features: declarative data binding and event handlers, property notification, computed properties, and the set of helper custom elements provided with Polymer)
2295
2295
2296
2296
This layering is subject to change in the future and the number of layers may be reduced.
0 commit comments