A Joomla plugin is an extension that adds or modifies functionality without creating a separate page or menu item.
Without plugins, adding features such as SEO tools, spam protection, social login, or custom functionality would require modifying Joomla's core code. Directly changing the core would make the system harder to maintain, upgrade, and secure. To solve this problem, Joomla uses an event driven plugin system that allows developers to hook into specific actions, such as saving an article or logging in a user, and execute custom code without modifying the core.
Plugins are primarily used when you need to modify Joomla's behavior at a specific point in the request lifecycle. They can be used to add CSS or JavaScript files, modify content, replace article text, perform redirects, integrate third party services, and much more.
Joomla organizes these actions into different event groups, including System Events, Content Events, User Events, Authentication Events, Search Events, and others.
A Content Plugin is a type of Joomla plugin that works with article and content data. It is mainly used to modify, extend, or add functionality to content before, during, or after it is displayed. Content events are triggered throughout the content lifecycle and are used by many Joomla components, modules, and views. They are not limited to the com_content component.
Content Plugin Events are commonly used to modify article text, insert additional content, process shortcodes, display custom information, add related content, generate dynamic output, and enhance the overall content presentation.
Here is a list of all Content Plugin Events with an explanation of each.
onContentPrepare
This event is triggered when Joomla prepares content before it is displayed. It allows developers to process, modify, or enhance article content before it is rendered on the front end.
It is particularly useful when you need to perform actions such as replacing text, processing custom tags, converting keywords into links, or inserting dynamic content into an article.
What Is It Used For:
- Modify article content before it is displayed.
- Replace text or keywords with other content.
- Process custom tags or shortcodes, such as {gallery} or {youtube}.
- Insert dynamic content into an article.
- Convert keywords into links automatically.
- Process placeholders and replace them with dynamic values.
Syntax:
onContentPrepare($context, &$article, &$params, $page = 0)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$article - A reference to the article that is being rendered by the view (e.g. $article->text)
&$params - parameters associated with the content being processed (e.g $value = $params->get('show_title'))
$page - It represents the page number of the content being prepared when the content is divided into multiple pages.
Example:
onContentAfterTitle
The event is triggered during article rendering. It is a request for information that should be placed between the content title and the content body.
It allows adding content after the article title and before the article main content.
What Is It Used For:
- Adding content after article title
- Display custom tag or label after title like "News"
- Add additional information such as author information, reading time, or article metadata.
- Display icons or buttons next to or below the article title.
- Show notices or messages related to the article.
Syntax:
onContentAfterTitle($context, &$article, &$params, $page = 0)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$article - A reference to the article that is being rendered by the view (e.g. $article->title)
&$params - parameters associated with the content being processed.
$limitstart - An integer that determines the page of the content that is being generated. This is particularly relevant when content is divided into multiple pages.
Example: Here is an example to add a badge of "New" after title using the onContentAfterTitle event.
onContentBeforeDisplay
The event is triggered before the content is displayed. It allows users to add content before the main content display on the front end.
It is particularly useful when you want to display additional information, notices, banners, or custom HTML before an article.
What Is It Used For:
- Display a notice or message before an article.
- Add custom HTML before the article content.
- Display dynamic information based on the article.
- Add a button or icon before the article content.
- Insert advertisements or banners before the content.
Syntax:
onContentBeforeDisplay($context, &$article, &$params, $limitstart)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$article - A reference to the article that is being rendered by the view (e.g. $article->title)
&$params - parameters associated with the content being processed.
$limitstart - An integer that determines the page of the content that is being generated. This is particularly relevant when content is divided into multiple pages.
Example:
onContentAfterDisplay
The event is triggered after the content is displayed. It allows users to add content after the main content display on the front end.
It is particularly useful when you want to display additional information, notices, banners, or custom HTML after an article.
What Is It Used For:
- Add custom content after an article is displayed.
- Display additional information or promotional content at the end of an article.
- Display related article content after the main article.
- Display social sharing buttons after the content.
- Add custom HTML after the article content.
Syntax:
onContentAfterDisplay($context, &$article, &$params, $limitstart)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$article - A reference to the article that is being rendered by the view (e.g. $article->title)
&$params - parameters associated with the content being processed.
$limitstart - An integer that determines the page of the content that is being generated. This is particularly relevant when content is divided into multiple pages.
Example:
onContentBeforeSave
This event is triggered before the content is saved into the database. It allows a content plugin to process, validate, or modify the content before Joomla saves it to the database.
What Is It Used For:
- Modify article content before saving.
- Set default values for article fields.
- Prevent invalid content from being saved.
- Apply custom rules before an article is stored in the database.
- Validate article data before it is saved.
Syntax:
onContentBeforeSave($context, &$article, $isNew, $data)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$article - A reference to the article that is being rendered by the view (e.g. $article->title)
$isNew - It is a boolean value to show the content item is new.
$data - Data being saved. It can be used to access the submitted form data.
Example:
onContentAfterSave
The event is triggered after the content is saved into the database. It allows a content plugin to perform additional actions after Joomla saves an article.
What Is It Used For:
- Perform an action after an article is saved.
- Create logs when an article is saved.
- Update related data after an article is saved.
- Trigger custom processing after an article is successfully saved.
Syntax:
onContentAfterSave($context, &$article, $isNew)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$article - A reference to the article that is being rendered by the view (e.g. $article->title)
$isNew - It is a boolean value to show the content item is new.
Example:
onContentPrepareForm
The event is called before JForm is rendered. It is triggered to modify a JForm object before rendering.
What Is It Used For:
- Add custom fields to an article, category, contact, or user form.
- Remove or hide existing fields from a form.
- Load an extra file or field to the existing form.
- Change field attributes (label, required, readonly, etc.) dynamically.
Syntax:
onContentPrepareForm($form, $data)
Parameters:
$form - The JForm object to be displayed. It provides access to form fields and allows users to modify forms.
$data - Associated with the form. It contains information about the currently loaded value.
Return Value: Boolean, true if the method succeeds.
Example: Here is an example of updating the label of an article field.
onContentPrepareData
The event is called after JForm has been retrieved. It is triggered when Joomla loads an existing form and needs to fill it with data, right after the form structure itself has been prepared. It runs just after onContentPrepareForm, as part of the same "load form" process.
It is used for filling data for custom fields which you added through the onContentPrepareForm event.
What Is It Used For:
- Add custom data to an article before the form is displayed.
- Pre-fill form fields with default values.
- Modify existing data before it is loaded into forms.
- Set dynamic values based on the current article or user.
Syntax:
onContentPrepareData($context, &$data)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$data - An object containing the data for the form. A reference to the content data being prepared.
Return Value: Boolean, true if the method succeeds.
Example: Here is an example where you can add a default value to a custom field when a Joomla article is open for editing.
onContentBeforeDelete
This event is triggered right before content is deleted from the database. Here you can abort the delete by returning false.
What Is It Used For:
- Validation and prevention: stop deletion if a specific condition matches.
- Get user data and store it before delete from database.
- Logging and auditing: record who deleted what and when, before the data disappears.
- Permission check and notification: check permission before deleting data and send notifications like alerts before delete from database.
Syntax:
onContentBeforeDelete($context, $data)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
&$data - An object containing the data for the form. A reference to the content data being prepared.
Return value: Boolean, the result affects whether the deletion actually proceeds; returning false cancels the delete.
Example:
onContentAfterDelete
This event is triggered after content is deleted from the database.
What Is It Used For:
- Redirecting users after deleting their data.
- Logging and auditing: recording that the deletion happened, since you no longer have access to the record afterward for logging purposes.
- Notifications: informing other users or systems that the content is gone (e.g. via email or webhook).
- Cache invalidation: clearing cached views or listings that referenced the now deleted item.
Syntax:
onContentAfterDelete($context, $article)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
$article - A reference object that has been deleted which holds the article data.
Example:
onContentChangeState
This event is triggered after content has its state changed. For example, when an article is published, unpublished, archived, or trashed.
What Is It Used For:
- Custom workflow logic, e.g. auto unpublish related items when a parent item is unpublished.
- Notifications: alert someone when content gets published (e.g. notify an editor when a submission goes live) or trashed.
- Logging and auditing: record who published, unpublished, archived, or trashed what and when.
- Access control adjustments: revoke or grant front end access to related resources (like downloadable files tied to an article) based on the new state.
- SEO and sitemap management: add or remove URLs from an XML sitemap when content is published or trashed, so search engines aren't pointed at unpublished content.
Syntax:
onContentChangeState($context, $pks, $value)
Parameters:
$context - It shows where the content is coming from. This is the component name and view, or name of the module (e.g. com_content.article).
$pks - An array of primary key ids of the content that has changed state.
$value - The new state value.
Example:
onContentSearch
This event is triggered by a variety of search related operations. It is used to add its own content to Joomla's search results or modify the results returned by the content plugin.
The rows must return the following fields, which are used in a common display routine: browsernav, catslug, created, href, section, slug, text, title.
Most modern Joomla sites use Smart Search (com_finder) instead, which has its own separate indexing based event system.
What Is It Used For:
- Making a custom component's data searchable, e.g. if you built a Products or Events extension, you write an onContentSearch handler so those items show up in Joomla's global search results alongside articles and contacts.
- Filtering search by permission and state: plugins typically restrict the query to only published, non-expired, access-permitted items so search doesn't leak unpublished or restricted content.
- Custom search UI extensions: third party extensions (e.g. a directory listing, a downloads manager) commonly hook this to plug their content into the site wide search box.
Syntax:
onContentSearch($text, $phrase = '', $ordering = '', $areas = null)
Parameters:
$text - The search text entered by the user.
$phrase - A string matching option (exact, any, all). The default is "any".
$ordering - Determines the ordering method for the search results. The default is "newest".
$areas - The search areas selected by the user.
Example:
onContentSearchAreas
This event is used to identify which "areas" a plugin provides search facilities for. It is called when Joomla needs to know which areas of content can be searched.
What Is It Used For:
- It helps Joomla know what types of content your plugin can search.
- Articles, products, FAQs, and other areas of content can be searched.
Syntax:
onContentSearchAreas()
Parameters:
None.
Example: Here you can define multiple search areas.
Need Help Building aCustom Joomla Plugin?
Our team writes update safe Joomla plugins and components built directly on core events like the ones covered here, no shortcuts, no core file edits.
Talk to a Joomla DeveloperConclusion
Content Plugin Events give you a clean, update safe way to hook into nearly every stage of an article's life, from first render through saving, deleting, and search indexing, without ever touching Joomla core. Once you know which event fires at which point, you can add functionality, enforce rules, or extend the content system in a way that survives every future Joomla update.
If you're building a custom plugin and aren't sure which event fits your use case, or want a second pair of eyes on your event driven code, that's exactly the kind of work our development team handles regularly.