diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..7b6fd3ae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing to Polymer + +There are many ways to contribute to the Polymer project! We welcome and truly appreciate contribution in all forms - issues and pull requests to the [main library](https://github.com/polymer/polymer), issues and pull requests to the [elements the Polymer team maintains](https://github.com/polymerelements), issues and pull requests to one of our many [Polymer-related tools](https://github.com/polymer), and of course we love to hear about any Polymer elements that you build to share with the community! + +# Logistics + +## Communicating with the Polymer team + +Beyond Github, we try to have a variety of different lines of communication open: + +* [Blog](https://blog.polymer-project-org) +* [Twitter](https://twitter.com/polymer) +* [Google+ Community](https://plus.sandbox.google.com/u/0/communities/115626364525706131031?cfem=1) +* [Mailing list](https://groups.google.com/forum/#!forum/polymer-dev) +* [Slack channel](bit.ly/polymerslack) + +## The Polymer Repositories + +Because of the component-based nature of the Polymer project, we tend to have lots of different repositories. Our main repository for the Polymer library itself is at [github.com/Polymer/polymer](https://github.com/polymer/polymer). File any issues or pull requests that have to do with the core library on that repository, and we'll take a look ASAP. + +We keep all of our element "product line" repos in the [PolymerElements](https://github.com/polymerelements) organization. For any element-specific issues or pull requests, file directly on the element's repository, such as the `paper-button` repository at [github.com/polymerelements/paper-button](https://github.com/polymerelements/paper-button). + +The GoogleWebComponents element product line is maintained by teams all across Google, and so is kept in a separate organization: the [GoogleWebComponents](https://github.com/googlewebcomponents) org. Feel free to file issues and PR's on those elements directly in that organization. + +We also track each element product line overall in "meta-repos", named as `$PRODUCTLINE-elements`. These include [paper-elements](https://github.com/polymerelements/paper-elements), [iron-elements](https://github.com/polymerelements/iron-elements), [gold-elements](https://github.com/polymerelements/gold-elements), and more. Feel free to file issues for element requests on those meta-repos, and the README in each repo tracks a roadmap for the product line. + +## Contributor License Agreement + +You might notice our friendly CLA-bot commenting on a pull request you open if you haven't yet signed our CLA. We use the same CLA for all open-source Google projects, so you only have to sign it once. Once you complete the CLA, all your pull-requests will automatically get the `cla: yes` tag. + +If you've already signed a CLA but are still getting bothered by the awfully insistent CLA bot, it's possible we don't have your GitHub username or you're using a different email address. Check the [information on your CLA](https://cla.developers.google.com/clas) or see this help article on [setting the email on your git commits](https://help.github.com/articles/setting-your-email-in-git/). + +[Complete the CLA](https://cla.developers.google.com/clas) + +# Contributing + +## Filing bugs + +The Polymer team heavily uses (and loves!) Github for all of our software management. We use Github issues to track all bugs and features. + +If you find an issue, please do file it on the repository. The [Polymer/polymer issues](https://github.com/polymer/polymer/issues) should be used only for issues on the Polymer library itself - bugs somewhere in the core codebase. + +For issues with elements the team maintains, please file directly on the element's repository. If you're not sure if a bug stems from the element or the library, air toward filing it on the element and we'll move the issue if necessary. + +We love examples for addressing issues - issues with a Plunkr, jsFiddle, or jsBin will be much easier for us to work on quickly. + +Occasionally we'll close issues if they appear stale or are too vague - please don't take this personally! Please feel free to re-open issues we've closed if there's something we've missed and they still need to be addressed. + +## Contributing Code to Elements + +Though the aim of the Polymer library is to allow lots of flexibility and not get in your way, we work to standardize our elements to make them as toolable and easy to maintain as possible. + +All elements should follow the [Polymer element style guide](http://polymerelements.github.io/style-guide/), which defines how to specify properties, documentation, and more. It's a great guide to follow when building your own elements as well, for maximum standardization and toolability. For instance, structuring elements following the style guide will ensure that they work with the [`iron-component-page`](https://github.com/polymerelements/iron-component-page) element, an incredibly easy way to turn any raw element directly into a documentation page. + +## Contributing Code to the Polymer library + +We follow the most common javascript and HTML style guidelines for how we structure our code - in general, look at the code and you'll know how to contribute! If you'd like a bit more structure, the [Google Javascript Styleguide](https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml) is a good place to start. + +Polymer also participates in Google's [Patch Rewards Program](http://www.google.com/about/appsecurity/patch-rewards/), where you can earn cold, hard cash for qualifying security patches to the Polymer library. Visit the [patch rewards page](http://www.google.com/about/appsecurity/patch-rewards/) to find out more. diff --git a/README.md b/README.md index 36fe233e..f5eb7d2f 100644 --- a/README.md +++ b/README.md @@ -1,328 +1,175 @@ -# Polymer 0.9 - Beta +# Polymer -## From The Ground Up +Polymer lets you build encapsulated, re-usable elements that work just like HTML elements, to use in building web applications. -Let us begin this tale with a short stroll through the layers that Polymer is -built upon, and some of the rationale of how we got there. + + -### Raw Custom Elements + <1-- Import element --> + -Custom Elements are a powerful emerging web standard that allows developers to create their own elements by attaching a class to a tag-name. + + -#### document.registerElement -The native API is very simple, it looks something like this: - -```js -document.registerElement(, {prototype: Object[, extends: String]}); -``` - -#### Typical Boilerplate - -There is a little bit of work one has to do to set up the class with the right prototypes and so on to construct a Custom Element. Here is an typical example (using ES5 syntax): - -```js -var ctor = function() { - return document.createElement('x-custom'); -}; -ctor.prototype = Object.create(HTMLElement.prototype); -ctor.prototype.constructor = ctor; -ctor.prototype.createdCallback = function() { - this.innerHTML = 'Hello World, I am a Custom Element!'; -} -document.registerElement('x-custom', ctor); -``` - -### Reluctant Polymer() Abstraction - -By principle, Polymer team tries to avoid abstracting DOM APIs, especially new ones. But in this case we finally decided the ergonomic benefit was worth it. By wrapping `registerElement` in our own function, we can reduce the above boilerplate to: - -```js -var ctor = Polymer({ - is: 'x-custom', - created: function() { - this.innerHTML = 'Hello World, I am a Custom Element!'; - } -}); -``` - -### Polymer() Does a Bit More - -You might notice the `Polymer()` invocation defines `created` instead of `createdCallback`. This is a feature of `Polymer.Base`, a tiny prototype that `Polymer()` adds to your prototype chain as it's handling the boilerplate above. `Polymer.Base` hooks the standard Custom Element lifecycle callbacks to provide helper implementations. The hooks in turn call shorter-named lifecycle methods on your prototype. - -- `created` instead of `createdCallback` -- `attached` instead of `attachedCallback` -- `detached` instead of `detachedCallback` -- `attributeChanged` instead of `attributeChangedCallback` - -You can always fallback to using the low-level methods if you wish (iow, you could simply implement `createdCallback` in your prototype). - -`Polymer.Base` also implements `registerCallback` on your prototype. `Polymer()` calls `registerCallback` which allows `Polymer.Base` to supply a layering system for Polymer abstractions so that no element needs to pay for features it doesn't use. - -## Features - -By default, the default Polymer distribution include several features. Although `Polymer.Base` itself is tiny, if you examine `Polymer.Base` you will probably see several methods that have been plugged-in to that prototype by feature definitions. The next few sections will explain these features and why we include them in the default set. Keep in mind that it's entirely possible to construct custom feature sets, or even use a trivial, featureless form of `Polymer()`. - -### Feature: _property-config_ - -The first feature implements support for the `properties` property. By placing a object-valued `properties` property on your prototype, let's you define various aspects of your custom-elements public API. - -By itself, the `properties` feature **doesn't do anything**. It only provides API for asking questions about these special properties (see [link to docs] for details). +## Getting Started + +Check out [polymer-project.org](https://www.polymer-project.org) for all of the library documentation, including getting started guides, tutorials, developer reference, and more. + +Or if you'd just like to download the library, check out our [releases page](https://github.com/polymer/polymer/releases). + +## Polymer in 1 Minute + +The Polymer library is a lightweight sugaring layer on top of the [web components](http://webcomponents.org/articles/why-web-components/) API's to help in building your own web components. It adds convenient features to make it easy to build complex elements: + +**Create and register a custom element** ```js +/** + * A not-very-useful inline element + */ Polymer({ - - is: 'x-custom', - - properties: { - user: String, - isHappy: Boolean, - count: { - type: Number, - readOnly: true, - notify: true - } - }, - - created: function() { - this.innerHTML = 'Hello World, I am a Custom Element!'; - } - + is: 'my-element' }); ``` -Remember that the fields assigned to `count`, such as `readOnly` and `notify` don't do anything by themselves, it requires other features to give them life. +```html + + +``` -### Feature: _attributes_ +**Add markup to your element** -Many custom elements want to support configuration using HTML attributes. Custom Elements provides the `attributeChanged` callback gives us the raw API for this ability, but then we have to deal with initialization and type conversion (attributes are always strings). Here is an example of a custom element that supports a `user` attribute using the raw API. +```html + + +
+ Hi! My name is Jane +
+ + + +``` + +**Configure properties on your element...** ```js - Polymer({ - - is: 'x-custom', - - created: function() { - // handle any initial value - this.attributeChanged('user'); - // render - this.innerHTML = 'Hello World, my user is ' + (this.user || 'nobody') + '.'; - }, - - attributeChanged: function(name) { - switch(name) { - case 'user': - // pretty easy since user is a String, for other types - // we have to do more work - if (this.hasAttribute('user')) { - this.user = this.getAttribute('user'); - } - break; - } - } - - }); -``` - -Although it's relatively simple, having to write this code becomes annoying when working with multiple attributes or non-String types. It's also not very DRY. - -Instead, Polymer's `attributes` feature handles this work for you (using the `properties` feature data). If an attribute is set that matches a property listed in the `properties` object, the value is captured into the matching property. Strings are automatically converted to the specified type. - -The type system includes support for Object values expressed as JSON, or Date objects expressed as any Date-parsable string representation. Boolean properties are mapped to Boolean attributes, in other words, if the attribute exists at all, its value is true, regardless of its string-value (and the value is only false if the attribute does not exist). - -Here is the equivalent of the above code, taking advantage of the `attributes` feature. - -```html - - - +}); ``` -### [ToDoc] attributes:hostAttributes - -### Feature: _template_ - -HTML templates are an emerging web standard that we like to consider part of the Web Components family. Templates are a great way to provide archetypal DOM content for your custom element, and this is where the `template` feature comes in. - -As usual, we started by writing basic template support by hand. It generally looks something like this: +**...and have them set using declarative attributes** ```html - - - + + ``` -Again, it's simple, but it's a common pattern, so the `template` feature does it automatically. By default it looks for a template as the first element before the script, so our code can look like this: +> Hi! My name is Jim. + +**Bind data into your element using the familiar mustache-syntax** ```html - - - + + ``` -### Feature: _annotations_ - -Most elements need to customize the DOM instanced from a template. For this reason, it's handy to encode markers into your template to indicate special nodes, attributes, or text. Polymer calls these markers _annotations_. The `annotations` feature scans the template (once per element, at registration time) and builds a data-structure into the prototype that identifies markers it finds in the DOM (see [link to docs] for details). Normally you do not need to work with this data directly, Polymer does it for you. - -### Feature: _annotations-nodes_ - -Traditionally, modifying DOM is done by querying for elements to manipulate. Here is an example: - ```html - - - + + ``` -This example is very simple. But in real projects, repeating queries is inefficient, so query results are often stored (memoized). Also, as DOM composition becomes more tricky, crafting correct queries can be difficult. For these reasons, automatically capturing nodes makes a good feature. +> Hi! My name is Josh. -The `annotations-nodes` feature builds a map of instance nodes by `id` in `this.$` (using the `annotations` feature data). Here is how the `annotations-nodes` feature simplifies the above example. +**Style the internals of your element, without the style leaking out** ```html - - - + + ``` -### Feature: _annotations-events_ - -Most elements also need to listen for events. The standard DOM method `addEventListener` provides the low-level support: - ```html - - - + + ``` -Again, this is pretty simple, but it's so common that it's worth making even simpler. The `annotations-events` feature supports declaring event listeners directly in our template. +> Hi! My name is **Jesse** -Declaring listeners in the template is convenient, and also helps us decouple view from behavior. +**and so much more!** -```html - +* Built from the platform up +* Self-contained +* Don't require an overarching framework - are interoperable across frameworks +* Re-usable - -``` - -Notice that the `kickAction` method doesn't know anything about `button`. If we decided that kicking should be performed by a key-press, or a menu-item, the element code doesn't need to know. We can change the UI however we want. Also notice that by attaching the event declaratively, we have removed the need to give the button an id. - -### [ToDoc] events feature - -### [ToDoc] keys feature - -### [ToDoc] content feature +* [Blog](https://blog.polymer-project-org) +* [Twitter](https://twitter.com/polymer) +* [Google+ Community](https://plus.sandbox.google.com/u/0/communities/115626364525706131031?cfem=1) +* [Mailing list](https://groups.google.com/forum/#!forum/polymer-dev) +* [Slack channel](bit.ly/polymerslack) +# License +The Polymer library uses a BSD-like license available [here](./polymer/blob/master/LICENSE.txt)