Skip to content

Commit

Permalink
Removing navgroup cruft
Browse files Browse the repository at this point in the history
  • Loading branch information
ebidel committed Nov 18, 2014
1 parent 2901fd5 commit b25b561
Show file tree
Hide file tree
Showing 61 changed files with 388 additions and 450 deletions.
2 changes: 1 addition & 1 deletion _layouts/default.html
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
</app-drawer>

<scroll-area sidebar unresolved>
<site-banner type="{{page.type}}" navgroup="{{page.navgroup}}" shortname="{{page.shortname}}" unresolved>
<site-banner type="{{page.type}}" shortname="{{page.shortname}}" unresolved>
{% include top-nav.html %}
<header>
<h1>{{page.title}}</h1>
Expand Down
25 changes: 12 additions & 13 deletions articles/accessible-web-components.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Articles
title: "Accessible Web Components - Part 1"
subtitle: Improving the accessibility of Web Components
Expand Down Expand Up @@ -39,21 +38,21 @@ When designing for accessibility, there are four key areas of disability to cons

* Ensure all user interface elements can be used with assistive technologies such as screen readers, magnifiers and braille displays. This entails ensuring that elements are marked up such that accessibility APIs can programmatically determine the *role*, *state*, *value* and *title* of any element.

**Hearing** issues mean a user may have issues hearing sound emitted from a page.
**Hearing** issues mean a user may have issues hearing sound emitted from a page.

