Inconsistent documentation on dom-repeat: shorthand form or native element

[renfeng]

1. https://github.com/Polymer/docs/blob/master/app/2.0/docs/devguide/templates.md#template-repeater-dom-repeat-dom-repeat

In most cases, you'll use the first (shorthand) form for dom-repeat. the shorthand form <template is="dom-repeat">

2. https://github.com/Polymer/polymer/blob/master/README.md#v1-custom-elements

<template is="dom-repeat"> should change to <dom-repeat>

It looks the shorthand form is being abandoned. And, the first document is stale.

[arthurevans]

I think the. README should be updated here--the template helpers dom-if and dom-repeat are special cases, because using the custom element form has drawbacks (like not working well with tables).

@kevinpschaaf I think the docs page (first link above) is more complete information than the README here... WDYT?

[kevinpschaaf]

@arthurevans Correct, the first doc is indeed correct, describing what Polymer 2.0 supports and is framed correctly from my reading.

@renfeng This is the key from the readme:

For the time being, Polymer (both legacy and class API) will automatically wrap template extensions used in Polymer element templates during template processing for backward-compatibility, although we may decide to remove this auto-wrapping in the future. Templates used in the main document must be manually wrapped.

As part of Polymer's template processing steps, any <template is="dom-..."> are automatically turned into <dom-...><template>..., where the is is removed prior to the template ever being stamped. This was done both for backward compatibility with 1.x and also to continue support for repeating in parser-constrained elements like tables, as @arthurevans mentioned. So while you are correct that customizing built-in elements with is is effectively being abandoned by Apple and thus we are choosing to not promote it in Polymer, we added this small affordance just for the existing template extensions to keep them working and provide a better experience. Hope that makes sense.

[renfeng]

Thanks for the swift responses.

It would be uncomfortable to accept both of the following

• <template is="dom-..."> is encouraged (and required, e.g. for working well with tables)
• <template is="dom-..."> may not work in the future

I wonder what kind of update the README is going to have.

[renfeng]

For dom-bind, shorthand doesn't work, but native element does when placed inside <demo-snippet>

The problem can be reproduced.