Content plugin events

[robbiejackson]

User description

This is a draft structure for plugin events - submitted for review.

It's similar to the existing format at https://docs.joomla.org/Plugin/Events/Content but with some differences.

Let me know if you disagree with any of the following:

• the index page shows the event traditional name and concrete event class
• the index page shows when the event is available from. I know that it should be possible to infer this from selecting the version within docusaurus, but it's easy to make a mistake in the manual when duplicating files into different versions. Having the version there makes it clearer if a mistake has been made, and it's then easier to recover as well.
• the detailed descriptions are split into pages, based on the first segment of the concrete class (rather than the traditional name - the way it has been done up to now)
• the headers on the detail pages have the event class first - so there's a deliberate move to using these rather than the traditional names
• the examples are really just for examples which are properly documented in the Joomla manual. The additional notes can be used for other instances within Joomla, but these would require more work from the reader in understanding the Joomla code.

Also, it might be worth at some point including sortable headers - as in https://pester.dev/docs/additional-resources/articles/

---

PR Type

Documentation

---

Description

• Added detailed documentation on accessing event arguments and returning values for different event classes in Joomla.
• Documented various content plugin events, including their descriptions, arguments, return values, and examples.
• Created an index page listing plugin events with links to their detailed descriptions.

---

Changes walkthrough 📝

Relevant files

Documentation

joomla-4-and-5-changes.md Detailed Guide on Accessing Event Arguments and Returning Values docs/building-extensions/plugins/joomla-4-and-5-changes.md Added detailed sections on accessing event arguments and returning values for concrete, generic, and traditional legacy methods. Included code examples for each method. Explained the commitment to preserving argument order until Joomla 6. +147/-0  content.md Comprehensive Documentation of Content Plugin Events          docs/building-extensions/plugins/plugin-events/content.md Documented various content plugin events with descriptions, arguments, return values, and examples. Provided detailed information on events like onContentPrepare, onContentAfterTitle, onContentBeforeDisplay, etc. Included references to Joomla manual and API documentation. +451/-0  index.md Index of Plugin Events with Detailed Links                              docs/building-extensions/plugins/plugin-events/index.md Created an index page listing plugin events with their names, classes, groups, and release versions. Added links to detailed descriptions of each event. Included a warning about coding for both concrete and generic event classes. +27/-0

---

💡 PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[qodo-code-review]

PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ No key issues to review

[qodo-code-review]

PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

PR Code Suggestions ✨

Category	Suggestion	Score
Clarity	✅ Specify the expected format of the return value in the Content\AfterTitleEvent Suggestion Impact: The commit clarified that the return value for the Content\AfterTitleEvent should be a string of HTML, which aligns with the suggestion. code diff: +### Return Value + +String of HTML. This will get displayed after the item title. In the Content\AfterTitleEvent / onContentAfterTitle section, specify that the return type is a string and clarify that it should contain HTML content to be displayed, to avoid confusion about what should be returned. docs/building-extensions/plugins/plugin-events/content.md [67] ### Return Value -String. This will get displayed after the item title. +String (HTML): Content to be displayed immediately after the item title in the rendered HTML. Apply this suggestion Suggestion importance[1-10]: 8 Why: This suggestion provides clear guidance on the expected format of the return value, which is crucial for developers to ensure the correct implementation of the event.	8
	✅ Clarify the handling of return values in event descriptions Suggestion Impact: The commit added detailed descriptions for the return values of various events, specifying what types of values or modifications are expected to be handled by the event, which aligns with the suggestion. code diff: +### Return Value + +String of HTML. This will get displayed after the item title. + +:::info + The Joomla Custom Fields (com_fields) functionality has an associated plugin which is triggered by this event. +This plugin returns the HTML for those custom fields which have the Automatic Display option set to After Title. +So this event is triggered within the view which displays an item such as an article (com_content Article View), contact (com_contact Contact View), etc. +If you implement a component which supports custom fields then you will need to dispatch this event. +::: + +## onContentBeforeDisplay + +This is a request for information that should be placed immediately before the component's main content (eg article text). + +For views that generate HTML, this might include the use of styles that are specified as part of the content or related parameters. + +### Event Arguments +The event class \Joomla\CMS\Event\Content\BeforeDisplayEvent has the following arguments: + +Although `&item` and `&params` are passed by reference, this is not the event to modify item data. Use onContentPrepare for that purpose. + +- **`context`** - The context of the content being passed to the plugin. This is the component name and view - or name of module (e.g. com_content.article, com_contact.contact, com_users.user). Use this to check whether you are in the desired context for the plugin. + +- **`&item`** - A reference to the item which is being rendered by the view, for example, an article, contact or user. + +- **`&params`** - A reference to an associative array of the item parameters (usually the `params` field in the item's database record, but the `attribs` database field for com_content). + +- **`page`** - An integer which has been associated with the offset when displaying paginated lists of items. +However, it is often set to 0 or null, so you probably shouldn't rely on it. + +### Return Value + +String of HTML. This will get displayed before the text of the item. For the Return Value sections that currently state "None", consider specifying what types of values or modifications are expected to be handled by the event, even if no value is returned, to provide clearer guidance to developers. docs/building-extensions/plugins/plugin-events/content.md [35-37] ### Return Value -None. +No direct return value. Any modifications to the passed parameters are expected to be handled internally within the event. Apply this suggestion Suggestion importance[1-10]: 6 Why: This suggestion improves clarity by specifying that modifications are handled internally, which can help developers understand the expected behavior of the event.	6
