diff --git a/app/1.0/index.html b/app/1.0/index.html index e4b27e577c..1ae90b42d3 100644 --- a/app/1.0/index.html +++ b/app/1.0/index.html @@ -233,14 +233,14 @@

#UseThePlatform to build a better web

Polymer Summit 2016

- +

Polymer Summit 2016 is done and dusted! Missed it, or want to replay your favorite talks? + You can find all the videos here!

+ Watch all + Summit site + Codelabs
-

Polymer Summit is almost here! Join us October 17–18, 2016, in person or by livestream, for two days of talks, guided codelabs, and breakout sessions. Livestream starts October 17 at 10AM BST.

- Livestream - Schedule -

Can't wait? You can still watch videos from last year's Summit in Amsterdam.

- Watch Summit 2015 Videos +
diff --git a/app/1.0/nav.yaml b/app/1.0/nav.yaml index 417a1c9697..8f2916d7af 100644 --- a/app/1.0/nav.yaml +++ b/app/1.0/nav.yaml @@ -42,7 +42,7 @@ - endheader: True - section: Polymer - shortpath: docs + shortpath: 1.0/docs path: /1.0/docs/devguide/feature-overview items: - title: Feature overview @@ -183,6 +183,19 @@ indent: True - endheader: True +- section: 2.0 Preview + shortpath: 2.0/docs + path: /2.0/docs/about_20 + items: + - title: About Polymer 2.0 + path: /2.0/docs/about_20 + - title: Upgrade guide + path: /2.0/docs/upgrade +# - title: Custom element concepts +# path: /2.0/docs/devguide/custom-elements +# - title: Shadow DOM concepts +# path: /2.0/docs/devguide/shadow-dom + - section: App Toolbox shortpath: toolbox path: /1.0/toolbox/ diff --git a/app/2.0/404.html b/app/2.0/404.html new file mode 100644 index 0000000000..7df8494e60 --- /dev/null +++ b/app/2.0/404.html @@ -0,0 +1,69 @@ + + + + +404 - Polymer Project +{% include 'templates/head-meta.html' %} + + + + {% include 'templates/site-nav.html' %} + + +
+
+
+ Offline Polymer dinosaur +
+
+

Not found.

+

We're sorry, but the polymerosaurus can't find the page you were looking for.

+

Maybe head back to the homepage or use one of the menu links instead?

+
+
+
+
+ + + + diff --git a/app/2.0/500.html b/app/2.0/500.html new file mode 100644 index 0000000000..31e0fb9543 --- /dev/null +++ b/app/2.0/500.html @@ -0,0 +1,69 @@ + + + + +500 - Polymer Project +{% include 'templates/head-meta.html' %} + + + + + {% include 'templates/site-nav.html' %} + +
+
+
+ Offline Polymer dinosaur +
+
+

EEEEK...500!

+

