Repository files navigation

This guide serves as an extension to theGoogle JavaScript Style Guide with additional style guidance around authoring Web Components, particuarly those inthis element collection. It is targeted at Google engineers, but may be useful for others too :)

• All elements should useseed-element as a starting point. This provides a clean base for authoring elements that arereusable. It includes acomponent page for documentation and a setup forunit-testing.
• Where possible try to follow theSRP (Single-responsibility principle) &first for elements you are authoring. “Do one thing and do it well”.
• Extend existing elements over re-implementing functionality yourself. Alternatively, reuse base components (e.g.<google-client-api>) in your own.
• Ensure your element, methods, events, attributes, and properties arewell documented.
• Use@attribute,@property,@method,@event to document the API for your element.
• Ensure any styling hooks or accepted light DOM are documented in the element summary.
• Follow the Web Componentbest practices guide where possible.
• Ensure your elements areaccessible from the get-go.
• In your bower.json, depend on a specific version of Polymer (e.g. "polymer": "Polymer/polymer#~0.4.0")

• Elements should contain a dash in their name (e.g<my-tabs> vs<tabs>), per the Custom Elementspecification,
• Google elements should be prefixed with “google” (e.g<google-sheets> vs<g-sheets>).
• Where multiple words are required for the name, they should be separated with a dash (e.g<google-street-view-pano> vs<google-streetviewpano>) for readability.
• Unless for private use, elements should use a unique name to avoid clashing withexisting elements.

• Published attributes should be camel-cased where multiple words are in use.
• Provide sensible default values as part of your API if values will be bound and displayed anywhere in your template. Default property values in attributes are null.
• Use@default and@required for parameters that either have a default value or are required.

• Event names should have a prefix strongly related to the name of the element in use (e.gdrive-upload-success vsupload-succeeded). This allows you to drop in multiple elements in the page without event namespacing clashing.
• It’s fine to simplify things a bit if your element name is complex, as long as the relationship is unambiguous (e.g., for a load event on a<google-client-api-loader> element, usegoogle-client-api-load instead ofgoogle-client-api-loader-load).
• A unique event name should be fired for unique actions in your element that will be of interest to the outside world.
• Events should either end in verbs in the infinitive form (e.g.google-client-api-load) or nouns (e.ggoogle-drive-upload-success).
• Use declarative event handlers over JS based (e.g. don't writeaddEventListener in your element code).

• Do not use $ to prepend your own object properties and variables. Consider this style of naming reserved for use by Polymer and jQuery. Polymer allows you to use$.* within<template> andthis.$.* within script to access the content of element children.
• Define constants outside of thePolymer() constructor, wrapped in an anonymous self-executing function.
• If you need to define private or static variables, wrap your script usingstandard techniques like anonymous self-calling functions.

• Methods should be camel-cased where multiple verbs/words are in use (e.gselectFile() vsselectfile()).

• <seed-element> has a setup using Mocha and Chai that should be adapted to exercise your own element’s functionality. Examples of existing tests written by the Polymer team can be found incore-tests.

• Assets such as icons, graphics and other forms of media should live inside anassets directory. One example of an element that does this isyt-video.
• Assets should be optimized (e.g using tools such asImageOptim) to minimize the size of resources package consumers need to download.

• Where possible, useon-tap instead ofon-click to benefit from additional help provided for touch screens
• Avoid using the<template> tag inside<table>,<select> and other potentially problematic native elements documented in theFAQ.
• Avoid excluding the outer<template> when attempting to use a conditional or repeat template
• Avoid binding to native attributes that can cause issues. See the Polymerdata-binding docs for more information.
• Be careful when placing content inside the<shadow> element. This will not render.

Note, that this section is mostly relevant to Google engineers working on elements and follows current requirements around open-source projects.

• As with other open source code that Google releases, use the Apache 2.0 license.
• Include aLICENSE file at the top level of your project.
• Include a copyright comment in yourdemo.html file.
• Include"license": "Apache-2.0" in yourbower.json.