Enhancement	✅ Add an example or clarification for the page parameter usage Suggestion Impact: The commit added a detailed explanation for accessing event arguments, including the `page` parameter, and provided examples of how to handle it in both Joomla 4 and 5. This aligns with the suggestion to clarify the usage of the `page` parameter. code diff: +<details> + <summary>Accessing Event Arguments</summary> + +To access the event arguments of an event concrete class you can use within your plugin class: + +```php +use Joomla\CMS\Event\Content\ContentPrepareEvent; + +class MyPlugin ... + public function onContentPrepare(ContentPrepareEvent $event) + { + $context = $event->getArgument('context'); + $item = $event->getArgument('item'); + $params = $event->getArgument('params'); + $page = $event->getArgument('page'); + // ... + } +``` + +However, if you want your plugin to work across Joomla 4 and 5 it may be better to use: + +```php +use Joomla\Event\Event; + +class MyPlugin ... + public function onContentPrepare(Event $event) + { + [$context, $item, $params, $page] = array_values($event->getArguments()); + // ... + } +``` + +This will work for both concrete event classes and generic event classes (as described in [Joomla 4 and 5 changes](../joomla-4-and-5-changes.md)). +</details> Consider adding a brief explanation or example for the page parameter in the Content\ContentPrepareEvent / onContentPrepare section to clarify its usage or potential importance, despite it often being set to 0 or null. docs/building-extensions/plugins/plugin-events/content.md [32-33] -- **`page`** - An integer which has been associated with the offset when displaying paginated lists of items. -However, it is often set to 0 or null, so you probably shouldn't rely on it. +- **`page`** - An integer which has been associated with the offset when displaying paginated lists of items. This parameter can be crucial for handling pagination correctly in some contexts, although it is often set to 0 or null. If used, ensure to handle cases where it might not be set. Apply this suggestion Suggestion importance[1-10]: 7 Why: The suggestion provides additional context and potential usage scenarios for the page parameter, which can help developers understand its importance and handle it correctly.	7
Maintainability	Use a single, reusable description for common parameters across different events To avoid redundancy and maintain consistency, consider using a single description for the context, &item, and &params parameters across all events, and then reference this description in each specific event section. docs/building-extensions/plugins/plugin-events/content.md [24-30] -- **`context`** - The context of the content being passed to the plugin. This is the component name and view - or name of module (e.g. com_content.article, com_contact.contact, com_users.user). Use this to check whether you are in the desired context for the plugin. -- **`&item`** - A reference to the item which is being rendered by the view, for example, an article, contact or user. -- **`&params`** - A reference to an associative array of the item parameters (usually the `params` field in the item's database record, but the `attribs` database field for com_content). +Refer to the general parameters description section for details on `context`, `&item`, and `&params`. Apply this suggestion Suggestion importance[1-10]: 5 Why: While this suggestion can improve maintainability by reducing redundancy, it may also reduce the immediate clarity of each event's documentation by requiring readers to refer to another section.	5

[HLeithner]

About the sortable datatables, pester (which you linked to) uses there own table implementation https://github.com/pester/docs/tree/main/src/components/PesterDataTable

[Fedik]

Looks good.

About index page.
I would do full class name (also for all other pages), it will symplify understanding and copy/pasting.
Also would do each group in own table.
Like:

---

Content

Event Name	Event Class	From Release
onContentPrepare	Joomla\Event\Content\ContentPrepareEvent	before 4.0

Another group

Event Name	Event Class	From Release
onFoobar	Joomla\Event\Content\FoobarEvent	before 4.0

---

And unlinked.
Well, it is very similar how it done in old wiki page 😃
Also this table need to be duplicated in the group overview page, or maybe Docusaur can do some "Table of content" at top of the page automaticaly.

For detail page.
I tried a bit different approach:

• https://manual.joomla.org/docs/building-extensions/plugins/editors-xtd-plugin
• https://manual.joomla.org/docs/building-extensions/plugins/editors-plugin

But I think what you made is good.

the headers on the detail pages have the event class first

I would keep only the event name in the header, and move the class in to description.
kind of:

---

onContentPrepare

Event class Joomla\Event\Content\ContentPrepareEvent

---

Mix of the event class and the event name in the headers is a bit hard to read.

[robbiejackson]

@HLeithner @Fedik many thanks for your comments - very useful.

I've revised the documentation

• events now split by plugin group - I presume the Model events will fit under Content group
• I've added how to access the event arguments and return a value on the Content plugins page, but as a collapsible section. I'm presuming we would add that on each page. The event arguments are going to be different for different plugin groups, so you can't have a generic section of text that would do them all.
• additional notes are now set as info admonitions
• examples section is included only if there are valid examples
• On the details page I've set the toc_max_heading_level to just display the event names

Details page is at
http://pr-291.manual.joomlacode.org/docs/next/building-extensions/plugins/plugin-events/content

[Fedik]

So I've expanded the collapsible sections on how to access the parameters and return values.

I think we better move this sections in to joomla-4-and-5-changes.md, and just link it here.
To keep the page more clean, and avoid duplication on every other Events detail page.
What do you think?

The "Accessing Event Parameters / Arguments" looks good.

The "Returning Values" is very confusing 😉
I kind of understand what you wanted to say, but I not sure about others.
The events does not have return value at all now. Maybe can try something like:

---

The legacy event which is expecting the result:

function onFooBar() 
{
  // ...
  return $myValue;
}

The event class which is expecting the result:

function onFooBar(FooBarEvent $event): void
{
  // ...
  $event->addResult($myValue);
}

---

Parameters which was with "reference"

Also there is events which had parameters as reference, in j5 this events got a special method to update the parameter (because referencing does not work anymore). I have tries do give a migration example at:
https://manual.joomla.org/migrations/44-50/removed-backward-incompatibility#module-event-onrendermodule-backward-compatibility
For onContentPrepareData https://manual.joomla.org/migrations/44-50/removed-backward-incompatibility#content-event-oncontentpreparedata-backward-compatibility

but this also better to be part of joomla-4-and-5-changes.md

I'm thinking also that we should maybe change 'item' to 'subject' in the arguments as well. What do you think?

Yes, that is good idea. Maybe for arguments that changed their names can do kind of this:

• subject (formerly known as $item or $row parameter) ... the rest of description ...

[robbiejackson]

I think we better move this sections in to joomla-4-and-5-changes.md, and just link it here.
To keep the page more clean, and avoid duplication on every other Events detail page.
What do you think?

Yes, agreed! I'm going to do this. Otherwise it's going to end up unmaintainable.

The event class which is expecting the result:

function onFooBar(FooBarEvent $event): void
{
  // ...
  $event->addResult($myValue);
}

The problem is that this works only if it's a concrete class. If it's a generic class it raises an exception. So if someone is trying to return a value to onContentAfterTitle in Joomla 4.4 then they can't use this, and simply returning a value won't work, so they have to use the generic event approach.

I think I know how to make this clearer though.

Parameters which was with "reference"

Also there is events which had parameters as reference, in j5 this events got a special method to update the parameter (because referencing does not work anymore).

Ok, I wasn't aware of this. As the update functions are going to have different names I think it's best to document this in the detailed section, eg in the onContentPrepareData documentation.

Will this just be done for some parameters and not for others? For example, for onContentPrepare where you can update the $subject/item?

[Fedik]

The problem is that this works only if it's a concrete class. If it's a generic class it raises an exception.

Yes, you are right.
My example was for "clean" listeners, specific for old and new.
For "transitional" listeners, could add 3-rd example, similar to what you made.

function onFooBar(Joomla\Event\Event $event): void
{
    // ...
    if ($event instanceof ResultAwareInterface) {
        $event->addResult($value);
    } else {   // use GenericEvent approach
        $result = $event->getArgument('result') ?: [];   // get the result argument from GenericEvent
        $result[] = $value;                              // add your return value into the array
        $event->setArgument('result', $result);  
    }
}

Will this just be done for some parameters and not for others? For example, for onContentPrepare where you can update the $subject/item?

Yes, only for specific parameters, in specific events.

I tried to document all of them at https://manual.joomla.org/migrations/44-50/removed-backward-incompatibility/#module-event-onrendermodule-backward-compatibility
Can just copy paste from there, or give a link for reference.

The list:

onRenderModule
attributes

onAfterRenderModules
content

onPrepareModuleList, onAfterModuleList, onAfterCleanModuleList
modules

onCustomFieldsAfterPrepareField
value

onInstallerBeforeInstallation, onInstallerBeforeInstaller, onInstallerAfterInstaller
package

onInstallerBeforePackageDownload
url
headers

onContentBeforeValidateData
data

onContentPrepareData
data

onSubmitContact
data

onPreprocessMenuItems
items

onAfterGetMenuTypeOptions
items

These events should use $event->updateFoobar($newValue); also could use $event->setArgument('foobar', $newValue);.

Technicaly, you can use $event->setArgument() for any argument, but it is not recomended, because most of the event class is AbstractImmutableEvent. And after we get something like this joomla/joomla-cms#39469 merged it will be not possible to do such thing for imutable arguments.

[robbiejackson]

I'm going to go with Fedir's suggestion of putting the description in Joomla 4/5 changes page, and linking to it from each details page. Otherwise there's a lot of maintenance overhead. I've updated the explanation hopefully to make it clearer.

I've changed item to subject in the first content events, but I've finding a problem with NormaliseRequestDataEvent getting the subject. I think getSubject() might be missing.

[Fedik]

I've finding a problem with NormaliseRequestDataEvent getting the subject. I think getSubject() might be missing.

NormaliseRequestDataEvent is the same as BeforeValidateDataEvent, and child of FormEvent.
subject here is the form object.
For these events it is like: $form = $event->getArgument('subject') or $form = $event->getForm()

[qodo-code-review]

PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Syntax Error There is a syntax error in the class definition on line 113 and 147. The class MyPlugin is incorrectly using extends twice. It should use implements for the interface. Documentation Clarity The explanation of the traditional legacy method starting from line 177 could be clearer. It should explicitly state that this method is deprecated and recommend transitioning to the new event class approach.

[qodo-code-review]

PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

PR Code Suggestions ✨

Category	Suggestion	Score
Possible bug	✅ Correct the class inheritance syntax to properly implement interfaces Suggestion Impact: The commit corrected the class inheritance syntax by replacing the incorrect extends keyword with the correct implements keyword for the SubscriberInterface, as suggested. code diff: -class MyPlugin extends CMSPlugin extends SubscriberInterface +class MyPlugin extends CMSPlugin implements SubscriberInterface Correct the class inheritance syntax error by replacing the incorrect extends keyword with the correct implements keyword for the SubscriberInterface. docs/building-extensions/plugins/joomla-4-and-5-changes.md [113] -class MyPlugin extends CMSPlugin extends SubscriberInterface +class MyPlugin extends CMSPlugin implements SubscriberInterface Apply this suggestion Suggestion importance[1-10]: 10 Why: This suggestion corrects a critical syntax error in the class declaration, ensuring that the SubscriberInterface is properly implemented, which is essential for the code to function correctly.	10
	✅ Fix the syntax error in class inheritance Suggestion Impact: The suggestion corrected the syntax error by replacing extends with implements for the SubscriberInterface in the class declaration. code diff: -class MyPlugin extends CMSPlugin extends SubscriberInterface +class MyPlugin extends CMSPlugin implements SubscriberInterface Replace the incorrect extends keyword with implements for the SubscriberInterface in the generic event class example to correct the syntax error. docs/building-extensions/plugins/joomla-4-and-5-changes.md [147] -class MyPlugin extends CMSPlugin extends SubscriberInterface +class MyPlugin extends CMSPlugin implements SubscriberInterface Apply this suggestion Suggestion importance[1-10]: 10 Why: This suggestion addresses a critical syntax error in the class declaration, ensuring that the SubscriberInterface is properly implemented, which is crucial for the code to work as intended.	10
Best practice	Clarify the deprecation notice for direct property modifications on the data object to encourage best practices For the onContentPrepareData event, it's recommended to clarify the deprecation notice regarding setting properties directly on the data object. Providing a clear rationale for why updateData should be used instead could help developers understand the importance of this practice. docs/building-extensions/plugins/plugin-events/content.md [165] -However, setting the properties directly is deprecated, and you should use `updateData` instead: +Setting properties directly on the `data` object is deprecated due to potential issues with data integrity and unexpected behavior in event handling. Instead, use the `updateData` method provided by the event class to ensure changes are managed correctly: +```php +$data = $event->getData(); +// modify $data +$event->updateData($data); +``` Apply this suggestion Suggestion importance[1-10]: 8 Why: This suggestion improves the clarity of the deprecation notice and explains the rationale behind using updateData, which is important for maintaining data integrity and proper event handling.	8
Enhancement	Improve the documentation for the page parameter to enhance clarity and provide usage examples Consider providing a more detailed explanation or example for the page parameter in the event arguments sections where it's mentioned. The current description suggests it is unreliable, which might confuse users about its utility or lead them to misuse it. Enhancing the documentation could improve clarity and usability. docs/building-extensions/plugins/plugin-events/content.md [36] -However, it is often set to 0 or null, so you probably shouldn't rely on it. +However, it is often set to 0 or null. If you choose to use this parameter, ensure your implementation handles these default cases gracefully. Here's an example of how you might check and use the `page` parameter safely: +```markdown +if (page !== null && page > 0) { + // Logic to handle pagination +} +``` Apply this suggestion Suggestion importance[1-10]: 7 Why: The suggestion provides a useful example and additional context for handling the page parameter, which can help developers avoid confusion and misuse. However, it is not addressing a critical issue.	7
	Add an example for enqueuing a custom error message when aborting a save operation to improve developer guidance In the section describing the onContentBeforeSave event, it would be beneficial to include an example of how to enqueue a custom error message when aborting a save operation. This can guide developers on how to provide more informative feedback to users. docs/building-extensions/plugins/plugin-events/content.md [257] -If you do return `false` then by default the error displayed to the user will then be set by calling `$this->setError($table->getError)`. +If you return `false`, you should provide a clear reason to the user. Here's how you can enqueue a custom error message: +```php +if (condition_to_abort_save) { + $this->setError('Custom error message explaining the reason for aborting the save.'); + return false; +} +``` Apply this suggestion Suggestion importance[1-10]: 7 Why: Providing an example for enqueuing custom error messages enhances developer guidance and helps in creating more user-friendly applications. However, it is a minor enhancement.	7
Maintainability	Improve consistency and clarity in event naming conventions within the documentation The documentation could benefit from a consistency check, particularly in the use of terminology and event naming conventions. For example, the event onContentChangeState is noted for its inconsistency in naming. A suggestion would be to standardize event names and update the documentation to reflect these changes, or at least note the exceptions more clearly. docs/building-extensions/plugins/plugin-events/content.md [403] -Note that this event isn't called "onContentAfterChangeState" - Joomla is a little inconsistent here. +Note that unlike other events, this event is called `onContentChangeState` instead of following the usual pattern of `onContentAfterChangeState`. This naming inconsistency is historical, but it's important to be aware of it to avoid confusion. Apply this suggestion Suggestion importance[1-10]: 6 Why: The suggestion addresses a minor inconsistency in event naming conventions, which can improve maintainability and reduce confusion. However, it is not a critical issue.	6

[Fedik]

Please remove all & in the argument names, like &foobar to just foobar. It does not need anymore, and can be confusing.
Also I would probably remove it from description, from eg:
A reference to the item which is being rendered by the view ...
to:
The item which is being rendered by the view ...

But just removing & should be enough.

The rest is looks good now.

[robbiejackson]

@Fedik I've removed the & symbols and changed some of the text as you suggested. Many thanks for your help sorting out this page - it was important to get it in a good state as a pattern for the rest.

Would you mind having a quick look at the updated index page to make sure it's accurate? (I've changed it a bit).
http://pr-291.manual.joomlacode.org/docs/next/building-extensions/plugins/plugin-events/

[Fedik]

Sorry a bit late.
I just noticed one litle thing 😄

The order of events is mixed:

onContentBeforeValidateData	Before POST data validation
onContentNormaliseRequestData	After POST data validation

Actualy the onContentNormaliseRequestData event goes first (trigrerred in the controller, before validation) , then onContentBeforeValidateData (trigered in model, before validation)

Also in the events descriptions it mixed, for onContentNormaliseRequestData it says:

It is triggered after the submitted form data 
(usually an array sent by the browser within a jform HTTP POST parameter) 
has been filtered and validated.

However it is triggered before validation.

[robbiejackson]

Ah thanks @Fedik , I missed that. I'll fix it up in the next pull request.