PolymerElements
attributes vs. properties
A recurring problem that people seem to have is the new attribute to property mapping in 1.0.
They try something like <custom-element myProperty="{{something}}"> because myProperty is listed in the element docs, where they should be using <custom-element my-property="{{something}}">
It would be nice to somehow display both the property and the attribute name in the generated docs. Especially beginners won't find their way all the way to the "property name mapping" part in the docs.
Gets me all the time, still. Great idea for linter mode. I've added it to the linter idea list.
Is this "Polymer linter" already available somewhere for testing/contributing or is it just an idea so far? :)
I think it is a work in progress
On Fri, Jun 12, 2015 at 10:42 AM, Gerwin Sturm [email protected] wrote:
Is this "Polymer linter" already available somewhere for testing/contributing or is it just an idea so far? :)
— Reply to this email directly or view it on GitHub https://github.com/PolymerElements/iron-component-page/issues/32#issuecomment-111570719 .
Adding this to the docs is also a good idea.
This and the auto-generated change events (property-changed) are subtleties that are obvious to the folks writing the API docs, but obscure to newcomers, especially if they go straight to the catalog.
My vote would be to have a toggle that flips "Properties" to "Attributes" and back, changing the formatting of the names but leaving everything else intact.
For <prop>-changed events, there are two ways I see to go about it -- have a toggle to show/hide them or have a separate section that just collects them into a comma-separated list. Any preference?
i'd love to see element generators, either as part of the demo, or a separate page. Nothing makes me happier as a developer than having an interactive playground.
For the events, I was thinking "Show/Hide generated."
Not sure about the flipping attributes/properties ... It makes it more compact but less discoverable (and possibly a little bit opaque).
Some elements have 10+ properties, meaning you're going to have a huge repeating section if you separate them out. A toggle helps reinforce that they're the same.
On further thinking, maybe it would be even better to have an "attribute name" along with the property name so there's no toggle needed. Show both at the same time for each one.
Yeah, I agree on not repeating them. Just adding an attribute name sounds good.
Because this behavior (and the property-changed events) are specific to Polymer, we should really add them to the autogenerated docs, so users on WC.org don't need to know Polymer-specific conventions to use the elements appropriately.
@aomarks WDYT? This is probably in the wrong repo, but would love to see this move forward.
@arthurevans I need to check the analyzer output again, but we should be generating both an attribute record and property record, and we may be able to associate them because they have the same source range.
While the specific camel-case property name to kebab-case attribute name is from Polymer, I think the general idea that some attributes are associated with properties is general enough to keep in iron-component page, so we can link the docs of them.
I think showing the attributes is a good idea, and https://github.com/PolymerElements/iron-doc-viewer/issues/125 is the same request.
