Lit-html: Clarify intended use of event handlers

[jpierson]

Hello, I'm new to lit-html and I'm really enjoying it so far although I've run into a rough edge when implementing a somewhat trivial HTML example that has an onchange event that I want to handle.

Reading the documentation under Writing Templates > Binding Types an example is given on how to "bind" event handlers using the syntax below:

html`<button @click=${(e) => console.log('clicked')}>Click Me</button>`

Trying this myself it didn't work and then later I ran into evidence that in order to get event handlers working that one has to use lit-extended the main documentation however doesn't seem to mention this. Oddly again, poking around for the lit-extended github project and npm package yielded no success until I realized from some github issues that lit-extended appears to be just a sub-api of lit-html. After changing my imports as mentioned in the SO post I was able to get things working however it also required me to change my event handler syntax to reference the pseudo attribute on-click instead of @click which differs from the official documentation as well as the syntax I've encountered in many examples in recent github issues. This makes me believe that I must be doing something wrong or that the documentation is out of date or perhaps both.

What I would appreciate is some assistance in understanding the expected usage and support for event handler syntax and perhaps a bit of explanation of what function lit-extended plays. Note that I'm working with lit-html outside of the Polymer/Web-Component ecosystem and am instead running our application through Babel & webpack to create a single page application so I'm mostly unfamiliar with usage of lit-html outside of this type of direct usage scenario at the moment. If I can formulate some understanding of the intentions behind the event syntax and APIs I'd be happy to contribute back in the form of documentation updates if it would help.

[Westbrook]

The current documentation site is a little ahead of itself, and it outlining the usage of syntax that won't be available until the next release of the lit-html library. In that is will be more future proof, it's probably a good idea to get started with that syntax, and you _should_ find it available via https://www.npmjs.com/package/lit-html/v/0.11.0-dev.1 or yarn add lit-html@dev. If you continue to have issues with that, or are otherwise interested in this syntax available in previous releases, take a look at https://github.com/Polymer/lit-html/tree/v0.10.2 which has some scripting for generating docs at https://github.com/Polymer/lit-html/blob/v0.10.2/package.json#L22

[jpierson]

@Westbrook thanks for the explanation. Do you think it would make sense to specifically document installing the pre-release version of lit-html in the getting started guide until the next official release is made. Until then for those like myself that are new it's going to seem confusing.

I'll checkout lit-html@dev to see if it helps smooth out some of the rough edges as I kick the tires.

[Westbrook]

I think @justinfagnani is looking to have this an official release, imminently. If not, maybe he could share his thoughts on this?

[ruphin]

There's been a lot of users running into the same problem recently; They read the docs and find that things not work because the new syntax does not work in the current release. I suggest either taking down the docs that teach the new syntax until it is released, or just releasing a version now that supports the syntax.

Some people report issues like this or ask questions about it on slack, but a many more will just give up and leave, and those people will have a terrible first impression and probably won't come back. Please fix it.

[aadamsx]

just releasing a version now that supports the syntax.

100%

[jpierson]

It seems that the changes to make extended default and the syntax changes are pretty major. Are we waiting on v1.0 release or is there a chance at an intermediate release so that we don't have to target 0.11.0-dev.1? There are concerns from my team about depending on a non-stable package build as we attempt adopting lit-html in a few key areas.

[jpierson]

Discussion in #333 doesn't lead me to believe that 1.0 is ready anytime soon.

[Westbrook]

Last I head from Justin (about a week ago) was he'd like to make an 0.11.0
release, and then charge hard towards a 1.0.0 release. Maybe he could
update us on that?

On Tue, Aug 14, 2018 at 9:53 AM Jeff [e-mail] wrote:

Discussion in #333 https://github.com/Polymer/lit-html/issues/333
doesn't lead me to believe that 1.0 is ready anytime soon.

—
You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub
https://github.com/Polymer/lit-html/issues/432#issuecomment-412879296,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABGmMU6SWdlPCN8ImTfuWCFxaRhqOUw9ks5uQtZVgaJpZM4V51cc
.

[justinfagnani]

The docs are now in sync with master. I'll make sure not to do that again.

[fineline]

@justinfagnani I agree that the Guide is now up to date with how event handlers work in lit-html. However the API ref:

https://polymer.github.io/lit-html/api/

still seems out of date. Looks like it is autogenerated from somewhere, maybe that needs to be run again.