Skip to content

Commit 3184046

Browse files
author
Arthur Evans
authored
Merge pull request Polymer#2 from Polymer/up-to-date
Up to date
2 parents 94913b8 + 1d6c2f8 commit 3184046

File tree

13 files changed

+251
-176
lines changed

13 files changed

+251
-176
lines changed

‎app/2.0/docs/devguide/observers.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -400,6 +400,20 @@ class XCustom extends Polymer.Element {
400400
customElements.define(XCustom.is, XCustom);
401401
```
402402
403+
### Observe the length of an array
404+
405+
To create an observer on the length of an array, specify a path to an array followed by `.length` in your `observers` array:
406+
407+
``` js
408+
static get observers() {
409+
return [
410+
'usersAddedOrRemoved(users.length)'
411+
]
412+
}
413+
```
414+
415+
Your length observer method should accept a single argument (the new array length).
416+
403417
### Observe all changes related to a path {#deep-observation}
404418
405419
To call an observer when any (deep) sub-property of an
@@ -414,7 +428,7 @@ observer is a change record object with the following properties:
414428
* `base`. The object matching the non-wildcard portion of the path.
415429
416430
For array mutations, `path` is the path to the array that changed,
417-
followed by `.splices`. And the `value` field includes the `indexSplices`
431+
followed by `.splices`. The `value` field includes the `indexSplices`
418432
property described in [Observe array mutations](#array-observation).
419433
420434
Example: { .caption }
@@ -460,6 +474,8 @@ Example: { .caption }
460474
</dom-module>
461475
```
462476
477+
**Array mutations may also raise a change record for the length of the array.**
478+
If an array mutation also caused the length of the array to change, a wildcard observer on an array path raises a separate change record for the array length. The `path` field of the length change record is the path to the array that changed, followed by `.length`. The `value` field is the new array length. { .alert .alert-info }
463479
464480
### Identify all dependencies {#dependencies}
465481

‎app/2.0/docs/polyfills.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ There are a couple of other related polyfill files that you may need:
2828
on browsers that support native custom elements. This is useful in static serving environments
2929
where you need to serve a single app version to all browsers. The adapter is discussed in more
3030
detail in [ES6](es6) and in [Build for production](/{{{polymer_version_dir}}}/docs/apps/build-for-production).
31+
Important note: the es5 adapter must come _before_ the webcomponents polyfills, if any.
3132
* `apply-shim.html`. A polyfill for CSS mixins. Unlike the other polyfills, it should be included
3233
by any component that defines or applies CSS mixins. For details, see
3334
[Use custom CSS mixins](/{{{polymer_version_dir}}}/docs/devguide/custom-css-properties#use-custom-css-mixins).
@@ -79,7 +80,7 @@ The following table lists the JavaScript snippets and query parameters for each
7980
JavaScript:
8081

8182
```js
82-
window.customElements && window.customElements.forcePolyfill = true;
83+
if (window.customElements) window.customElements.forcePolyfill = true;
8384
```
8485

8586
Query parameter:

‎app/2.0/docs/upgrade.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1133,7 +1133,7 @@ Before {.caption}
11331133
<template is="dom-bind">
11341134
<ul>
11351135
<template is="dom-repeat" items="{{people}}">
1136-
<li>{{item.name}}
1136+
<li>{{item.name}}</li>
11371137
</template>
11381138
</ul>
11391139
</template>
@@ -1157,7 +1157,7 @@ After {.caption}
11571157
<ul>
11581158
<!-- inner template doesn't need to be wrapped -->
11591159
<template is="dom-repeat" items="{{people}}">
1160-
<li>{{item.name}}
1160+
<li>{{item.name}}</li>
11611161
</template>
11621162
</ul>
11631163
</template>

‎app/3.0/docs/apps/service-worker.md

Lines changed: 119 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -2,105 +2,165 @@
22
title: Offline caching with Service Worker Precache
33
---
44

5-
<div>
6-
{% include 'outdated.html' %}
7-
</div>
5+
<!-- toc -->
86

9-
To provide a better experience in offline and spotty network situations, App
10-
Toolbox uses a service worker to provide offline caching of critical resources. A
11-
service worker is a script associated with a specific web site that acts as a
7+
A service worker is a script associated with a specific web site that acts as a
128
client-side proxy for network requests. The service worker can intercept network
139
requests, access the browser's cache, and serve requests out of the cache
1410
instead of accessing the network.
1511

16-
The first time someone opens the site, the browser installs the site's service
17-
worker, and the service worker ensures that the site's critical resources are
18-
cached. On subsequent visits, the service worker can load resources directly
19-
from the cache. If the user is completely offline, the service worker can still
20-
load the site, and display cached data or an offline message, as appropriate.
12+
A service worker can improve your app's performance and allow it to work
13+
offline.
2114

22-
Service worker works well with an _app shell_ strategy, where the app's main UI
23-
views and logic (the app shell) are cached so that they can be served from the
24-
cache.
15+
The first time someone opens your site, the browser installs the site's service
16+
worker, and the service worker caches your app's critical resources. On
17+
subsequent visits, the service worker can load resources directly from the
18+
cache. If the user is completely offline, the service worker can still load the
19+
site, and display cached data or an offline message, as appropriate.
2520

2621
The Polymer Starter Kit template uses the Service Worker Precache (`sw-precache`) module for offline
2722
support. This module takes a list of files to cache and generates a service
2823
worker at build time, so you don't need to write your own service worker code.
24+
Service worker works well with an _app shell_ strategy, where the app's main
25+
views and logic (the app shell) are cached so that they can be served without
26+
accessing the network.
2927

30-
For background, gotchas and debugging tips on service workers, see [Introduction to Service
31-
Worker](https://developers.google.com/web/fundamentals/primers/service-worker/) on Web Fundamentals.
28+
Polymer CLI uses the [Service Worker Precache
29+
(`sw-precache`)](https://github.com/GoogleChromeLabs/sw-precache) library. All
30+
of the Polymer [build
31+
presets](/{{{polymer_version_dir}}}/docs/tools/polymer-json#presets), and the
32+
default build, include a service worker.
3233

33-
## Prerequisites
34-
35-
To work with service worker, your application **must** be served over HTTPS. However, you can
36-
test service worker on your local system without a SSL certificate, because `localhost` is
37-
considered a secure origin.
38-
39-
## Add a service worker
40-
41-
Support for Service Worker Precache is built into the [Polymer CLI](/{{{polymer_version_dir}}}/docs/tools/polymer-cli),
42-
so a service worker script is automatically generated when you build your app.
34+
For background, gotchas and debugging tips on service workers, see
35+
[Introduction to Service Workers](https://developers.google.com/web/fundamentals/primers/service-worker/) on Web Fundamentals.
4336

44-
However, to use the service worker, you need to add code to register it:
37+
## Prerequisites
4538

46-
```js
47-
// Register service worker if supported.
48-
if ('serviceWorker' in navigator) {
49-
navigator.serviceWorker.register('/service-worker.js');
39+
To work with a service worker, your application **must** be served over HTTPS.
40+
However, you can test your service worker locally without a SSL certificate,
41+
because `localhost` is considered a secure origin.
42+
43+
For information on browser support for service worker, see [Is Service Worker
44+
Ready](https://jakearchibald.github.io/isserviceworkerready/).
45+
46+
## Add a service worker to your build
47+
48+
To add a service worker to your build:
49+
50+
1. [Configure polymer.json](#configpolymerjson).
51+
2. [Add code to your entrypoint to register a service worker](#register).
52+
3. Run `polymer build`.
53+
54+
A service worker is added to your build.
55+
56+
### Configure polymer.json
57+
58+
To configure polymer.json, set the `"entrypoint"` and `"shell"` properties. The
59+
service worker will automatically precache these resources.
60+
61+
Polymer CLI generates a service worker by default. You can switch service worker
62+
generation on or off with the `"addServiceWorker"` option in your build
63+
configuration.
64+
65+
Example polymer.json configuration {.caption}
66+
67+
```json
68+
{
69+
"entrypoint": "index.html",
70+
"shell": "src/my-app.js",
71+
"builds": [
72+
{
73+
"name": "esm-unbundled",
74+
"browserCapabilities": [
75+
"es2015",
76+
"modules"
77+
],
78+
"js": {
79+
"minify": true
80+
},
81+
"css": {
82+
"minify": true
83+
},
84+
"html": {
85+
"minify": true
86+
},
87+
"bundle": false,
88+
"addServiceWorker": true
89+
}
90+
]
5091
}
92+
```
93+
94+
### Register your service worker
95+
96+
To use the service worker, add code to your app's entrypoint to register it:
97+
98+
Register a service worker {.caption}
99+
100+
```html
101+
<head>
102+
<script>
103+
// Feature detect for service worker capability in the browser
104+
if ('serviceWorker' in navigator) {
105+
// Delay registering until page load
106+
window.addEventListener('load', function() {
107+
navigator.serviceWorker.register('service-worker.js');
108+
});
109+
}
110+
</script>
111+
</head>
51112
```
52113

53-
Registering a service worker doesn't speed up the first load of your site, so you can delay
54-
registering it until after your app has loaded.
55-
56-
## Configuring the service worker
57-
58-
You can specify any Service Worker Precache options by passing an options file
59-
to the build command:
114+
Registering a service worker doesn't speed up the first load of your site. You
115+
can delay registering it until after your app has loaded.
60116

61-
<code>polymer build --sw-precache-config <var>config-file</var>.json</code>
117+
## Customize your service worker
62118

63-
The config file is a JavaScript file that exports a set of configuration options supported by
64-
Service Worker Precache. See [Options parameter](https://github.com/GoogleChrome/sw-precache#options-parameter)
65-
in the `sw-precache` README for more information.
119+
To customize your service worker, create a configuration file called
120+
`sw-precache-config.js` in your top-level project folder.
66121

67-
If you identify resources using the `--entrypoint`, `--shell` and `--fragment`, arguments, those
68-
files are added in to the `staticFileGlobs` parameter to ensure that they're cached.
122+
`sw-precache-config.js` exports a set of configuration options supported by
123+
Service Worker Precache. See [Options
124+
parameter](https://github.com/GoogleChrome/sw-precache#options-parameter) in the
125+
`sw-precache` README for more information.
69126

70-
If you're writing a single-page app and you want it to work completely offline, you probably want
71-
to specify a _fallback_ document, to be served when the requested URL is not in the cache. For a
72-
single—page app, this is typically the same as the entrypoint. Configure fallback using the
73-
[navigateFallback](https://github.com/GoogleChrome/sw-precache#navigatefallback-string) and
127+
If you're writing a single-page app and you want it to work completely offline,
128+
specify a _fallback_ document to be served when the requested URL is not in the
129+
cache. For a single—page app, this is typically the same as the entrypoint.
130+
Configure fallback using the
131+
[navigateFallback](https://github.com/GoogleChrome/sw-precache#navigatefallback-string)
132+
and
74133
[navigateFallbackWhitelist](https://github.com/GoogleChrome/sw-precache#navigatefallbackwhitelist-arrayregexp)
75134
parameters.
76135

77-
The following config file sets up some common options, including falling back to the `/index.html`
78-
file when offline.
136+
Example sw-precache-config.js {.caption}
79137

80138
```js
81139
module.exports = {
82140
staticFileGlobs: [
83141
'/index.html',
84142
'/manifest.json',
85-
'/bower_components/webcomponentsjs/webcomponents-lite.js',
143+
'/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js',
86144
'/images/*'
87145
],
88146
navigateFallback: '/index.html',
89-
navigateFallbackWhitelist: [/^(?!.*\.html$|\/data\/).*/]
147+
navigateFallbackWhitelist: [/^(?!.*\.js$|\/data\/).*/]
90148
}
91149
```
92150

93-
Only paths that match the whitelist fall back to `/index.html`. In this case, the whitelist includes
94-
all files _except_ those that end in `.html` (for HTML imports) and ones with `/data/` in the path
95-
(for dynamically-loaded data).
151+
Only paths that match the whitelist fall back to `/index.html`. In this case,
152+
the whitelist includes all files _except_ those that end in `.js` (for
153+
JavaScript imports) and ones with `/data/` in the path (for dynamically-loaded
154+
data).
96155

97156
## More resources
98157

99-
The library supports a number of other features, including runtime caching of
100-
your app's dynamic content.
158+
The `sw-precache` library supports a number of other features, including runtime
159+
caching of your app's dynamic content.
101160

102-
For more information on the library, see [Service Worker Precache Getting
161+
For more information on the library, see [Service Worker Precache: Getting
103162
Started](https://github.com/GoogleChrome/sw-precache/blob/master/GettingStarted.md).
104163

105164
For background on service workers, see [Introduction to Service
106-
Worker](https://developers.google.com/web/fundamentals/primers/service-worker/) on Web Fundamentals.
165+
Worker](https://developers.google.com/web/fundamentals/primers/service-worker/)
166+
on Web Fundamentals.

‎app/3.0/docs/devguide/dom-template.md

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -273,37 +273,41 @@ static get template() {
273273

274274
### URLs in templates {#urls-in-templates}
275275

276-
**Outdated information.** This section needs to be updated after
277-
[issue #5163](https://github.com/Polymer/polymer/issues/5163) is resolved.
278-
{.alert .alert-warning}
279-
280276
A relative URL in a template may need to be relative to an application or to a specific component.
281277
For example, if a component includes images alongside a module that defines an element, the
282278
image URL needs to be resolved relative to the import. However, an application-specific element may
283279
need to include links to URLs relative to the main document.
284280

285281
By default, Polymer **does not modify URLs in templates**, so all relative URLs are treated as
286282
relative to the main document URL. This is because when the template content is cloned and added
287-
to the main document, the browser evaluates the URLs relative to the document (not to the original
283+
to the main document, the browser evaluates the URLs relative to the document (not to the original
288284
location of the template).
289285

290-
To ensure URLs resolve properly, Polymer provides two properties that can be used in data bindings:
286+
Polymer provides the property `rootPath`-an instance property set to the value of `Polymer.rootPath`
287+
which is globally settable and defaults to the main document URL. It may be useful to set
288+
`Polymer.rootPath` to provide a stable application mount path when using client side routing.
291289

292-
| Property | Description |
293-
| -------- | ----------- |
294-
| `importPath` | A static getter on the element class. **To set URLs relative to the import, you must override the `importPath` getter.** |
295-
| `rootPath` | An instance property set to the value of `Polymer.rootPath` which is globally settable and defaults to the main document URL. It may be useful to set `Polymer.rootPath` to provide a stable application mount path when using client side routing. |
290+
To get a reference to the path from which an element was imported, add the following getter method
291+
to your element class:
296292

293+
```
294+
static get importMeta() {
295+
return import.meta;
296+
}
297+
```
298+
299+
When the element is loaded, the getter above assigns its `importPath` property. You can then use
300+
`importPath` in data bindings to resolve relative URLs.
297301

298302
Relative URLs in styles are automatically re-written to be relative to the `importPath` property.
303+
299304
Any URLs outside of a `<style>` element should be bound using `importPath` or
300305
`rootPath` where appropriate. For example:
301306

302307
```html
303-
// This getter must be defined for your element if you want to use importPath
304-
static get importPath() {
305-
// return the base URL for this import
306-
return import.meta.url;
308+
// This getter must be defined for your element if you want to use importPath
309+
static get importMeta() {
310+
return import.meta;
307311
}
308312

309313
static get template() {

‎app/3.0/docs/devguide/gesture-events.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ interactions. These events fire consistently on both touch and mouse environment
99
so we recommend using these events instead of their mouse- or
1010
touch-specific event counterparts. This provides better interoperability with both touch and mouse devices.
1111

12+
**In general, use the standard `click` event instead of `tap` in mobile browsers.** The `tap`
13+
event is included in the gesture event mixin for backwards compatibility, but it's no longer
14+
required in modern mobile browsers.
15+
{.alert .alert-info}
16+
1217
## Using gesture events
1318

1419
Add gesture support by importing and using the `GestureEventListeners` mixin:

0 commit comments

Comments
 (0)