Clarify example usage in README

[oslego]

First, thanks for working on these ideas! I'm following along with interest and starting to use them in personal projects.

Following along with the docs isn't always easy. This is more of a problem when ready-to-go examples are incomplete.

This PR clarifies the example for a class extending HyperElement:

• explicitly require hyperHTML to make it clear it's required

• define this.html bound to a shadowRoot, a common use case for Custom Elements. This particular one bit me hard. The comment in render() wasn't clear that this method MUST be defined. Added it in the constructor to help others after me.

• explicitly call this.onclick event handler. I like your idea with handleEvent, but it wasn't written anywhere in the code here and it WILL trip up people unfamiliar with the delegation mechanism.

Good job on the libraries so far! The docs need improving and better structure. I'd like to help here and there where I can.

[coveralls]

Coverage remained the same at 100.0% when pulling ed4f61263a0289763aa8bcc7e9ae0208ba5f9d09 on oslego:fix-example into 260ad0605873512ea8a6a5396efd3a1f720ac90f on WebReflection:master.

[WebReflection]

Oh dear ... I know the documentation is incomplete and the whole Patreon is about this indeed: me spending time to write the documentation!

About this PR, basically everything is a misunderstanding.

• you don't need to manually attach the shadowroot to this.html .. actually, you should never care about this.html at all. When you create this.attachShadow({mode: 'open'}) the DOM element will automatically expose a this.shadowRoot accessor which is exactly what this.html lazily use
• do not ever define this.html yourself, which is why it's not in the documentation. It's there to be used, not to be defined
• if you explicitly pass this.onclick your callback will be invoked with the global or undefined context. People still don't understand what is handleEvent about, beside me writing on my book and online so many times about it. The class provides an automatic handleEvent mechanism so that you just pass the instance as event handler and that's it. If you have a method called exactly the same as the one you are assigning in the template, everything you expect to happen will happen and nobody trips out: the context is the expected one, no wasted memory and performance on binding methods, the event is the correct one.

Please read again this post and ask me anything you want to in order to better understand why you don't want to pass this.onclick but just this to any listener you[d like to react to.

TL;DR your documentation breaks all features of the class.

[WebReflection]

P.S. about this.html ... if you attach a shadow dom, it does the right thing. If you don't, it does the right thing anyway, 'cause it uses the current element as container.

Custom Elements do not need Shadow DOM to work, which is another huge misunderstanding of the whole Web community.

These examples all work without using Custom Elements at all, because DOM nodes are already containers.

Shadow DOM is just to sandbox some content but it's not mandatory to have Custom Elements.

That means:

• you don't need to attachShadow in the created or constructor method, you do that only if you want Shadow DOM but that's not what everyone wants/needs
• you can render right away any Custom Element without caring about this.html but you have to use it, because if there's one thing I've written is that this.html is lazily doing the right thing.

Apologies 'cause I perfectly know the documentation is at crap-state and I need to improve, but I'm also alone behind all these projects and help would be surely appreciated but please ask me more before wasting time on PR 'cause I hate not-mernign PRs due lack of my own documentation.

It feels like a circle ... I am trying my best, people want to help, people didn't get it 100%, I have to halp people understand before they can help ... and etcetera :sob:

[oslego]

Fair point. I can take the criticism and accept the misunderstanding.

But if someone went to the trouble of making a PR to fix things that confused them, then these are prime candidates to clarify in the documentation. They will trip others too. Remember you are always building software for people. Use your knowledge to lift others.

[WebReflection]

these are prime candidates to clarify in the documentation

absolutely! before that, I need to clarify everything about hyperHtmL which is the logic behind this HyperHTMLElement scene.

They will trip others too

sure thing. However, this is because I don't do thing like every other ... what would be the purpose of proposing yet another library if that was the case?

I'm trying to bring developers back to standards because 70% of them don't know standards.

Passing a method as an event listener is the most common mistake ever, and the easiest to avoid if they knew about handleEvent that doesn't require bindings but they don't know it, and they will do many things aroudn instead of just using handleEvent!

Remember you are always building software for people. Use your knowledge to lift others.

That's my mission in a nutshell, but people also want more before being engaged ... and I'm just one person, with many projects to take care of.

I will clarify these things ASAP

[sourcegr]

Hi! I am following Hyper* closely, and I can confirm that better documentation is indeed needed.

I had to bang my head on the wall many many times before I start to understand what is happening under the hood. I am in a fair point right now, but I am really sorry that I dont write english good so that I could help with the documentation.

HyperHTML is a revolutionary technology, using the low level features of javascript, and that is why people find it hard to understand - because they are familiar with ready-made solutions that "hide" those features from the programmer.

The case with handleEvent is a common gotcha for those people that are accustomed to the hype javascript as I call it, but once you get it, it suddenly makes full sense. But I believe that in this particular point, someone needs to have a solid understanding of how the Javascript handleEvent is actually working in the Javascript Engine Level, and I think that besides the article you have wrote to medium for that, it has to be documented in the hyperHTML site.

I am very excited with these projects, but I am really sorry I am not such a good english speaker-writer (especially as far as terminology is concerned) to help with the documentation :-(

[WebReflection]

I can confirm that better documentation is indeed needed.

I am the first one to confirm that and I am working on it (not in this exact moment but in general)

Thanks for appreciating the revolution !