For example, how do you deal with ::-webkit-distributed under polyfill (@polyfill)?

What about polymer-scope="global" etc.

Which features are implemented in which browsers natively, with shim, with polyfill, or unsupported.

Article discussion approaches for writing a custom element that contains
multiple <template>. The internal "view" updates based on an attribute change.

The architecture diagram is very information rich, but it's hard to digest at first.

We should consider having a page that walks people through our architecture, introducing each layer one a time like we did in the I/O session. That would allow us to call out details like 3rd party frameworks/component sets interoperating.

• this.fire()
• Using their public api
• data binding attributes on the same property

* Use MDV data binding w/ published properties: like a bus*

(the approach TodoMVC uses)

<element name="my-app">
<template>
  <td-model items="{{items}}"></td-model>
  <polymer-localstorage value="{{items}}"></polymer-localstorage>
  <div>{{items}}</div>
</template>
</element>

This is great if you're in a Polymer element and want to "link" elements together via a binded property. When <td-model> updates its internal array, other elements that bind to its published "items" property see those changes. Essentially, you've put "items" on a bus, internal to <my-app>.

*_Use _Changedwatchers`

Instead, say <polymer-localstorage> didn't publish "value" and we didn't have that attribute to bind to. In this case, you could setup a *Change watcher.

<template>
  <td-model items="{{items}}"></td-model>
  <polymer-localstorage id="storage"></polymer-localstorage>
</template>
<script>
  Polymer.register(this, {
    itemsChanged: function() {
      // TODO: tell this.$.storage something has changed.
    }
  });
</script>

Fire custom events

Custom events bubble up. You can use an event delegation
scheme by declaring a on-* handler on your outer most <element>.
I call this method as the air traffic controller.

<element name="my-element">
  <template>Hello</template>
  <script>
    Polymer.register(this, { ready: function() { this.asyncFire('myevent'); } });
  </script>
</element>

<element name="my-app" on-myevent="doMyEvent">
  <template>
    <my-element></my-element>
  </template>
  <script>
    Polymer.register(this, {
      doMyEvent: function(e, details, sender) {
        console.log(e.type, details, sender);
        // TODO: act on this.
      }
    });
  </script>
</element>

http://jsbin.com/ekahug/4/edit

We currently have sample components in /samples/components/ which are duplicated in _includes/samples/ for including into the docs. Unfortunately, Jekyll only allows you to include partials that are under _includes.

The ones in /samples/components/ are used for live samples.

One way around this would be to great a samples repo and submodule it into _includes
as well as the main folder.

toolkit.js now automatically pulls in platform.js. We need to update the docs to reflect this.

Yehuda pointed out that the architecture diagram makes it look kind of like MDV isn't required in polymer.js, because the edge of the polymer.js block and the MDV polyfill block happen to align. Taking them out of alignment a bit should help.

Why it's implemented this way; what we learned from exploring the technologies. Footsteps for other toolkits to follow in, and beginning place for web component compatibility to grow from, etc.

The iframe in the 'Test your environment' is 404'ing.

This can also be used for validation/error checking properties.

Example: http://jsfiddle.net/75GkH/4/

Should be minimal, and point to the GitHub pages docs.

The intros are great. It'd be helpful (for me at least) to know what features being explained are part of the standards-track process and which are conveniences provided by the toolkit. For instance, I suspect that the "$" property might be toolkitchen specific, but I don't know and the intro doesn't help me find out.

The examples show it being loaded synchronously, which might be OK, but it doesn't clarify what can and can't be loaded async. See:

http://toolkitchen.github.com/docs/getting-started.html

Would love it if the first paragraph included a link to the Shadow DOM spec when discussing built-in implementations. See: http://toolkitchen.github.com/docs/shadow-dom-shim.html

The default is to load a minified version of platform and to include Shadow DOM polyfill support only where needed. The defaults can be altered using run-time flags.

The matrix is something like this:

[flags] loads [target]

[] loads [platform.min.js]
[debug] loads [platform.debug.js]
[shadow=polyfill] loads [platform.poly.min.js]
[shadow=polyfill, debug] loads [platform.debug.js] loads [ShadowDOM Polyfill]

Note that the shadow flag defaults to 'polyfill' on platforms where native Shadow DOM is not detected.

Flags can be specified on the main URL or on the script tag which loads platform.js.

Examples:

http://localhost/someapp.html?debug&shadow=polyfill

or

<script src="../platform/platform.js" debug shadow="polyfill">

Note that the non-debug (minified) versions of the platform must be built via the (default) grunt task if source is modified. There are minified versions of platform.js (platform.min.js and platform.poly.min.js) checked in to the repository now that we will attempt to keep current. Ultimately some post-commit hook to keep them fresh would be great.

See the section "Accessing public properties on an component" at http://toolkitchen.github.com/docs/getting-started.html

When we update to the new repo structure the live demos will stop working.

This is subtle, but we decided early that "workbench" was literally for files and tests we need while working on components. It's a mistake to conflate that with "examples", since the latter would have different requirements for readability and so on.

There really is no "examples". We need something cool for that. =P

So we can deep link into sections of doc pages.

"As browsers being to implement"

Looks like some media query love is needed to re-format the page for smaller screen sizes.

From the mailing list:

What differences there is between Polymer and Angular, and respect to Dart's Web UI ?

Why does Google is developing three different technologies for the web front-end instead of to create one only killer technology?

Random cow paths vs. well-paved roads, etc.

The ShadowDOM polyfill does not cover ShadowDOM css scoping behavior. Toolkit has a partial shim for this behavior.

1. @host rules are converted to rules prefixed with the element's tag name. For example this rule inside an x-foo

   @host {

   • { ...
     }
     }

becomes:

x-foo { ...
}

1. Selectors in shadowRoot style elements are prepended with the element name and a space, creating a descendent selector. This makes sure the styling does not leak outside the shadowRoot. For example, inside an x-foo, this rule:

   div { ... }

becomes:

x-foo div { ... }

1. For other complex styling, we've included the @polyfill directive which can be placed inside a css comment. The seletor next to @polyfill replaces the next selector in the style element. For example, a distributed rule can be polyfilled manually with careful use of selectors:

   /* @polyfill .container .bar */
   content::-webkit-distributed(.bar) { ... }

Under native ShadowDOM polyfill, the rule is as written. Under the polyfill, it becomes:

.container .bar { ... }

@azakus has a potential fix locally.

The elements in toolkit have now been separated into the toolkit-ui repository.

The docs should mention that toolkit elements are in the toolkit-ui repo.

I wanted to do a pull request but I don't see how you generate the documents.

Under "Public properties"

this.component({
  clickColor: 'orange',
  clickHandler: function() {
    this.node.style.backgroundColor = this.clickColor;
  },
  publish: {
    this.clickColor = 'red',

  }
});

should be

this.component({
  clickColor: 'orange',
  clickHandler: function() {
    this.node.style.backgroundColor = this.clickColor;
  },
  publish: {
    clickColor: 'red'
  }
});

publish is an object literal, not a block. I think you might want to update the text too since you refer to it as a block in places.

I don't understand the vertical (apparently stacked) relationship in the intro diagram. Many of the stuff at the highest level would exist at many "low" levels in an app. Likewise, why is the toolkit in the middle? Between the platform and Toolkitchen, quiet a lot is still being left to the user, and those things aren't called out clearly in the graphic here:

http://toolkitchen.github.com/docs/images/architecture.png

It'd be great if there were color coding for what you'd need to bring/build in your own app. Addiitionally, we should call out BYO features of any app such as a data model, storage/synchronization strategy, UI layout, and of course app features ;-)

I don't mean to be a stickler, but the font-size is really small, and so nothing really pops out at me, especially the things that should like the principles at bottom.

See: http://toolkitchen.github.io

Define key terms of this emerging platform (web components, shadow DOM, custom elements, MDV, etc.)

Explanation of use cases/description of functionality
API (properties, methods)
Valid attributes, children
Events

• g-component link tag uses toolkit/src/g-component which is located in toolkit/components
• Many examples lack the g-component link tag entirely (tk-binding-to-elements, tk-element-ready, tk-node-finding)
• There are several cases of {{owner}} missing (tk-element-property-public, tk-element-public-access, tk-element-public-access)
• {{color}} missing from tk-node-finding

Ideally, integrated into the core "technical" framework documentation.

Will work with Alex.

This is nitpicky, so feel free to ignore.

The original text I think used "simultaneously" instead of "both". The intention is to say that one application can be at once complex (in the gestalt) and simple (when viewed as a collection of components). Using "both" it reads IMO that toolkit is suitable for both complicated applications and simple applications, which is not the same thing at all.

Btw, "extremely simple" is hyperbole, but I couldn't think of better phrasing there.

Btw #2: good job on these documents in general.

https://github.com/PolymerLabs/google-apis
https://github.com/Polymer/core-shared-lib
googlewebcomponents.github.io