[4.0][JS] Joomla! Custom events. Yo!

[Fedik]

It is another try to introduce a custom events to the client side (previous versions #6357, #1260)

Summary of Changes

This time I tried make it simple as possible.
Joomla! Custom events use native DOM events, and so compatible with any library (jquery, mootools etc).

The custom events should allow us interact between different frontend part more easily.
Example, the subform field script, and other fields inside it.

For start I introduce 2 custom event:

• joomla:updated Should be dispatched over the changed container, example after the content was updated via ajax
• joomla:removed Can be dispatched when the container was removed

I made example for the Calendar field.
The subform field dispatch joomla:updated event (see in the code). And the calendar scrip listen to it, and initialize the calendar in a new subform row (see here).

Joomla.Event contain two method:

Joomla.Event.dispatch Helper method used for dispatch the custom event. Use:

// Dispatch event to myElement, with custom data
Joomla.Event.dispatch(myElement, 'joomla:updated', {for: 'bar', foo2: 'bar2'}); 
//or:
Joomla.Event.dispatch('joomla:madestuff', {for: 'bar', foo2: 'bar2'}); // Default element is Window

Joomla.Event.listenOnce Helper method which allow for the eventListener to be called only once.

I would like to see event delegation, but the general implementation more complex than local implementation.

Another use case

Custom events can be used to send a custom data from one script to another.
Example:

// scrip foo.js
window.addEventListener('bar:madestuff', function(e){
  console.log(e.detail.data);
});

// script bar.js
Joomla.Event.dispatch('bar:madestuff', {data: 'some tuff'});

Profit: bar.js do no need to know about foo.js exists, and which callbacks has. And vise versa.

btw, @DGT41 this can be a solution to "modal close" endless story 😉 (I will write details later)

Joomla! Custom events name convention:

The event name has at least two part, separated ":", eg foo:bar. Where the first part is an "event supporter", and second part is the event name which happened. Which is allow us to avoid possible collisions with another scripts and native DOM events.
Joomla! CMS standard events should start from joomla:.

Testing Instructions

Can test with the calendar field in the subform field. Use the example xml, for a subform field, place it in any form:

<field name="test" type="subform" label="Test" multiple="true">
  <form>
    <field name="calendar" type="calendar" label="Calendar" />
  </form>
</field>

Expected result

The calendar works in each new row.

Actual result

The calendar do not work

Documentation Changes Required

Need to add new info.

TODO:

• write tests

Documentations: https://docs.joomla.org/J4.x:ClientSideEvents

[wilsonge]

Seems good to me

[dgrammatiko]

Thank you @Fedik!

[Sophist-UK]

Having now been pointed at this in #11299, I feel the need to ask why we need Joomla.Event.dispatch and Joomla.Event.listenOnce but instead of providing Joomla.Event.listen we require window.addEventListener?

Arguments for providing Joomla.Event.listen:

1. Style & elegance
2. If at a later date we want to change the way Events work.

[dgrammatiko]

require window.addEventListener?

Yes, that’s basic and fundamental browser js API. We are not jquery creating our own API that is a proxy to to the native API the only cases we do it is by creating a helper eg Joomla.request()

[Sophist-UK]

So why do we create Joomla.Event.dispatch when there is a window.dispatchEvent native API?

And why not have:

Joomla.Event.list = function(element, name, callback) {
    element.addEventListener(name, callback);
}

which only has a tiny overhead on registering the listener and no impact when the event happens, but provides both an consistent solution and also one which is potentially extendable if for any reason we ever want to extend the model beyond the standard one.

[Fedik]

@Sophist-UK the main direction is to use nativ JS,

Joomla.Event.dispatch is just a shurtcut/wrapper/helper, and way to say "Joomla! have it",
and instead of do:

var event = new CustomEvent('blablaevent', {
	detail:     params,
	bubbles:    true,
	cancelable: true
});
element.dispatchEvent(event);

we can do Joomla.Event.dispatch('blablaevent')

And in opposite to dispatchEvent, <element>.addEventListener is a very easy thing, where Joomla.Event.listen will be not a very helpful wrapper 😉
And also we want that user use more native JS.

Also it make Joomla! more friendly to new/"non Joomla!" developers, as they can use skills which they already learned while worked with JavaScript somewhere else.

I do not mind if someone add Joomla.Event.listen, but it does not make much profit, and most of a time no one will use it.

but provides both an consistent solution and also one which is potentially extendable if for any reason we ever want to extend the model beyond the standard one.

We stick to a native events, and as long as they works, we do not have to worry about it 😉

[Sophist-UK]

I am not disagreeing with the decision to go with native JS rather than using e.g. jQuery / MooTools, but as an example of how we might like to extend it, it might be nice to have the Javascript equivalent of the PHP Joomla Debug block if Joomla debugging is on. If you feed all Event and Ajax calls through lightweight helpers, then adding this is a small change with minimal overhead.

[Sophist-UK]

P.S. jQuery / Mootools exist because at the time they were written:

a. Native browser functionality did not exist for a lot of the functionality, and frameworks like these provided pre-written standardised ways of doing them; and

b. The functionality that browsers did have differed across browsers, and frameworks allowed those to be hidden and to have common code that ran on all browsers.

These problems have largely gone away - which is why ditching MooTools and jQuery makes sense. But that doesn't mean that there is never a need to add advanced functionality not provided by browsers natively.

[Fedik]

@Sophist-UK I understood your idea

But let's keep it simple for now, we always can add it later if there will be more request for it 😉

[Sophist-UK]

When I get the chance I will submit a PR to 4.0 to add the debugging capability.