We have "attributes" - why not "custom-events"?

[Sergey Shevchenko]

Hi all,

(reposting from Dart Web Development)

 

With "attributes", we have some way to succinctly communicate to an element's users what properties they can set at the instantiation point. Why don't we have something similar for custom events that an element can fire? Something like:

<polymer-element name="my-element" attributes="height width" custom-events="open activate">

...

<my-element height="100" width="200" on-open="onOpen" on-activate="onActivate"></my-element>

The way it is now, users are left to either rely on the documentation (unreliable) or hunt all fire() and asyncFire() calls in the element's code.

If "custom-events" were added, it would be nice to also check, for every fire()/asyncFire() call, that the element actually declares the event being fired.

I bet all this would save a lot of debugging hours for a lot of people.

--Sergey

[Sergey Shevchenko]

...and as commented by Seth Ladd on the said Dart Web Development:

<quote>

I'd love this.

I see four APIs for custom elements:

* Custom attributes

* Custom events

* Children elements (yes, even adding a child element is a type of API)

* The elements imperative API (aka pure Dart code)

I hope we can demonstrate superior toolability for all surface areas of a custom element.

</quote>

[Scott Miles]

The reason we haven't done this is because it would be unique in our system to have live DOM or JavaScript code whose only purpose is documentation. I'm not saying it's off the table, but it would be crossing a line. All other declarations (in particular `attributes`) have a runtime function, any documentary service is incidental.

Follow Polymer on Google+: plus.google.com/107187849809354688692
---
You received this message because you are subscribed to the Google Groups "Polymer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to polymer-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/a6394d86-c4c1-4070-80e1-cca9840c776d%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Sergey Shevchenko]

Good point. How about the following function that custom-events could have:

- (as already proposed) in the element's definition, all fire() and asyncFire() calls would be checked to match an event in the custom-events;

- at the instantiation point, all non-standard-DOM on-event attributes would also be checked against the custom-events.

I'm not sure what weight Polymer Dart has on general Polymer JS development, but I think it needs to be mentioned that in Polymer Dart, the attributes property's purpose has already shifted towards documenting/code validity checking: it is always required that a published property be defined in the element's Dart implementation; the developer can also add it to the element's attributes, but the only goals that serves are:

- to better inform the user about the element's API;

- to check that all properties listed in attributes have @published counterparts in the implementation - just listing a name there never auto-creates a property.

[John Messerly]

On Sun, Feb 16, 2014 at 1:52 PM, Sergey Shevchenko <serg...@google.com> wrote:

I'm not sure what weight Polymer Dart has on general Polymer JS development, but I think it needs to be mentioned that in Polymer Dart, the attributes property's purpose has already shifted towards documenting/code validity checking: it is always required that a published property be defined in the element's Dart implementation [...]

 

Hmm, if true that would be a bug in Polymer.dart :). The "attributes" attribute and "publish"-ing a property do the same thing but they operate independently. Saying attributes="foo" should be enough to cause the attribute "foo" to correspond with "foo" in your custom element. You don't also need to publish it.

It is true (for now) that if you want changes to propagate in the other direction (property -> attribute) you need to mark the field with @observable, but that's more a limitation in how observers work in Dart (and one I hope we can fix).

FWIW, I do agree that it is a bit confusing to have "publish" and "attributes". If I recall correctly, "attributes" is preferred because it's easier for tools to understand. But I'm not sure in what cases "publish" would be recommended.

[Eric Bidelman]

From the docs, when to use "attributes" vs. "published":

Generally it’s preferable to use the attributes attribute because it’s the declarative approach and you can easily see all of the exposed properties at the top of the element.

You should opt for the publish property when either of the following is true:

1. Your element has many properties and placing them all on one line feels unwieldy.
2. You want to define default values for properties and prefer the DRYness of doing it all in one place.

Follow Polymer on Google+: plus.google.com/107187849809354688692
---
You received this message because you are subscribed to the Google Groups "Polymer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to polymer-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/CAJup4OX%2Bayp-dYtBG-8zzvD%3DAa8WAQOGBRcnnjRy27Tm9Spi1A%40mail.gmail.com.

[John Messerly]

yeah, I guess to me, those reasons aren't worth the mental overhead for having two ways of doing the same thing. Since people can choose "publish", humans and tools can't really rely on "attributes" telling the full story, so it kind of undermines the declarative value of "attributes". Honestly I would be fine with either "attributes" or "publish" if it was the only way. Anyway, just my opinion FWIW :)

[Matthew Butler]

On Tuesday, February 18, 2014 4:59:51 PM UTC-4, John Messerly wrote:

yeah, I guess to me, those reasons aren't worth the mental overhead for having two ways of doing the same thing. Since people can choose "publish", humans and tools can't really rely on "attributes" telling the full story, so it kind of undermines the declarative value of "attributes". Honestly I would be fine with either "attributes" or "publish" if it was the only way. Anyway, just my opinion FWIW :)

