Embedded web components: allow the web component to fire custom DOM events

[ujoni]

Allow web components produced by WebComponentExporter implementations to fire custom DOM events on the client-side.

The API needs further discussion!

Proposed interface (delivered to InstanceConfigurator):

public interface WebComponent extends Serializable {
    void fireEvent(String eventName);

    void fireEvent(String eventName, JsonValue objectData);

    void fireEvent(String eventName, JsonValue objectData,
                   EventOptions options);
}

[pleku]

Acceptance Criteria

The embedded application should be able to notify the embedding application about certain changes. These events are a part of the public API of the embedded application, and thus help decouple the embedding and the embedded application from each other.
The tutorial should be updated with an example of firing an event when e.g. a form has been saved.
The PetClinic example should be updated to fire an event when the form is saved, instead of updating the URL. (the Spring MVC app catches the event and then triggers the correct action)

[pleku]

Start with the API usage example and tutorial before going into the implementation.

[Legioth]

The issue description currently uses both "fire" and "publish" interchangeably for the same concept. Could we agree to always use the same word? Furthermore, can we agree to use the word "fire"?

[denis-anisimov]

PetClinic example via firing a client side event on save (not working since the feature implementation is not available yet):
https://github.com/denis-anisimov/spring-petclinic/tree/fire-event

[denis-anisimov]

Tutorial:
vaadin/flow-and-components-documentation#538

[ujoni]

As the #5259 is now in review, it provides the wiring that should make the implementation of this feature quite straight forward (soon).

But: we should probably run DX for the current web component thing before tacking this on or at least have small discourse about the current proposal.

Personally I find the example code in pet clinic to be pretty easy to follow but then again, I am super biased by now.

@denis-anisimov should I pick up the implementation portion of this, or do you fancy it?

[denis-anisimov]

I'm OK if you take the implementation. Just assign yourself then.

If you are able to run DX somehow soon then please do it.

I personally see the current API a bit cumbersome: you need to set one more callback inside a callback. And I'm not event sure in fireEvent methods : I would do it just via calling JS directly than via API (may be we still should have API do "declare" that it's possible).

I will write here a sketch of the usage which I would prefer instead of the current one.

[denis-anisimov]

So this code looks a bit complicated to me:

public class LoginFormExporter implements WebComponentExporter<LoginForm> {

    @Override
    public void define(WebComponentDefinition<LoginForm> definition) {
        definition.addProperty("userlbl", "")
                .onChange(LoginForm::setUserNameLabel);
        definition.addProperty("pwdlbl", "")
                .onChange(LoginForm::setPasswordLabel);

        definition.setInstanceConfigurator(this::initialize);
    }

    private void initialize(WebComponent<LoginForm> webComponent,
            LoginForm form) {
        form.addLoginListener(() -> webComponent.fireEvent("logged-in"));
    }
}

WebComponentExporter is SPI here. We require to set another callback (~ SPI) here : definition.setInstanceConfigurator.
It's too many callbacks for me.
I would prefer to have :

• either WebComponentExporter implements InstanceConfigurator right away with no-op accept default impl.
• or make it possible to implement InstanceConfigurator by the WebComponentExporter implementation (optionally).
  In the latest case instead of using the setInstanceConfigurator a developer may just implement InstanceConfigurator and our code will consider the WebComponentExporter impl as a InstanceConfigurator out of the box and use it.
  So one method call less.

Another thing is: form.addLoginListener(() -> webComponent.fireEvent("logged-in")).
It's good to have fireEvent method declared as API may be (it shows that this is possible).

But I personally would try this :

form.addLoginListener(() -> form.getElement().executeJavaScript("this.dispatchEvent( new CustomEvent ('logged-in'));"));

Yes, this code contains extra lines but it's strait-forward.
By the way: is it possible at all ? Is fireEvent method do the same as form.getElement().executeJavaScript("this.dispatchEvent( new CustomEvent (' ?
I would like to be able to reuse Element API in this way.

[denis-anisimov]

Preparations for this are done: tutorial and example code are updated.
Implementation requires changes from PR for #5259.
So let's wait for it to proceed with this ticket.

[ujoni]

Couple of questions about the interface:

• The plan is to accept JsonValues as parameter, if any data is given - should this be expanded to accept the same primitives as the properties
• Do we want to enforce some naming conventions, like converting camelCamel into kebab-case?