* Make the content understandable using [text alternatives](http://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt) for all content that is not strictly text.
* Make the content understandable using [text alternatives](http://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt) for all content that is not strictly text.

* Ensure you test that your elements are still functional [without sound](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#content-structure-separation-understanding).

**Mobility** issues can include the inability to operate a mouse, a keyboard or touch-screen.
**Mobility** issues can include the inability to operate a mouse, a keyboard or touch-screen.

* Make the content of your elements [functionally accessible from a keyboard](http://www.w3.org/TR/wai-aria-practices/#keyboard) for any actions one would otherwise use a mouse for.

* Ensure user interface elements are correctly marked up for assistive technologies; these users may use technologies such as voice control software and physical switch controls, which tend to use the same APIs as other assistive technologies like screen readers.

**Cognitive** issues mean a user may require assistive technologies to help them with reading text, so it’s important to ensure text alternatives exist.
**Cognitive** issues mean a user may require assistive technologies to help them with reading text, so it’s important to ensure text alternatives exist.

* Avoid a visual presentation that is [repetitive](http://www.w3.org/TR/WCAG20/#time-limits) or flashing as this can cause some users [issues](http://www.w3.org/TR/WCAG20/#seizure).
* Avoid a visual presentation that is [repetitive](http://www.w3.org/TR/WCAG20/#time-limits) or flashing as this can cause some users [issues](http://www.w3.org/TR/WCAG20/#seizure).

* Avoid interactions that are timing-based.

Expand All @@ -79,13 +78,13 @@ Native controls (such as `<button>` and `<select>`) have accessibility built-in

Custom elements (with the exception of elements that extend native elements like `<button>`) do not have any built-in functionality, including accessibility, so this needs to be provided by you. A good place to start when implementing accessibility is to compare your custom element to an analogous native element (or a combination of several native elements, depending on how complex your component is).

The following is a list of questions you can ask yourself when attempting to make your custom elements more accessible.
The following is a list of questions you can ask yourself when attempting to make your custom elements more accessible.

### Can your element be used with the keyboard alone?
### Can your element be used with the keyboard alone?

Ideally, ensure that all functionality in your element can be reached by a keyboard. During your UX design, think about how you would use your element with the keyboard alone, and figure out a consistent set of keyboard interactions.
Ideally, ensure that all functionality in your element can be reached by a keyboard. During your UX design, think about how you would use your element with the keyboard alone, and figure out a consistent set of keyboard interactions.

Firstly, ensure that you have a sensible **focus** target for each element. For example, a complex element like a menu may be one focus target within a page, but should then manage focus within itself so that the active menu item always takes focus.
Firstly, ensure that you have a sensible **focus** target for each element. For example, a complex element like a menu may be one focus target within a page, but should then manage focus within itself so that the active menu item always takes focus.

![Menu displaying how to manage focus](/articles/images/accessible-web-components/image_0.png)

Expand Down Expand Up @@ -136,7 +135,7 @@ Any element which displays an image should provide a mechanism for providing alt

Assistive technology conveys semantic information which is otherwise expressed to sighted users via visual cues such as formatting, cursor style, or position. Native elements have this semantic information built-in by the browser, but for custom elements you need to use [ARIA](http://www.w3.org/WAI/PF/aria/) to add this information in.

One technology which is critical for custom element accessibility is [WAI-ARIA](http://www.w3.org/WAI/PF/aria/). ARIA is a specification defining support for accessible web apps. It defines markup extensions (implemented as attributes on elements), which can be used to provide additional information about the semantics of elements to assistive technologies like screen readers.
One technology which is critical for custom element accessibility is [WAI-ARIA](http://www.w3.org/WAI/PF/aria/). ARIA is a specification defining support for accessible web apps. It defines markup extensions (implemented as attributes on elements), which can be used to provide additional information about the semantics of elements to assistive technologies like screen readers.

As a rule of thumb, any element which listens to a mouse click or hover event should not only have some kind of keyboard event listener, but also an ARIA role and potentially ARIA states and attributes.

Expand All @@ -156,7 +155,7 @@ Color shouldn’t be used as the only means of conveying information, such as in

Any text content displayed in your element should meet the [minimum (AA) contrast bar](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast-contrast). Consider providing a high-contrast theme which meets the [higher (AAA) bar](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast7), and also ensure that user agent style sheets can be applied if users require extreme contrast or different colors. You can use this [Color Contrast Checker](http://webaim.org/resources/contrastchecker/) as an aid when doing design.

### Is the moving or flashing content in your elements stoppable and safe?
### Is the moving or flashing content in your elements stoppable and safe?

Content that moves, scrolls or blinks that lasts for anything more than 5 seconds should be able to be paused, stopped or hidden. In general, try to flash no more than three times per second.

Expand Down
15 changes: 7 additions & 8 deletions articles/communication.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Articles
title: "Communication & Message Passing"
subtitle: Common techniques for sharing information between custom elements
Expand Down Expand Up @@ -50,7 +49,7 @@ We'll cover the following techniques:
1. [Data binding](#binding)
1. [Changed watchers](#changedwatchers)
1. [Custom events](#events)
1. [Using an element's API](#api)
1. [Using an element's API](#api)

### 1. Data binding {#binding}

Expand Down Expand Up @@ -114,7 +113,7 @@ When a {{site.project_title}} element [publishes](/docs/polymer/polymer.html#pub
`<td-model>.items` and `<core-localstorage>.value` are bound together with "list":

{% raw %}
<td-model items="{{list}}"></td-model>
<td-model items="{{list}}"></td-model>
<core-localstorage name="myapplist" value="{{list}}"></core-localstorage>
{% endraw %}

Expand Down Expand Up @@ -271,7 +270,7 @@ a user of `<say-hello>` can setup a handler for the event:

As with normal DOM events outside of {{site.project_title}}, you can attach additional data to a custom event. This makes **events an ideal way to distribute arbitrary information to other elements**.

**Example:** include the `name` property as part of the payload:
**Example:** include the `name` property as part of the payload:

sayHi: function() {
this.fire('said-hello', {name: this.name});
Expand Down Expand Up @@ -348,7 +347,7 @@ Things become very interesting when several elements need to respond to an event
first: function(e, detail, sender) {
logger('first():', detail, sender);
},
second: function(e, detail, sender) {
second: function(e, detail, sender) {
logger('second():', detail, sender);
},
third: function(e, detail, sender) {
Expand Down Expand Up @@ -398,7 +397,7 @@ sibling or child elements. That is:
When `<say-hello>` fires `said-hello`, it bubbles and `sayHi()` handles it.
However, suppose `<say-bye>` has setup an internal listener for the same event.
It wants in on the action! Unfortunately, this means we can no longer exploit
the benefits of event bubbling...by itself.
the benefits of event bubbling...by itself.

This particular problem isn't new to the web but you can easily handle it in
{{site.project_title}}. Just use event delegation and manually fire the event
Expand Down Expand Up @@ -492,7 +491,7 @@ other frameworks for a long time, so technically it's not a new concept.
Whether you're inside or outside a `<polymer-element>`, there are plenty of
ways to send instructions/messages/data to other web components. Hopefully,
you're seeing that nothing has changed in the world of custom elements. That's
the point :) It's the same web we've always known...just more powerful!
the point :) It's the same web we've always known...just more powerful!

<script>
(function() {
Expand Down
13 changes: 6 additions & 7 deletions articles/concatenating-web-components.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Articles
title: "Concatenating Web Components with Vulcanize"
subtitle: Reduce network requests by flattening HTML Imports
Expand All @@ -25,7 +24,7 @@ tags:

We all know that reducing network requests is important. In the {{site.project_title}} world, [Vulcanize](https://github.com/Polymer/vulcanize) is the name given to a build tool that lets you **concatenate** a set of elements and their HTML imported dependencies into a single file. If your app has lots of top-level imports, consider squashing them into a single file and importing it instead!

Vulcanize recursively pulls in all your imports, flattens their dependencies and spits out something that can potentially **reduce the number of network requests** your app makes.
Vulcanize recursively pulls in all your imports, flattens their dependencies and spits out something that can potentially **reduce the number of network requests** your app makes.

In the future, we will hopefully have the tech to do away with needing Vulcanize using advanced HTTP techniques (e.g HTTP 2.0). In the mean time, it's an excellent tool for cutting down on the network requests made by your {{site.project_title}} apps.

Expand All @@ -52,7 +51,7 @@ The output file can be specified using the `--output` or `-o` flag:

vulcanize -o build.html index.html

No additional configuration is necessary. build.html now contains a version of index.html with all imports inlined and dependencies flattened. Paths to any URLs are automatically adjusted for the new output location, with the exception of those set in JavaScript.
No additional configuration is necessary. build.html now contains a version of index.html with all imports inlined and dependencies flattened. Paths to any URLs are automatically adjusted for the new output location, with the exception of those set in JavaScript.

If no output is specified, vulcanized.html is used by default.

Expand Down Expand Up @@ -132,7 +131,7 @@ Inline the imported requests with the `--inline` flag.

vulcanize -o build.html index.html --inline

Vulcanize also supports the opposite of this process, extracting inline scripts to external files for the purposes of CSP.
Vulcanize also supports the opposite of this process, extracting inline scripts to external files for the purposes of CSP.

## Content Security Policy

Expand Down Expand Up @@ -220,13 +219,13 @@ For more information on how to configure the `grunt-vulcanize` task, read the [o

### Is concatenation a good idea?

This depends on how large your application is. Excessive requests are often far worse than filesize. Hypothetically, let's say you have 20 HTML files/imports of 0.5MB each. Out of which only 2 (1MB) are required on the first page. You might want to keep them separate and combine others or load others in a deferred mode while on the first page.
This depends on how large your application is. Excessive requests are often far worse than filesize. Hypothetically, let's say you have 20 HTML files/imports of 0.5MB each. Out of which only 2 (1MB) are required on the first page. You might want to keep them separate and combine others or load others in a deferred mode while on the first page.

Some of the things that you should think about before combining a large number of imports are when you combine 100 files together, you're cutting down on 99 requests, but you're also doing the following:

* Increasing how long it takes to download that single file (and potentially block loading of an important page)

* Accounting for the additional time spent parsing and rendering that additional code we just pulled from the server, which may not be required at this point.
* Accounting for the additional time spent parsing and rendering that additional code we just pulled from the server, which may not be required at this point.

The short answer is "don't guess it, test it". There is always a trade-off when it comes to concatenation but tools like [WebPageTest](http://webpagetest.org) can be useful for determining what your true bottlenecks are.

Expand Down
15 changes: 7 additions & 8 deletions articles/distributing-components-with-bower.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Articles
title: "Distributing Components With Bower"
subtitle: How to package your elements for broader sharing
subtitle: How to package your elements for broader sharing

article:
author: addyosmani
Expand Down Expand Up @@ -47,7 +46,7 @@ Run `bower init` to generate a valid bower.json manifest to lock down your proje
[?] name: polymer-demo
[?] version: 0.0.1
[?] description: An awesome {{site.project_title}} element
[?] main file:
[?] main file:
[?] keywords: {{site.project_title}}, web-components
[?] authors: John Smith
[?] license: MIT
Expand Down Expand Up @@ -85,7 +84,7 @@ This will produce a bower.json file containing something like:

### 2. Adding the Polymer dependencies {#add-dependencies}

Next, you will want to install webcomponents.js (the Web Component polyfills) and polymer.html so that your {{site.project_title}} elements can consume them. This can be done by running the following one-liner:
Next, you will want to install webcomponents.js (the Web Component polyfills) and polymer.html so that your {{site.project_title}} elements can consume them. This can be done by running the following one-liner:

bower install --save polymer

Expand Down Expand Up @@ -150,9 +149,9 @@ Your element should now be available on the [bower registry](http://bower.io/sea

### How do I install Bower? {#bower-install}

Bower depends on [Node](http://nodejs.com) and [npm](http://npmjs.org) and is generally used via the command-line.
Bower depends on [Node](http://nodejs.com) and [npm](http://npmjs.org) and is generally used via the command-line.

You can download and install Node from [nodejs.org](http://nodejs.org). npm comes bundled with each binary package, so when you install Node, npm should automatically be installed at the same time. You’ll also need to have Git installed, as Bower uses Git endpoints to locate packages. If you don’t have Git installed, you can download it from [http://git-scm.com/downloads](git-scm.com/downloads).
You can download and install Node from [nodejs.org](http://nodejs.org). npm comes bundled with each binary package, so when you install Node, npm should automatically be installed at the same time. You’ll also need to have Git installed, as Bower uses Git endpoints to locate packages. If you don’t have Git installed, you can download it from [http://git-scm.com/downloads](git-scm.com/downloads).

You can then install Bower using npm:

Expand All @@ -176,7 +175,7 @@ To list what packages you have installed in the current project, pass the `list`

This won’t display any information until a package has been installed, but you can do this with the `install` command:

bower install {{site.project_title}}/platform
bower install {{site.project_title}}/platform

Uninstalling packages is just as easy as installing them. In this case we use the `bower uninstall` command.

Expand Down
3 changes: 1 addition & 2 deletions articles/index.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Docs
title: Articles
subtitle: Core concepts of build apps on top of Polymer and web components
Expand Down
3 changes: 1 addition & 2 deletions articles/polymer-xtag-vanilla.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Articles
title: "Custom Element Interoperability"
subtitle: Using Polymer, X-Tag, and Vanilla Custom Elements
Expand Down
3 changes: 1 addition & 2 deletions articles/spa.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
layout: default
type: core
navgroup: docs
type: guide
shortname: Articles
title: "Building single page apps using web components"
subtitle: The Polymer approach to building single page applications
Expand Down
Loading

0 comments on commit b25b561

Please sign in to comment.