gistfile1.md

Polymer Feedback

Things I've come accross that are unpleasant with polymer.

Template Binding

1. There is TemplateBinding which is standalone
2. It doesn't seem like a direct implementation of the template tag

TemplateBinding is an add-on API to template tag, so this is true by definition.

3. No instructions for using it standalone (turns out you have to bower install it and its dependencies and include them manually) — I've published a compiled version to npm at templatebinding

The inventor of TemplateBinding along with our team chose specifically to de-emphasize it's standalone nature to focus on integrating it with Polymer. Note that "missing instructions on using TemplateBinding by itself" is not a problem with Polymer per se (since it involves not using Polymer).

In general, I hear your issue about the documentation not being comprehensive.

4. The event handling doesn't work, turns out you do something different for that called auto-binding, no explanation why this is the case, or why it was left out of template binding.

Proper API design involves layering. In other words, it's just good engineering practice to break things into separable chunks. So, in general, expressions and other features aren't "left out" of TemplateBinding, they are just in other layers. TemplateBinding provides hooks for other libraries to extend the functionality as they want. We provide a set of extended functionality in the polymer-expressions module.

Event handling requires a notion of a controller, there are many ways one could define it. The auto-binding template extensions and Polymer elements themselves provide this notion. It's much harder to define it generally and built directly into TemplateBinding (in addition to being a layering violation).

Intuitiveness

Intuitiveness is fundamentally an exercise in bias. What one finds intuitive usually depends on one's experiences.

In polymer you define custom elements like so:

<!-- scripts dependencies go here -->
<polymer-element name="my-element">
	<template>
		<!-- stylesheet dependencies go here -->
		<!-- element html goes here -->
	</template>
	<script>
		Polymer('my-element', {
			// logic goes here -->
		})
	</script>
</polymer-element>

However, it is completely unclear why this is so. In fact, reading the docs says that there are a few varieties to this. Here's why this is unclear:

1. Where does the shadow dom start? Is that what the template element does? Is template synomonous with shadow dom?

Polymer elements contain functions that by default convert the first template into ShadowDOM. This is all controllable via overriding functions.

2. What is the template element for? Can I have multiple template elements at that level?

Template element allows you to create a stencil for DOM without actually creating live nodes. Yes, you can have more than one.

3. How does it know which script tag is the polymer element definition script tag? Does it care?

The call to Polymer() is the definition, not the script itself. If you want to use DRY syntax and omit the element name from the Polymer call, it must be in a script tag inside the element definition, otherwise it doesn't matter.

4. Why is that script tag inside the polymer element?

As above to be DRY, or just because it's convenient to have it all in one tag.

5. Is it in the shadow dom?

No.

6. or the global scope? It appears the global scope?

Polymer does not not change the basic nature of JavaScript in DOM. <script> tags behave as normal, so variables and functions not in a closure will appear in the global scope. Most Polymer element simply declare a prototype and make no globals.

7. In which case, why is it inside the <polymer-element> element?

See above.

8. What if I don`t want to use shadow dom for my custom element? But I still want the model change listeners, the auto binding, etc?

See above, but don't do this. The defaults we provide are the best practice (by a mile).

9. The this.$.elementID helper doesn't seem to find dynamicly created elements (e.g. an element created from the results of an ajax request), it should just be removed imho

The $ static list is useful because it's an efficient look-up and is bindable.

10. How come when I include jQuery inside the template, then I create another script to use jQuery, it can't find jQuery? Nor can I access it via this.jQuery or any other way I could think of, E.g.

    <polymer-element name="my-element">
    	<template>
    		<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
    		<script>$(function(){
    			// never reached because $ is undefined
    			alert('dom is ready');
    		})</script>
    	</template>
    	<script>
    		Polymer('my-element', {
    			// logic goes here -->
    		})
    	</script>
    </polymer-element>

Load JQuery as normal, not inside the template. After that how you access JQuery depends on the version of JQuery you loaded and what options you provided. By default it exist as (window).$.

``` html
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
<polymer-element name="my-element">
	<template>
	 	<!-- don't put script here -->
	</template>
	<script>
		Polymer('my-element', {
			// can use $ here (or anywhere else for that matter)
		})
	</script>
</polymer-element>
```