We intend to migrate the WebUI in Chromium to implement the
material design spec. This document explains the technical aspects of our approach and serves as a landing page for resources used by developers working on this migration.
Questions can be submitted to the chromium-polymer Google group, but general Polymer questions are better answered at polymer-dev@googlegroups.com.
This CL demonstrates the addition of a new WebUI page that uses Polymer components.
Working with Polymer elements
Importing new Polymer elements
In order to make use of Polymer elements in WebUI, they must first be added to Chromium.
To add a Polymer component not already in Chromium:
- Add the element to
third_party/polymer/v1_0/bower.json:
"iron-icon": "PolymerElements/iron-icon#~1.0.0"
Also add all of the component's dependencies (listed in its bower.json. We list all dependencies explicitly to prevent accidental additions of other third-party libraries.
- From
third_party/polymer/v1_0, run reproduce.sh. See the README
for more details.
- If the element needs to be built into Chrome (as opposed to elements only used for demos), use tools/polymer to add the necessary
.css, .extracted-js and .html files to ui/webui/resources/polymer_resources.grdp:
tools/polymer/polymer_grdp_to_txt.py ui/webui/resources/polymer_resources.grdp > polymer.txt
vim polymer.txt # add iron-icon/iron-icon.html, etc.
tools/polymer/txt_to_polymer_grdp.py polymer.txt > ui/webui/resources/polymer_resources.grdp
git diff ui/webui/resources/polymer_resources.grdp # verify changes
Once the resources are added to Chrome, they can be included from another HTML page via chrome://resources:
<link rel="import"
href="chrome://resources/polymer/v1_0/iron-icon/iron-icon.html">
Adding custom elements
Find the appropriate place for the new element. For example, elements within the "settings" namespace use chrome/browser/resources/settings.
Separate HTML and JS into their own files instead of using inline scripts to ensure elements will work under
CSP.
Add the element's resources to the appropriate .grd file. Do not include demo files.
Sharing Polymer elements
Polymer elements intended to be shared across WebUI reside in src/ui/webui/resources/cr_elements.
New WebUI pages implementing material design should make use of these elements when convenient.
Localization
Prefer C++-side $i18n{key} templating. When necessary, use I18nBehavior to dynamically translate strings in JS.
Accessibility
Polymer elements provide their own ARIA roles and labels, and a11y support should be improving soon in Polymer 1.0. Custom elements can also provide their own ARIA roles and labels when necessary.
Shadow DOM is already supported in some screen readers, such as OS X's VoiceOver and Chrome OS's
ChromeVox Next.
As with light DOM, the shadow DOM tree can be explored from chrome://accessibility.
Compilation
Testing
We also want to be able to perform visual testing to check for regressions in element layout and looks.
Clients
WebUI pages implementing material design:
