How to Create Joomla Content Plugin
Content events are triggered during the content creation process. The majority of these events are called in many views, many components and modules. They are generally not specific for the com_content component.
Events
1. onContentPrepare
This is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work. Since the article and related parameters are passed by reference, event handlers can modify them prior to display.
Return Value: None. Results are returned by modifying the referenced arguments. Sometimes a boolean might be returned to check for success or failure of the event.
function onContentPrepare($context, &$article, &$params, $limitstart)
{
//add your plugin codes here
//no return value
}
2. onContentAfterTitle
This is a request for information that should be placed between the content title and the content body. Although parameters are passed by reference, this is not the event to modify article data. Use onContentPrepare for that purpose. This event has special purpose in com_content for use in handling the introtext.
Return Value: String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.
function onContentAfterTitle($context, &$article, &$params, $limitstart)
{
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}
3. onContentBeforeDisplay
This is a request for information that should be placed immediately before the generated content. For views that generate HTML, this might include the use of styles that are specified as part of the content or related parameters. Although parameters are passed by reference, this is not the event to modify article data. Use onContentPrepare for that purpose.
Return Value: String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.
function onContentBeforeDisplay($context, &$article, &$params, $limitstart)
{
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}
4. onContentAfterDisplay
This is a request for information that should be placed immediately after the generated content. For views that generate HTML, this might include the closure of styles that are specified as part of the content or related parameters. Although parameters are passed by reference, this is not the event to modify article data. Use onContentPrepare for that purpose.
Return Value: String. Returned value from this event will be displayed in a placeholder.
function onContentAfterDisplay($context, &$article, &$params, $limitstart)
{
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}
5. onContentBeforeSave
This is an event that is called right before the content is saved into the database. You can abort the save by returning false.
Return Value: Boolean. Result will affect the saving process.
function onContentBeforeSave($context, $article, $isNew)
{
//add your plugin codes here
return true;
}
6. onContentAfterSave
This is an event that is called after the content is saved into the database. Even though article object is passed by reference, changes will not be saved since storing data into database phase is past. An example use case would be redirecting user to the appropriate place after saving.
Return Value: None. Result will be omitted.
function onContentAfterSave($context, $article, $isNew)
{
//add your plugin codes here
return true;
}
Example: Joomla Content plugin uses this event to send email whenever the content is submitted through front-end.
7. onContentPrepareForm
This event is called before a JForm is rendered. It can be used to modify the JForm object in memory before rendering. For example, use JForm->loadFile() to add fields or JForm->removeField() to remove fields. Or use JForm->setFieldAttribute() or other JForm methods to modify fields for the form.
Return Value: boolean. True if method succeeds.
8. onContentPrepareData
This event is called after the data for a JForm has been retrieved. It can be used to modify the data for a JForm object in memory before rendering. This is usually used in tandem with the onContentPrepareForm method - this event adds the data to the already altered JForm.
Return Value: boolean. True if method succeeds.
9. onContentBeforeDelete
This is an event that is called right before the content is deleted from the database. You can abort the delete by returning false.
Return Value: Boolean. Result will affect the saving process.
function onContentBeforeDelete($context, $data)
{
//add your plugin codes here
return true;
}
Example: Joomla Content plugin uses this event to check whether categories are fully empty before deletion.
10. onContentAfterDelete
This is an event that is called after the content is deleted from the database. An example use case would be redirecting user to the appropriate place after deleting.
Return Value: None. Result will be omitted.
function onContentAfterDelete($context, $data)
{
//add your plugin codes here
return true;
}
11. onContentChangeState
This is an event that is called after content has its state change. For example, from Published to Unpublished.
Return Value: None. Result will be omitted.
function onContentChangeState($context, $pks, $value)
{
//add your plugin codes here
return true;
}
Parameters
context
The context of the content being passed to the plugin. This is the component name and view or name of module. For example, com_content.article. You can use this to check whether you are in the desired context for the plugin.
&article
A reference to the article that is being rendered by the view. For example, the text of a com_content article can be found with $article->text.
¶ms
A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
page
An integer that determines the "page" of the content that is to be generated. In the context of views, it might not generate HTML output, a page is a reasonably abstract concept that depends on the context.
Examples and Tips
1. Don't run this plugin when the content is being indexed
// Don't run this plugin when the content is being indexed
if ($context == 'com_finder.indexer')
{
return true;
}