Joomla-cms: [4.0] Having a consistent Plugin Events

[webconsolinc]

Is your feature request related to a problem? Please describe.

I've noticed that Joomla's Plugin Events are very inconsistent. For example, onDisplay event in editors and editors-xtd are very different. I am aware that the display will not be the same for different type of content or different feature. However, the method's arguments should always be the same (or generic) and allows the body to be flexible. That way, as developer, when we extend the JPlugin and implement events, we know exactly what to expect in the callback of the events.

onDisplay is just an example. I've noticed there's a ton more.

Describe the solution you'd like

Having generic arguments for Events. For instance, onDisplay(array $context=[]). This way, if in my plugin, if I expect "name" element, I can check and implement my code accordingly.

Additional context

[ghost]

Changed Label as new Features go in J4.

[Fedik]

onDisplay is not really an Event, it used like a callback https://github.com/joomla/joomla-cms/blob/4.0-dev/libraries/src/Editor/Editor.php#L200 same for buttons.

You should not expect that it triggered as Event for all plugins.

[webconsolinc]

@Fedik, check here:
https://docs.joomla.org/Plugin/Events

Regardless, the inconsistency is there and it should be genericized. See my suggestion in the proposed solution.

Another option is something like this:

public function onEventName() {
$args = func_get_args();
// implement the details here...
}

Or

// EventContext can be something like \JoomlaCMS\EventContext
public function onEventName(EventContext $context) {
// implement the details here...
}

Basically, an event should be very generic.

[alikon]

@webconsolinc please submit a pr should be more easier to discuss further with some code

[mbabker]

Basically, an event should be very generic.

Actually, no. An event should be emitted with a consistent set of parameters, typically encapsulated within an event object (which 4.0 supports, but because of 15 years of B/C most events aren't triggered that way and I get the feeling core will never fully embraced this level of encapsulation). The parameters should not be different regardless of where an event is triggered in the system; what can be different is the data contained within those parameters (i.e. a $context if something needs to distinguish the context the event is triggered from). If you're having to use func_get_args() in a listener to decide how to handle an event, that is already a code smell as listeners generally should only be subscribed to one event.

If onDisplay is being emitted as an event from two different contexts with two different sets of parameters, this is broken and one of those contexts should be refactored to use a different event. As pointed out, onDisplay actually isn't being emitted as an event in certain circumstances. So trying to compare the two contexts is like saying "every call to a onDisplay method in any class should always have the same signature".

As @Fedik pointed out, there isn't an "onDisplay" event in the editor API (and the documentation page is wrong for listing it as an event), it is a callback explicitly called by another method in the Editor class. There IS an "onDisplay" event in the Captcha API though, and this one is a proper event.

[alikon]

so we should fix documentation only, in your hopinion.?
... sounds reasonable... or wait.... still thinking ...

but because of 15 years of B/C ...

that's the point where i start to loose myself

[mbabker]

The docs should be fixed to accurately reflect onDisplay isn't an event in the Editor API.

[webconsolinc]

@mbabker, that's fair.

Keep in mind, I just raised onDisplay as an example and as it also listed as an Event on Joomla! Website. Now we know that it's wrong. So, what documentation can the community rely on?

Also, my report was related to 3.9.6, and not 4.0. I didn't log it as bug as I didn't see it as a bug. However, I saw it as serious inconsistency issue.

Now, there are other "Events" (I don't know if I should call them events now), such as:
onInit and a few others that I saw, there's similar inconsistency issue. Are they just callback? If so, where exactly can I use as a reference when I need to build Plugin to listen to events?

[ReLater]

I have added a short information on https://docs.joomla.org/Plugin/Events/Editor#Description_3

[ReLater]

So, what documentation can the community rely on?

A documentation that is kept up-to-date by the "community" ;-) Everybody is welcome to help.

[webconsolinc]

@RaLater how do I get involved to be able to contribute to code and documentation?

[ghost]

Documentation is a Wiki, so everyone can register and contribute. Coding i leave the Answer to @ReLater ;-)

[zero-24]

This two pages could be a good starting point :)

how do I get involved to be able to contribute to code

https://docs.joomla.org/Special:MyLanguage/Portal:Developers

how do I get involved to be able to contribute to [...] documentation

https://docs.joomla.org/JDOC:How_to_Contribute_to_Joomla!_Documentation

[fvlasenko]

say one thing, write another
JOOMLA4