There was an issue on our end :(

+

Maybe head back to the homepage or use one of the menu links instead?

+
+
+
+
+ + + + diff --git a/app/2.0/about.html b/app/2.0/about.html new file mode 100644 index 0000000000..06413a499e --- /dev/null +++ b/app/2.0/about.html @@ -0,0 +1,135 @@ + + + + +About the Polymer Project +{% include 'templates/head-meta.html' %} + + + + {% include 'templates/site-nav.html' %} + + +
+
+

About the Polymer Project

+
+
+ +
+
+

Who we are

+ +

The Polymer Project is an open-source project led by a team of front-end developers working within the Chrome organization at Google.

+ +

Our mission

+ +

Our mission is to make life better for users and developers, by helping developers unlock the web platform’s full potential and by spurring the web platform to evolve and improve.

+ +

In pursuit of this mission, we work on libraries, tools and patterns to help developers build modern Progressive Web Apps, taking full advantage of cutting-edge platform features like Web Components, Service Workers and HTTP/2.

+ +

We also collaborate closely with our colleagues on the Chrome development team, identifying pain points, putting new platform features to the test and doing our part to ensure that front-end developers have a strong voice in the evolution of the platform.

+ +

Our motto, reflecting our unique mission, is #UseThePlatform. It’s worth explaining what that means to us.

+ +

Why #UseThePlatform?

+ +

tl;dr: We believe that embracing the modern web platform is the best way to give users and developers what they deserve.

+ +

Users deserve apps that launch quickly, respond instantly and can be accessed from anywhere—on devices of all types and sizes, under any network conditions.

+ +

Developers deserve a platform they can work with, not around—one that makes it easy to build, deliver and maintain these universally accessible, reliable, delightful, high-performing apps.

+ +

But we haven’t always gotten what we deserve from the web, especially when it comes to mobile.

+ +
    +
  • From a user point of view, too many mobile web apps launch slowly, perform poorly compared to native apps, and don’t work at all when network conditions are poor.

  • +
  • For app developers, the web platform has been frustratingly slow to evolve. For years, we’ve had to plug holes in the platform and build layers on top of it to meet basic needs like defining components and loading modules.

  • +
+ +

Credit where credit is due

+ +

The libraries, tools and frameworks we’ve built to fill the gaps in the web platform are a testament to the web’s fundamental extensibility and to the endlessly innovative spirit of the web community.

+ +

These innovations have been instrumental in the web’s transition from a content platform to a platform that supports powerful, feature-rich applications. There’s no doubt that the path forward will continue to be cleared and illuminated by our collective efforts in “user space.”

+ +

That said, there are real costs to doing too much outside and above the platform itself—costs that both developers and users pay.

+ +

Developer costs

+ +

Developer costs come in the form of complexity and lock-in.

+ +

Over time, the stacks we’ve built on top of the platform have pushed web development further and further from the simplicity of view-source and shift-refresh, to a place where every project begins with an overwhelming sea of choices.

+ +

And when we rely on libraries and frameworks for even our most basic needs, we end up writing code that depends on opinionated abstractions rather than universal platform primitives. Because it’s expensive to migrate from one abstraction to another, these dependencies limit our future choices and make our code costlier to maintain.

+ +

User costs

+ +

More importantly, users pay a performance penalty when the layers we build above the platform become too thick.

+ +

Every byte of code that we send over the wire consumes bandwidth that could be used for content and data, and every tick we spend executing JavaScript on the client reduces our apps’ responsiveness. This is especially true on the far reaches of the mobile web, where poor connections and underpowered devices are the norm.

+ +

Many of the development patterns that we use today originated in an era when we used the web mostly from the desktop. Now that the web is mobile-first, we need to reconsider those patterns. Giving our users the experience they deserve in the hyper-constrained mobile environment means aggressively minimizing bandwidth and execution cost, leaning heavily on the platform and saving our limited budget for things that only our applications can provide.

+ +

For example, the browser specializes in loading resources, parsing native web formats like HTML and CSS, and caching them for maximum efficiency. Similarly, the browser has highly optimized native code for instantiating elements, inserting them in the DOM, updating their properties and attributes, managing the flow of events between them, and eventually tearing them down.

+ +

When we write our own code to do these things, send that code over the network and execute it on the client, we are doing work we shouldn’t have to do; and in some cases, we are also negating current and future browser-side optimizations.

+ +

A platform-centric path forward

+ +

Thanks to new web platform primitives, many of the needs we’ve addressed by building over and around the platform can now be met by the platform itself:

+ +
    +
  • Web Components let us extend the browser’s built-in component model—the DOM—rather than bring our own.

  • + +
  • In combination with HTTP/2 and server push, standard module formats like HTML Imports and ES6 Modules let us declare fine-grained dependencies and efficiently deliver them to the client in optimally cacheable form, without relying on complicated packaging tools and loaders.

  • + +
  • Service Workers let us build pure web apps that users can access even when their devices are offline or network conditions are poor, whereas previously we might have had to resort to manually installable native or “hybrid” apps.

  • +
+ +

We believe that in the next era, the best-performing apps will be those that take full advantage of these modern web platform features and let the browser do the heavy lifting wherever it can. Similarly, the least costly, most future-proof apps will be those that build as much as possible on platform primitives, maximizing interoperability and minimizing switching costs.

+ +

Rethinking libraries and frameworks

+ +

Using the platform doesn’t mean leaving libraries and frameworks behind; it just means making them lighter, and designing them to complement the strengths of the platform itself.

+ +

At their best, libraries and frameworks make our jobs easier. They provide off-the-shelf solutions for hard problems; broadly applicable abstractions that save us from reinventing the wheel; and useful patterns and constraints to help us structure our apps intelligently and avoid shooting ourselves in the foot.

+ +

The challenge is to achieve these benefits while minimizing the weight of our solutions and making the most of what the platform provides.

+ +

Within this problem space, as always, there’s plenty of room for innovation and opinion. For our part, we aim to treat the platform as the framework, adding value in the form of lightweight, optional “sugaring” of platform APIs; loosely coupled, interoperable modules; and effective patterns for composing components and applications from smaller building blocks.

+ +

Our role

+ +

Returning to our mission, here’s how we see our role:

+ +
    +
  • Strongly advocate a platform-centric approach to building modern web apps

  • + +
  • Build libraries and tools to support app developers in adopting a platform-centric approach

  • + +
  • In doing so, explore and exemplify best practices for designing platform-centric libraries and tools

  • + +
  • Based on our own experiences and those of the broader community, continue to influence the evolution of the platform from within the Chrome organization

  • +
+ +

We believe the patterns, libraries and tools we work on are beneficial, and we're happy to see them widely adopted.

+ +

But our campaign to #UseThePlatform is ultimately not about driving people to use the stuff the Polymer Project builds. It’s about promoting the use of the web platform to deliver the best apps possible, and helping to ensure that web users and developers get everything they deserve from the platform in the future.

+
+
+ +
+ + + + diff --git a/app/2.0/authors.yaml b/app/2.0/authors.yaml new file mode 100644 index 0000000000..cba33b9d12 --- /dev/null +++ b/app/2.0/authors.yaml @@ -0,0 +1,66 @@ +--- +ebidel: + full_name: Eric Bidelman + gplus: +EricBidelman + profile_pic: https://lh5.googleusercontent.com/-kgFnix5akCc/AAAAAAAAAAI/AAAAAAAAOqk/IVG-V3nJ8jM/s40-c/photo.jpg + web: http://www.ericbidelman.com + twitter: ebidel + github: ebidel + +addyosmani: + full_name: Addy Osmani + gplus: 115133653231679625609 + profile_pic: https://lh3.googleusercontent.com/-riQH0F3Zb2k/AAAAAAAAAAI/AAAAAAAAyyI/A0ynkSbO-nM/s40-c/photo.jpg + web: http://addyosmani.com/ + twitter: addyosmani + github: addyosmani + +robdodson: + full_name: Rob Dodson + gplus: +RobDodson + profile_pic: https://lh3.googleusercontent.com/-0IG6advy6qg/AAAAAAAAAAI/AAAAAAAAAJM/pivb_QaIJjQ/s40-c/photo.jpg + web: http://robdodson.me + twitter: rob_dodson + github: robdodson + +alice: + full_name: Alice Boxhall + gplus: 111975973972817482025 + profile_pic: https://lh5.googleusercontent.com/-nS21Q4tD1R4/AAAAAAAAAAI/AAAAAAAAAp4/ixMudlaPGDs/s40-c/photo.jpg + twitter: sundress + github: alice + +sjmiles: + full_name: Scott Miles + gplus: 116100920359918112000 + profile_pic: https://lh3.googleusercontent.com/-7uiizITSXzc/AAAAAAAAAAI/AAAAAAAAAH0/qiZVhp4C0i8/s40-c/photo.jpg + twitter: scottjmiles + github: sjmiles + +rictic: + full_name: Peter Burns + gplus: +PeterBurnsrictic + profile_pic: https://lh3.googleusercontent.com/-JcCDjeNJTuk/AAAAAAAAAAI/AAAAAAAAJo0/wZSCEJGEacI/s120-c/photo.jpg + twitter: rictic + github: rictic + +polymer-team: + full_name: Polymer Team + gplus: +PolymerProject + profile_pic: /images/logos/p-author-logo.png + web: https://www.polymer-project.org/ + twitter: polymer + github: polymer + +taylor: + full_name: Taylor Savage + gplus: 102507331653262188696 + profile_pic: https://lh3.googleusercontent.com/-3m6T7W06bm4/AAAAAAAAAAI/AAAAAAAAAW8/RulK3UZPplI/s120-c/photo.jpg + github: tjsavage + twitter: taylorthesavage + +fbeaufort: + full_name: François Beaufort + gplus: +FrancoisBeaufort + profile_pic: https://lh3.googleusercontent.com/-jHvqK47b3F4/AAAAAAAAAAI/AAAAAAAA-0w/fayGhfYcgrk/s120-c/photo.jpg + github: beaufortfrancois diff --git a/app/2.0/docs/about_20.md b/app/2.0/docs/about_20.md new file mode 100644 index 0000000000..1ee5056ee5 --- /dev/null +++ b/app/2.0/docs/about_20.md @@ -0,0 +1,485 @@ +--- +title: About Polymer 2.0 +--- + + + +Polymer 2.0 is designed to support the new custom elements v1 and shadow DOM v1 specifications being implemented by most major browser vendors, while providing a smooth migration path for Polymer 1.x users. + +Polymer 2.0 also makes improvements in several areas: + + + +* **Improved interoperability.** By removing the need to use Polymer.dom for DOM manipulation, Polymer 2.0 makes it easier to use Polymer components with other libraries and frameworks. In addition, the shady DOM code has been separated out into a reusable polyfill, instead of being integrated into Polymer. +* **Data system improvements.** Polymer 2.0 includes targeted improvements to the data system. These changes make it easier to reason about and debug the propagation of data through and between elements. They also improve compatibility with top-down data flow approaches, like Flux. +* **More standard.** Polymer 2.0 uses standard ES6 classes and the standard custom elements v1 methods for defining elements, instead of a Polymer factory method. You can mix in features using standard JavaScript (class expression mixins) instead of `Polymer` behaviors. (The `Polymer` factory method is still supported using a compatibility layer.) + +**Unreleased preview code.** Currently, Polymer 2.0 is available as a branch of the Polymer library repo on GitHub. **This is an active development branch, and should not be used in production.** By all means, use the `2.0-preview` branch to experiment, to provide feedback, and to familiarize yourself with the latest versions of the custom elements and shadow DOM specifications. Just don't build production code on it quite yet. Please. +{.alert .alert-warning} + +Some tests currently fail on non-Chrome browsers; these will be addressed soon, but in the short term Chrome Canary is your best bet. + +Polymer 2.0 introduces a number of breaking changes—many of which are required by new custom elements v1 and shadow DOM v1 specifications. Expect to see more changes as this new version nears release. + +The following sections describes the major changes in Polymer 2.0. For details on upgrading elements to Polymer 2.0, see the [upgrade guide](upgrade). + +## Custom elements v1 + +Polymer 2.0 elements target the custom elements v1 API, which makes several changes to the v0 version of the spec used in Polymer 1.x. In particular: + + + +* The custom elements v1 spec defines elements using ES6 classes, instead of prototypes. + +Polymer 2.0 lets you use this native ES6 form by providing an ES6 base class (`Polymer.Element`) for your elements to extend. In addition, legacy elements using the `Polymer` factory method are supported with a Polymer 1.x compatibility layer. + + + +* The new spec has some changes to the lifecycle callbacks. In particular, instead of a created callback it invokes the class constructor. The spec also imposes new restrictions on what can be done in the constructor (previously createdCallback). + + + +* In addition, although they are supported in the specification, Polymer 2.0 does not currently support type-extension elements (`is=`). + +The following sections describe these changes in more detail. + +For general information on the custom elements v1 specification, see [Custom elements v1: reusable web components](https://developers.google.com/web/fundamentals/primers/customelements/?hl=en) on Web Fundamentals. + +### Lifecycle changes {#lifecycle-changes} + +When creating class-based elements, use the new native lifecycle methods (called "custom element reactions"). When creating legacy elements using the Polymer factory method, use the legacy Polymer callback names. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Reaction/callback name + Notes +
constructor (native) +

+created (legacy) +

The custom elements v1 spec forbids reading attributes, children, or parent information from the DOM API in the constructor (created callback in the legacy API). Likewise, attributes and children may not be added in the constructor. Any such work must be deferred (for example, until connectedCallback). + +The legacy created callback is no longer called before default values in properties have been set. As such, you should not rely on properties set in created from within value functions that define property defaults. +

+However, you can now set any property defaults within the created callback (in 1.0 this was forbidden for observed properties) in lieu of using the value function in properties. +

connectedCallback (native) +

+attached (legacy) +

Polymer 1.x deferred the attached callback until after first render, so elements could measure themselves or their children. +
disconnectedCallback (native) +

+detached (legacy) +

+
attributeChangedCallback (native) +

+attributeChanged (legacy) +

Attributes must be explicitly registered to be observed. +

+For Polymer elements, only properties explicitly declared in the properties object are tracked for attribute changes. (That is, changing the attribute value invokes the attribute changed callback, and causes Polymer to set the property value from the attribute.) +

+In custom elements v0, the attributeChangedCallback was generated for any attribute change. +

+In Polymer 1.x, attributes were deserialized for both explicitly declared properties and implicitly declared properties. For example, a property used in a binding or as the dependency of an observer, but not declared in properties can be considered implicitly declared. +

ready (Polymer specific) + Polymer longer guarantees that the initial light DOM distribution is complete before ready is called. +
+ + +In addition to changes in the callbacks, note that the `lazyRegister` option has been removed and all meta-programming (parsing the template, creating accessors on the prototype, and so on) is deferred until the first instance of the element is created. + +### Type-extension elements {#type-extension} + +Polymer 2.0 doesn't support type-extension elements (for example, ``). Type-extension support is still included in the custom elements v1 spec (as "customized build-in elements"), and scheduled for implementation in Chrome. However, since Apple has said it will not implement `is`, we will not be encouraging its use to avoid indefinite reliance on the custom elements polyfill. Instead, a wrapper custom element can surround a native element. For example: + +`...` + +Could become: + + +``` + + ... + +``` + + +Users will need to change existing type-extension elements where necessary. + +All template type extensions provided by Polymer have now been changed to standard custom elements that take a ` + +``` + +The `id` attribute specifies the name you'll use to reference +your shared styles. Style module names use the same namespace as elements, +so your style modules must have unique names. + +Using the shared styles is a two-step process: you need to use a `` tag +to _import_ the module, and a ` + + Hi + + + +``` + +You can also use a shared style module in a `custom-style` element. + +```html + + + + +``` + +A single style tag can both `include` shared styles +and define local rules: + +```html + +``` + +(This works for both `custom-style` elements and ` + +``` + +For more information, see [https://poly-style.appspot.com/demo/](https://poly-style.appspot.com/demo/). + +**Related tools** + +- [gulp-style-modules](https://github.com/MaKleSoft/gulp-style-modules)—3rd party Gulp plugin for wrapping local CSS files into style modules + +Source: [github.com/PolymerLabs/polystyles](https://github.com/PolymerLabs/polystyles) + +## polyicon—create an optimized custom icon set {#polyicon} + +[polyicon](https://github.com/PolymerLabs/polyicon) is an online tool to generate +an optimized custom icon set for your app, with only the icons that you need. +Instead of loading entire sets, this tool creates a slimmer (custom) icon set that you can load and use in your app. + +Try it out: [https://poly-icon.appspot.com/](https://poly-icon.appspot.com/) + +Source: [github.com/PolymerLabs/polyicon](https://github.com/PolymerLabs/polyicon) diff --git a/app/2.0/docs/tools/tests.md b/app/2.0/docs/tools/tests.md new file mode 100644 index 0000000000..b33ee07f24 --- /dev/null +++ b/app/2.0/docs/tools/tests.md @@ -0,0 +1,403 @@ +--- +title: Test your elements +--- + + + +This guide shows you the basics of using Polymer CLI to run unit tests, and +how to accomplish various tasks and scenarios using the Web Component Tester +library (the underlying library that powers Polymer CLI's testing tools). + +## Overview + +Polymer CLI is an all-in-one command-line interface that covers the vast majority of +Polymer development tasks, including unit testing. The underlying library +that powers Polymer CLI's unit testing tools is called Web Component Tester. + +Web Component Tester is an end-to-end testing environment built by the Polymer +team. It enables you to test your elements locally, against all of your +installed browsers, or remotely, via Sauce Labs. It is built on top of +popular third-party tools, including: + +* [Mocha](https://mochajs.org/) for a test framework, complete with support + for BDD and TDD. +* [Chai](http://chaijs.com/) for more assertion types that can be used with + your Mocha tests. +* [Sinon](http://sinonjs.org/) for spies, stubs, and mocks. +* [Selenium](http://www.seleniumhq.org/) for running tests against + multiple browsers. +* [Accessibility Developer + Tools](https://github.com/GoogleChrome/accessibility-developer-tools) + for accessibility audits. + +## Quick start {#quick-start} + +For demonstration purposes, this guide shows you how to install Polymer CLI +and initialize an element project. You'll then use this project to learn how +to add and run unit tests. + +1. (OS X only) [Manually install][selenium] the latest SafariDriver + extension for Selenium [(`SafariDriver.safariextz`)][safaridriver] to ensure + that Web Component Tester can run properly. See the + [Web Component Tester Polycast][workaround-example] for + a demonstration. Note: the Polycast is somewhat outdated, but the section + that the URL links to is still relevant. + +1. Install Polymer CLI. Follow the directions in + [Install Polymer CLI](polymer-cli#install) to get started. + +1. [Create an element project](polymer-cli#element). This guide assumes that + your element project directory and your element are both named `my-el`. + +1. `cd` to the base directory of your project. + +1. Run `ls`. + + You'll see that your element project contains a + directory called `test`. This is where all of your unit tests should be + stored. + + When you run `polymer test`, Web Component Tester automatically + searches for a `test` directory and runs any tests it finds in there. If + you use another directory name, you'll need to specify it when you run + `polymer test`. + {.alert .alert-info} + +1. Open up `test/my-el_test.html` to see an example of a basic unit test. + +1. Run the test. + + polymer test + + Web Component Tester automatically finds all of the browsers on your + system and runs your tests against each one. If you wanted to run your + tests against a single browser, say Google Chrome, you could + `polymer test -l chrome`. + {.alert .alert-info} + +### Run tests interactively + +You can also run your tests in the browser. This allows you to use the +browser's DevTools to inspect or your debug your unit tests. + +For example, using Polymer CLI and the example element project created +in [Quick start](#quick-start) above, first you would start your server: + + polymer serve + +And then, to run the basic `my-el_test.html` unit test in the browser, you +would open a web browser and go to the following URL: + + localhost:8080/components/my-el/test/my-el_test.html + +## Creating tests + +Now that you've got the basics down of using Polymer CLI to run tests, it's +time to start creating them. + +This section of the doc shows you how to accomplish various tasks or scenarios +while implementing your unit tests. + +### Asynchronous tests {#async} + +To create an asynchronous test, pass `done` as an argument to the test function +and then call `done()` when the test is complete. The `done` argument is a +signal to Mocha that the test is asynchronous. When Mocha runs the test, +it waits until the test code invokes the `done()` callback. If the `done()` +callback isn't invoked, the test eventually times out and Mocha reports the test +as a failure. + +```js +test('fires lasers', function(done) { + myEl.addEventListener('seed-element-lasers', function(event) { + assert.equal(event.detail.sound, 'Pew pew!'); + done(); + }); + myEl.fireLasers(); +}); +``` + +### Prevent shared state with test fixtures {#test-fixtures} + +Test fixtures enable you to define a template of content and copy a clean, +new instance of that content into each test suite. Use test fixtures to +minimize the amount of shared state between test suites. + +To use a test fixture: + +* Define the test fixture template and give it an ID. +* Define a variable in your test script to reference the template. +* Instantiate a new instance of the fixture in your `setup()` method. + +```html + + + + + +``` + +### Create stub methods + +Stubs enable you to replace default implementations with custom methods. This +is useful for catching side effects. + +``` +setup(function() { + stub('paper-button', { + click: function() { + console.log('paper-button.click called'); + } + }); +}); +``` + +You don't have to use stubs directly on individual elements. You can override +the implementation for all elements of a given type. + +### Create stub elements + +Use [stub elements](http://stackoverflow.com/questions/463278/what-is-a-stub) +to test elements in isolation. For example, if one of your tests +depends on another element to return data, rather than importing the other +(possibly unstable) element into your tests, you can implement a stub of the +other element that always returns consistent data. + +Use `replace()` to create stub elements. + +```js +setup(function() { + replace('paper-button').with('fake-paper-button'); +}); +``` + +For example, using the sample `replace()` above and the element below: + +``` + + + +``` + +At test runtime, the content template would be stamped out as: + +``` + + + +``` + +The attributes and content of the element are preserved, but the tag +is replaced with the specified stub tag. + +Because the method is called within `setup()`, all of the changes are +reverted at the end of each test. + +### AJAX + + + +Web Component Tester includes [Sinon](http://sinonjs.org/), which enables you to mock XHR +requests and create fake servers. + +Below is an example of a simple XHR unit test suite for +[``](https://elements.polymer-project.org/elements/iron-ajax). +Check out Sinon's documentation for more in-depth examples. + +``` + + + + + +``` + +**Note:** The example above uses Chai's [`expect`](http://chaijs.com/api/bdd/) +assertion style. +{ .alert .alert-info } + +### Run a set of tests {#test-sets} + +To run a set of tests, create an HTML file and call `loadSuites()`. When +running Web Component Tester, specify the path to the HTML file as the first argument +(for example, `wct test/my-test-set.html`. + +``` + + + + + + + + + + + +``` + +The argument to `loadSuites()` should be an array of strings. Each string +should be a relative URL to a test suite. You can configure your tests +using query strings in the URLs. See [Test shadow DOM](#shadow-dom) +for an example. + +### Test local DOM + +Use Polymer's [DOM API](/1.0/docs/devguide/local-dom#dom-api) to access +and modify local DOM children. + +```js +test('click sets isWaiting to true', function() { + myEl.$$('button').click(); + assert(myEl.isWaiting, true); +}); +``` + +**Note:** `myEl.$$('button')` returns the first `button` element encountered +in the local DOM of `myEl`. +{ .alert .alert-info } + +#### Test DOM mutations + +Always wrap your test in `flush` if your element template contains a [template +repeater (`dom-repeat`)](/1.0/docs/devguide/templates#dom-repeat) or +[conditional template (`dom-if`)](/1.0/docs/devguide/templates#dom-if), +or if your test involves a local DOM mutation. Polymer lazily performs these +operations in some cases for performance. `flush` ensures that asynchronous +changes have taken place. The test function should take one argument, `done`, +to indicate that it is [asynchronous](#async), and it should call +`done()` at the end of `flush`. + +``` +suite('my-list tests', function() { + var list, listItems; + setup(function() { + list = fixture('basic'); + }); + test('Item lengths should be equal', function(done) { + list.items = [ + 'Responsive Web App boilerplate', + 'Unit testing with Web Component Tester', + 'Offline support with the Platinum Service Worker Elements' + ]; + // Data bindings will stamp out new DOM asynchronously + // so wait to check for updates + flush(function() { + listItems = Polymer.dom(list.root).querySelectorAll('li'); + assert.equal(list.items.length, listItems.length); + done(); + }); + }); +)}; +``` + +#### Test with native shadow DOM {#shadow-dom} + +To test out how a test suite behaves when the browser runs native +shadow DOM, create a [test set](#test-sets) and pass `dom=shadow` as +a query string when Web Component Tester loads your test suites. + +```js +WCT.loadSuites([ + 'basic-test.html', + 'basic-test.html?dom=shadow' +]); +``` + +This sample runs `basic-test.html` twice, once using shady DOM and once +using native shadow DOM (if the browser supports it). + +### Automated testing in the cloud + +It's important to get a good testing setup in place for your project as +early as possible. Using services like Travis for continuous integration, +and Sauce Labs for cross-browser testing means you can be confident that +changes you push to your project will work well on different platforms and +devices. For guidance on setting up these tools check out the Polycast below. + + + +## Learn more + +Polymer Summit 2015 video on testing: + + + +The [Web Component Tester README][wct-readme] has more in-depth information +about Web Component Tester usage. + +[seed-element]: https://github.com/PolymerElements/seed-element +[wct-readme]: https://github.com/Polymer/web-component-tester/blob/master/README.md +[selenium]: https://github.com/SeleniumHQ/selenium/wiki/SafariDriver#getting-started +[safaridriver]: http://selenium-release.storage.googleapis.com/2.48/SafariDriver.safariextz +[workaround-example]: https://youtu.be/YBNBr9ECXLo?t=74 +[wct-polycast]: https://youtu.be/YBNBr9ECXLo +[ajax-polycast]: https://www.youtube.com/watch?v=_9qARcdCAn4 diff --git a/app/2.0/docs/upgrade.md b/app/2.0/docs/upgrade.md new file mode 100644 index 0000000000..102d630216 --- /dev/null +++ b/app/2.0/docs/upgrade.md @@ -0,0 +1,979 @@ +--- +title: Polymer 2.0 upgrade guide +--- + + + + +Polymer 2.0 includes a number of breaking changes. However, the Polymer team has worked to provide an incremental path for updating Polymer 1.x elements to 2.0. + +Polymer 2.0 supports several types of elements: + + + +* 2.0 class-based elements use the ES6 class-based syntax supported by the custom elements v1 specification. Recommended for new development in Polymer 2.0. +* 2.0 legacy elements use the `Polymer` factory method, and have most of the 1.0 API available to them. +* 2.0 hybrid elements are elements defined using the legacy `Polymer` factory method, with extra code for backwards compatibility with 1.x. They can run on Polymer 1.7+ as well as Polymer 2.0. + +When porting a large project, you can update to Polymer 1.7 and upgrade elements to 2.0 hybrid style one at a time. After all of the elements have been upgraded, you can test your project against Polymer 2.0. + +The Polymer team plans to release a Polymer Upgrade tool to automatically perform a number of the changes required to upgrade 1.x elements to either hybrid or class-based style. The remaining changes require either manual code changes, testing, or both to ensure that your element operates the same in 2.0 as it did in 1.x. + +See [Install Polymer 2.0](about_20#installing) for installation instructions. + +This upgrade guide is a work in progress. Please [report issues on GitHub](https://github.com/Polymer/docs/issues/new). + +## Shadow DOM changes {#shadow-dom-changes} + +Polymer 2.0 elements create shadow DOM v1 shadow trees. As such, user code related to scoped styling, distribution, and events must be adapted to the native v1 API. + + + +* ***All elements*** need to update their shadow DOM template and styling as described in [DOM template](#dom-template) and [Shadow DOM styles](#shadow-dom-styles). +* ***Hybrid elements*** should continue to use the Polymer.dom APIs, but may require some changes. +* ***Class-based elements*** don't need to use the Polymer.dom APIs for manipulating DOM or referring to events. + +### DOM Template {#dom-template} + +***All elements*** need to update their shadow DOM template and styling as described in this section. + +Quick summary: + + + +* Remove deprecated patterns in the DOM module (`` using `is` or `name`; styles outside of the template). +* Update your element's DOM template to use the new `` element instead of ``. +* Update styles to use the `::slotted()` selector in place of ::content. +* Remove any `/deep/` and `::shadow` CSS rules. + +These changes are detailed in the following sections. + +#### Remove deprecated patterns in DOM module {#remove-deprecated-patterns-in-dom-module} + +Your `` **must set** the `id` property to specify the element name. Polymer 1.x accepted the deprecated `is` or `name` as alternatives. + +Make sure your element's styles are defined *inside the template*. Defining styles outside the template was deprecated in Polymer 1.x and is no longer supported. + +Before {.caption} + + +``` + + + + +``` + + +After {.caption} + + +``` + + + +``` + + +#### Replace content elements {#replace-content-elements} + +* Change `` insertion points to `` elements. + +* Change `` to named slots: ``. + +Before {.caption} + +```html + + + + + + ... + + + Mr. Darcy + Fun at parties. + +``` + + +After {.caption} + + +```html + + + + + + ... + + + Mr. Darcy + Fun at parties. + +``` + + +Note that if you're using `` anywhere in your code, ***this means a change to your element's contract***, and everyone using your element will need to update to use slot names. + +**Limitation.** Slots can only be selected explicitly, by *slot name*. It's impossible to select content implicitly, based on a tag name or an arbitrary selector like `:not(.header)`. +{.alert .alert-info} + +Can't be upgraded automatically {.caption} + + +```html + + + + + + + +

Mr. Darcy

+ Not so fun at parties. +
+``` + + +**Default slot versus default insertion point.** In v0, a default insertion point (one without a `select` attribute) consumes all nodes **not matched by a previous insertion point**. In v1, a default slot (one without a `name` attribute) **only matches content with no slot attribute**. In other words, **a node with a slot attribute is never distributed to the default slot**. +{.alert .alert-info} + + +```html + + + + + +``` + + +If you have complex distributions, and you're trying to upgrade to hybrid elements, you may need +to place **both** `` and `` elements in the template. + +#### Multilevel distribution {#multilevel-distribution} + +Multilevel distribution works differently in shadow DOM v1. In v0, content was redistributed at each level. For example, an element with `class="title"` can be distributed through several insertion points and eventually selected by a ``. + +Document content {.caption} + +``` + + + My Title + +``` + + +Shadow DOM of <`parent-el>` {.caption} + + +``` + + + +``` + + +Shadow DOM of `` {.caption} + + +``` +

+ + +

+``` + + +By contrast, in v1, a host's light DOM nodes are only *assigned* to slots in the host's shadow DOM, based on the `slot` attributes on those light DOM nodes. For a parent element to redistribute content to a named slot, it must use a slot with a `slot` attribute. + + +``` + + + My Title + +``` + + +Shadow DOM of <`parent-el>` {.caption} + + +``` + + + + +``` + + +Shadow DOM of `` {.caption} + + +``` +

+ + +

+``` + + +Using the v0 approach does not work in v1: + + +``` + + + My Title + +``` + + +Shadow DOM of <`parent-el>` {.caption} + + +``` + + + + +``` + + +Shadow DOM of `` {.caption} + + +``` +

+ + +

+``` + + +### Shadow DOM styles {#shadow-dom-styles} + +Update styles in your shadow DOM to match v1 specifications: + + + +* Replace `::content` selectors with `::slotted()` selectors. +* Remove `/deep/` and `::shadow` selectors, if you're still using them. +* Remove `:root` selectors. +* Update custom property syntax. +* Wrap `custom-style` elements. + +#### Replace content selectors + +Replace any `::content` CSS selectors with ::slotted(selector) where selector is [compound selector](https://drafts.csswg.org/selectors-4/#compound) that identifies a top-level distributed child. + +That is: + +`::slotted(.foo)` + +is equivalent to: + + +``` +::content > .foo +``` + + +**For example**: + + +``` + + + + + + +
+ I'm colored blue. +
+
+ I'm colored red. +
+
+ Surprise! Not red. +
+
+``` + +In shadow DOM v1, **you cannot select a descendant of a top-level distributed child**. For example, you can't select the span in the previous example like this: + +`#container ::slotted(*) span { ... }` + +No selectors can follow the `::slotted()` selector. + +For more information, see [Styling distributed nodes](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom#stylinglightdom) in the Web Fundamentals article on shadow DOM. + +#### Remove deep and shadow selectors + +If you still have any `/deep/` or `::shadow` selectors in your project, it's time to remove them. They don't work at all in shadow DOM v1. + +There's no direct substitute for shadow-piercing selectors.To let users customize your element, custom CSS properties and mixins are probably the best option. + +#### Replace root selectors {#replace-root-selectors} + +If you're using the `:root` selector inside an element's template, replace it with: + + +```css +:host > * { ... } +``` + + +(If you're using `:root` selection inside a `custom-style`, replace it with the `html` selector.) + +In 1.x, you can use either of these selectors to override custom properties set at a higher level. For example, the following rule in the main document: + + +```css +style-me { + --my-theme-color: blue; +} +``` + + +Overrides a `:host` rule in `style-me`'s shadow root, because they match the same element, but the main document styles comes earlier in the cascade order. `:host > *` applies a ruleset to all of the top-level children in the host's shadow tree, which doesn't conflict with the rule in the main document. + +Before {.caption} + + +```html + +``` + + +After {.caption} + + +```html + +``` + + +#### Update custom property syntax {#update-custom-property-syntax} + +When applying custom properties, Polymer 1.x accepted this incorrect syntax for specifying a default value to a `var()` function: + +Before {.caption} + + +```css +color: var(--special-color,--default-color); +``` + + +By specification, the default (or fallback) is a CSS value, not a custom property name. To use a custom property as a default, add a nested `var()` function. + +After {.caption} + +```css +color: var(--special-color, var(--default-color)); +``` + + +In addition, you must update the syntax of any `@apply` rules to match the proposal, which doesn't use parentheses. + +Before {.caption} + + +```css +@apply(--my-mixin); +``` + + +After {.caption} + + +```css +@apply --my-mixin; +``` + + +#### Wrap custom-style elements {#wrap-custom-style-elements} + +While custom elements v1 supports customized built-in elements, Polymer 2.0 does not currently use them. Instead, it introduces a new `` element that wraps a ` +``` + + +**After (hybrid element):** + + +```html + + + + + + + + diff --git a/app/2.0/homepage/contact-card/index.html b/app/2.0/homepage/contact-card/index.html new file mode 100755 index 0000000000..9fa3e29a12 --- /dev/null +++ b/app/2.0/homepage/contact-card/index.html @@ -0,0 +1,13 @@ + + + + + + + + + Eric's photo + Eric Bidelman + + + diff --git a/app/2.0/homepage/google-map/index.html b/app/2.0/homepage/google-map/index.html new file mode 100755 index 0000000000..36cb9304d2 --- /dev/null +++ b/app/2.0/homepage/google-map/index.html @@ -0,0 +1,19 @@ + + + + + + + + + + + diff --git a/app/2.0/index.html b/app/2.0/index.html new file mode 100644 index 0000000000..64ae6ffb59 --- /dev/null +++ b/app/2.0/index.html @@ -0,0 +1,441 @@ + + + + +Welcome - Polymer Project +{% include 'templates/head-meta.html' %} + + + + {% include 'templates/site-nav.html' %} + + +
+
+
+ Polymer logo +
+
+

#UseThePlatform to build a better web

+
+

The Polymer Project helps you deliver amazing user experiences by unlocking the full potential of the web platform.

+

Use the Polymer library to make the most of Web Components, a powerful new platform feature for extending HTML and componentizing your apps.

+

Use the Polymer App Toolbox to build cutting-edge Progressive Web Apps that load quickly, respond instantly and work from anywhere.

+
+ +
+
+
+ +
+
+

Polymer Summit 2016

+
+
+ +
+
+

Registration is open for the second Polymer Summit, October 17 - 18, 2016 in London. The summit will feature two days of talks, guided codelabs, and breakout sessions presented by the Polymer team, Google engineers, and engineers at other companies using Polymer in production.

+ Register + Go To Summit Site +

To whet your appetite, watch videos from last year's Summit in Amsterdam.

+ Watch +
+
+
+
+ +
+
+
+

Polymer library

+
+

Polymer is a lightweight library that helps you take full advantage of Web Components.

+

With Web Components, you can create reusable custom elements that interoperate seamlessly with the browser’s built-in elements, or break your app up into right-sized components, making your code cleaner and less expensive to maintain.

+

Polymer sprinkles a bit of sugar over the standard Web Components APIs, making it easier for you to get great results.

+
+ About the Library +
+ +
+

Polymer App Toolbox

+
+

Polymer App Toolbox helps you build and deliver cutting-edge Progressive Web Apps with minimal overhead and payload, by leveraging powerful web platform features like Web Components, Service Worker and HTTP/2.

+

The Toolbox provides a component-based architecture, responsive layouts, a modular router, localization support, turnkey support for local storage and offline caching, and efficient delivery of unbundled app resources. Adopt these features individually, or use them together to build a full-featured Progressive Web App.

+
+ About the Toolbox +
+
+
+ +
+
+
+ illustration of an abstract arrow +

Built for speed

+

Because they let the platform do the heavy lifting, elements built with the Polymer library and apps built with the App Toolbox are blazing fast.

+
+ +
+ illustration of a computer +

For today and beyond

+

Polymer makes the most of the web platform by using the latest APIs. Polyfills provide support on evergreen browsers for APIs that aren't universal yet.

+
+ +
+ illustration of bolts +

Fully interoperable

+

Polymer-powered elements are based on standard Web Components APIs, so they work seamlessly with the browser's built-in elements and other Web Components.

+
+
+
+ +
+
+

Use elements from the catalog

+
+
+

+  <!-- Polyfill Web Components support for older browsers -->
+  <script src="components/webcomponentsjs/webcomponents-lite.min.js"></script>
+
+  <!-- Import element -->
+  <link rel="import" href="components/google-map/google-map.html">
+
+  <!-- Use element -->
+  <google-map latitude="37.790" longitude="-122.390"></google-map>
+          
+
+
+ +

An element built with Polymer looks and works just like any other HTML element. Simply find an element you’d like to use in your app, import it with an HTML import, and then add the tag to your page.

+ Browse elements +
+
+
+ +
+

Create your own elements

+
+
+

+  <dom-module id="contact-card">
+    <style>...</style>
+    <template>
+      <content></content>
+      <iron-icon icon="star" hidden$="{{!starred}}"></iron-icon>
+    </template>
+    <script>
+      Polymer({
+        is: 'contact-card',
+        properties: {
+          starred: Boolean
+        }
+      });
+    </script>
+  </dom-module>
+            
+
+

+  <contact-card starred>
+    <img src="profile.jpg" alt="Eric's photo">
+    <span>Eric Bidelman</span>
+  </contact-card>
+            
+
+ +
+ +

The Polymer library makes it easy to create your own powerful elements. Give your element some markup and properties, and then use it on a site. Polymer provides useful features like templating and data binding to reduce the amount of boilerplate you need to write.

+ Build an element +
+
+
+ +
+

Build Progressive Web Apps

+
+
+

+  <iron-pages role="main" selected="[[page]]" attr-for-selected="name" selected-attribute="visible">
+    <!-- home view -->
+    <shop-home name="home" categories="[[categories]]"></shop-home>
+
+    <!-- list view of items in a category -->
+    <shop-list name="list" route="[[subroute]]" offline="[[offline]]"></shop-list>
+
+    <!-- detail view of one item -->
+    <shop-detail name="detail" route="[[subroute]]" offline="[[offline]]"></shop-detail>
+
+    <!-- cart view -->
+    <shop-cart name="cart" cart="[[cart]]" total="[[total]]"></shop-cart>
+
+    <!-- checkout view -->
+    <shop-checkout
+        name="checkout"
+        cart="[[cart]]"
+        total="[[total]]"
+        route="{{subroute}}"></shop-checkout>
+  </iron-pages>
+            
+
+ +
+ +

Use the Polymer App Toolbox to build super-powered Progressive Web Apps. Try the Shop demo app to experience a Progressive Web App in action.

+ Try the demo + Build an app +
+
+
+
+ +
+
+

Browser Compatibility

+
The Polymer library and Polymer App Toolbox work in all major browsers (Chrome, Firefox, IE, Edge, Safari, and Opera).
+
+ chrome logo + firefox logo + internet explorer logo + edge logo + safari logo + opera logo +
+
+
+ +
+
+

Latest news

+
+ {% for item in articles[:3] %} +
+ {{{item.title}}} +

{{{item.description}}}

+
+ {% endfor %} +
+
+
+ +
+
+

Polymer at Google I/O 2016

+
+
+

In case you missed Google I/O or just want to relive the best bits in streaming HD, we've written a recap of Polymer goings-on and collected all of the Polymer-related sessions in one place. Enjoy!

+ Watch all + I/O 2016 recap +
+ +
+
+
+ +
+ + + + diff --git a/app/2.0/samples/test.html b/app/2.0/samples/test.html new file mode 100644 index 0000000000..b9671af52d --- /dev/null +++ b/app/2.0/samples/test.html @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/app/2.0/start/first-element/intro.md b/app/2.0/start/first-element/intro.md new file mode 100644 index 0000000000..6655199f27 --- /dev/null +++ b/app/2.0/start/first-element/intro.md @@ -0,0 +1,125 @@ +--- +title: "Step 1: Set up" +subtitle: "Build your first Polymer element" +--- + + + +In this tutorial, you’ll learn how to build elements using Polymer 1.0. You'll +create a simple Polymer element, a toggle button. The finished button will look +something like this: + +![Sample star-shaped toggle buttons, showing pressed and unpressed +state](/images/1.0/first-element/sample-toggles.png) + +You'll be able to use it with simple markup like this: + +```html + +``` + +This project introduces you to most of the key concepts in working with +Polymer. + +Don't worry if you don't understand everything. Each of the concepts presented +here is described in detail in the Polymer documentation. + + +## Step 1: Get set up + +To follow this tutorial, you'll need: + +- The starting code. +- The [Polymer CLI](/1.0/docs/tools/polymer-cli) to run the demo. + + +**Don't want to install anything?** To run through this tutorial online, +follow the instruction in [Step 1: No install version](#noinstall). +{ .alert .alert-info } + + +### Download the starting code + +1. Click the button to download the starting code as a ZIP file. + + + Download ZIP + + +2. Expand the archive to create your project folder. + + Your project folder should look something like + this: + +
+    README.md
+    bower.json
+    bower_components/
+    demo/
+    icon-toggle-finished/
+    icon-toggle.html
+    
+ + The main file you'll work with is `icon-toggle.html`, which contains the definition for your custom element. + + +### Install Polymer CLI. + +Install the Polymer CLI to serve the demo locally. + +1. Install the LTS version (4.x) of [Node.js](https://nodejs.org/en/download/). + The current version (6.x) should work, but is not officially supported. Versions + below LTS are not supported. + +2. Install [git](https://git-scm.com/downloads). + +3. Install the latest version of [Bower](http://bower.io/#install-bower). + + npm install -g bower + +4. Install Polymer CLI. + + npm install -g polymer-cli + +### Run the demo + +To run the element demo: + +1. Run `polymer serve` from the repo directory: + + polymer serve + +2. Open `localhost:8080/components/icon-toggle/demo/` in your browser. + + (Note that the path uses `icon-toggle`—the + component name listed in this element's `bower.json` file—rather than the actual directory name. + If you're wondering why `polymer serve` does this, see [HTML imports and dependency + management](/1.0/docs/tools/polymer-cli#element-imports).) + + You'll see some text where the icon toggles should appear. It doesn't look + very interesting, but it shows that everything is working. + + +Initial state of the demo. The demo shows three icon-toggle elements, two labeled 'statically-configured icon toggles' and one labeled 'data-bound icon toggle'. Since the icon toggles are not implemented yet, they appear as placeholder text reading 'Not much here yet'. + +**If this text doesn't appear**, make sure you're looking at the the demo folder itself, or at `demo/index.html`, +not at `toggle-icon.html` or `toggle-icon-demo.html`. +{ .alert .alert-info } + +If everything looks good, move on to [step 2](step-2). + +Step 2: Add local DOM + + + +## Step 1: No install version {#noinstall} + +To run through this tutorial online without installing anything: + +1. Open the [starter project on Plunker](https://plnkr.co/edit/QfsudzAPCbAu56Qpb7eB?p=preview){target="\_blank"}. + +2. Click **Fork** to create your own working copy. + +Continue to [step 2](step-2). + +Step 2: Add local DOM diff --git a/app/2.0/start/first-element/step-2.md b/app/2.0/start/first-element/step-2.md new file mode 100644 index 0000000000..a6e73c5105 --- /dev/null +++ b/app/2.0/start/first-element/step-2.md @@ -0,0 +1,241 @@ +--- +title: "Step 2: Add Local DOM" +subtitle: "Build your first Polymer element" +--- + +Next, you'll create a simple element that displays an icon. + +In this step, you'll learn about: + +* Creating a custom element using Polymer. +* Working with local DOM. + +_Local DOM_ is the set of DOM elements managed by your element. You'll learn more +about it in this section. + +**Local DOM? Shadow DOM?** If you're familiar with _shadow DOM_, a new proposed +web standard, local DOM is just a generic term for the same concept. Polymer's +local DOM works with or without native shadow DOM support. +{ .alert .alert-info } + +## Edit icon-toggle.html + +Open `icon-toggle.html `. This file contains the skeleton of a custom element. + +Unlike most HTML files, this file won't display anything if you load it in a +browser—it just defines a new element. The demo imports +`icon-toggle.html` so it can use the `` +element. As you add features to the element in the following steps, they'll show +up in the demo. + +Start by taking a look at the existing code: + + +Starting code—HTML imports { .caption } + +```html + + +``` + +Key information: + +* The `link rel="import"` element is an HTML import, a new + way of including resources in an HTML file. +* These lines import the Polymer library and another custom element called + `iron-icon` that you'll use later in this step. + +**Learn more: HTML Imports.** See [HTML Imports: #include for the web](http://www.html5rocks.com/en/tutorials/webcomponents/imports/) +on HTML5Rocks.com for an in-depth discussion of HTML Imports. +{ .alert .alert-info } + +Next is the definition of the element itself: + +Starting code—local DOM template { .caption } + +```html + + +``` + +Key information: + +* The `` tag wraps an element's local DOM definition. + In this case, the `id` attribute shows that this module includes the + local DOM for an element called `icon-toggle`. +* The `