I'm in the same boat. If either was the 'one way' then I'd be fine with it, but at the moment, I virtually always use @published annotation. Some cases just because if I want to change an @observable to an attribute it's much easier to just change the annotation. And the other is because I find it much easier to work with just one file after I get the base HTML stuff written, and worry about only the code as I refactor etc.

Just my $0.02CDN =)

Matt

[Justin Fagnani]

Joining this thread a little late, but I'd like to come back to the original topic of declaring the public interface for a custom element. We've talking about this in person, but to recap:

I think this is critical for good tooling for custom elements. Tools can't assume this fixed set of elements where they know all the events, properties and attributes of an element. This is obviously an issue for design-time tools, but runtime tools have problems too: a framework that wants to support way data binding needs to be able to understand the relationship of attributes, properties and events, so that it can properly use them to bind to a single "property".

I'm not sure how the sandbox demo figures out what properties to make editable in the inspector, does it use the attributes attribute? If so, does it then use Node.bind with that attribute name, or does it just set the attribute?

-Justin

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/CAHbmOLZrFs%3DA24hGyP9Ab8uHDeMqsSUU1%2BQB%3Dd7dpUzSC8TEKg%40mail.gmail.com.

[Scott Miles]

As I mentioned, our philosophy at the moment is that the code itself should be as close as possible to optimized for run-time use. Additionally, we prefer that the bower-able packages have as little non-runtime content as possible. Both principles are aimed to reduce our general footprint.

However, this is all on a spectrum.

Current exceptions to the code rule include meta-data in comments, which today we use for documentation and cataloging. We could conceivably expand this metadata to accommodate tooling, it's all a matter of balance.

Designer (nee Sandbox) uses separate metadata files to do it's thing. Our experience is that IDE tools can take advantage of more metadata than we are comfortable putting directly into the run-time file.

Current exceptions to the package rule include legal claptrap (which we want to reduce; at this level of granularity, reproducing each of those files N times is poor ergonomics), the demo file, and the index.html file (all of which I'm still stressing about =P).

Scott

[Justin Fagnani]

Has any thought been given to packaging metadata with the components in a standard way, ie. are the metadata files that Designer uses available and appropriate for other tools to use?

Also, the property-event-attribute association, this actually _is_ needed at runtime if a consumer needs to create a 2-way bindings, unless Node.bind() will always be public API.

On Sat, Feb 22, 2014 at 1:19 PM, Scott Miles <sjm...@google.com> wrote:

As I mentioned, our philosophy at the moment is that the code itself should be as close as possible to optimized for run-time use. Additionally, we prefer that the bower-able packages have as little non-runtime content as possible. Both principles are aimed to reduce our general footprint.

However, this is all on a spectrum.

Current exceptions to the code rule include meta-data in comments, which today we use for documentation and cataloging. We could conceivably expand this metadata to accommodate tooling, it's all a matter of balance.

Designer (nee Sandbox) uses separate metadata files to do it's thing. Our experience is that IDE tools can take advantage of more metadata than we are comfortable putting directly into the run-time file.

Current exceptions to the package rule include legal claptrap (which we want to reduce; at this level of granularity, reproducing each of those files N times is poor ergonomics), the demo file, and the index.html file (all of which I'm still stressing about =P).

Are the demo and index.html files expected to be a solid convention too? Excuse my ignorance, since I'm coming at the from the Dart side and don't have a lot of experience with the JS widgets. What is the index.html file?

One idea I had seen a while ago was that the actual element definition could be in a file that includes documentation and demos - a very fat declaration, fluent-programing style. The extra content could then be striped by tools like vulcanizer. Of course, that might not be any better than separate files.

Thanks,

  Justin

[Scott Miles]

>> Are the demo and index.html files expected to be a solid convention too?

It's not concrete yet, but the current concept is to suggest this structure as convention, yes.

>> Excuse my ignorance, since I'm coming at the from the Dart side and don't have a lot of experience with the JS widgets. What is the index.html file?

The notion is that by including an `index.html` file, we have a standard convention that you can point your browser at a component folder, and get information about that component.

The actual `index.html` we included in most of our elements today is a little weird, but let's not get stuck on that, the notion is as above. =P 

>>  file that includes documentation and demos

Yes, so we are trying to have our cake and eat it too. As I mentioned, we are putting some metadata/documentation directly in the `whatever-element.html` file, but factoring the documentation display infrastructure and demos to other files.

>> The extra content could then be striped by tools like vulcanizer. Of course, that might not be any better than separate files.

Yes, we cannot escape vulcanizer, but as much as possible we want to make it sort of an advanced thing.

Scott