Skip to content

Commit

Permalink
Fix typos in PRIMER.md
Browse files Browse the repository at this point in the history
  • Loading branch information
tomalec committed Aug 4, 2015
1 parent eafa3e5 commit cf793f4
Showing 1 changed file with 11 additions and 11 deletions.
22 changes: 11 additions & 11 deletions PRIMER.md
Original file line number Diff line number Diff line change
Expand Up @@ -764,7 +764,7 @@ Example:
<a name="gesture-events"></a>
## Gesture events

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.
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.

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`.

Expand Down Expand Up @@ -1022,7 +1022,7 @@ Polymer({
<a name="array-observation"></a>
### Array observation

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).
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).

```js
Polymer({
Expand Down Expand Up @@ -1290,7 +1290,7 @@ Example 5: Error / non-sensical state

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.

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 `::`.
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 `::`.

Example:

Expand Down Expand Up @@ -1459,7 +1459,7 @@ Polymer provides an alternate binding annotation syntax to make it explicit when
</template>
```

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`.
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`.

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.

Expand Down Expand Up @@ -1532,7 +1532,7 @@ In specific cases, it may be useful to keep an HTML attribute value in sync with
```

<a name="attribute-serialization'></a>
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.
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.

<a name="computed-properties"></a>
## Computed properties
Expand Down Expand Up @@ -1580,7 +1580,7 @@ Computed properties are implicitly `readOnly`, and cannot be manually set.
</dom-module>
```

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.
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.

<a name="annotated-computed"></a>
## Annotated computed properties
Expand Down Expand Up @@ -1694,7 +1694,7 @@ Generally, read-only properties should also be set to `notify: true` such that t

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.

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.
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.

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:

Expand Down Expand Up @@ -1885,7 +1885,7 @@ Example:
<a name="x-styling-limitations"></a>
### Custom Properties Shim - Limitations and API details

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.
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.

Below are current limitations of this system. Improvements to performance and dynamism will continue to be explored.

Expand Down Expand Up @@ -1938,7 +1938,7 @@ Below are current limitations of this system. Improvements to performance and d
--title-background: yellow;
}
```
* 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.
* 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.

```html
<dom-module>
Expand Down Expand Up @@ -2241,7 +2241,7 @@ Example:
</dom-module>
```

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.
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.

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.

Expand Down Expand Up @@ -2291,6 +2291,6 @@ Higher layers depend on lower layers, and elements requiring lower layers will a

* polymer-micro.html: [Polymer micro features](#polymer-micro) (bare-minum Custom Element sugaring)
* polymer-mini.html: [Polymer mini features](#polymer-mini) (template stamped into "local DOM" and tree lifecycle)
* 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)
* 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)

This layering is subject to change in the future and the number of layers may be reduced.

0 comments on commit cf793f4

Please sign in to comment.