Difference between revisions of "Plugin/Events/Content"
From Joomla! Documentation
< Plugin | Events
(s/onAfterContentSave/onContentAfterSave/) |
(→Description: grammar) |
||
| (29 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | {{version/tutor|2.5,3.x|alt=1.5|altlink=J1.5:Plugin/Events/Content|alttitle=this guide for old event names}} | |
| − | {{version/tutor|2.5,3.x|alt=1.5|altlink=J1.5:Plugin/Events/Content|alttitle=this guide for old event names | + | 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. This list gives a brief description of each event, what their parameters are, and some examples of their use in core plugins. |
| − | |||
| − | Content events are triggered during the content creation process. | ||
| − | == | + | ==onContentPrepare== |
===Description=== | ===Description=== | ||
| − | This is the first stage in preparing content for output and is the most common point | + | 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. |
| − | 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. | ||
===Parameters=== | ===Parameters=== | ||
| − | *<code>article</code> A reference to the article that is being rendered by the view. | + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. |
| − | *<code>params</code> A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along. | + | *<code>&article</code> 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). |
| − | *<code> | + | *<code>¶ms</code> A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along. |
| + | *<code>page</code> An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
| − | None. Results are returned by modifying the referenced arguments. | + | None. Results are returned by modifying the referenced arguments. Sometimes a boolean might be returned to check for success or failure of the event. |
| − | === | + | |
| − | *<tt> | + | ===Example=== |
| − | + | *<tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/content/emailcloak/emailcloak.php#L31 plugins/content/emailcloak/emailcloak.php]</tt> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==onContentAfterTitle== | ==onContentAfterTitle== | ||
===Description=== | ===Description=== | ||
| − | This is a request for information that should be placed between the content title and | + | This event only exists in Joomla {{JVer|3.x}}. 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 onPrepareContent for that purpose. Note this event has special purpose in com_content for use in handling the introtext. |
| − | the content body. | + | |
| − | Although parameters are passed by reference, this is not the event to modify article data. Use onPrepareContent for that purpose. | ||
===Parameters=== | ===Parameters=== | ||
See the onPrepareContent event for additional discussion of these parameters. | See the onPrepareContent event for additional discussion of these parameters. | ||
| − | *<code>context</code> The context of the content being passed to the plugin. | + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. |
| − | *<code>article</code> The article that is being rendered by the view. | + | *<code>&article</code> The article that is being rendered by the view. |
| − | *<code>params</code> An associative array of relevant parameters. | + | *<code>¶ms</code> An associative array of relevant parameters. |
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated. | *<code>limitstart</code> An integer that determines the "page" of the content that is to be generated. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator. | String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==onContentBeforeDisplay== | ==onContentBeforeDisplay== | ||
===Description=== | ===Description=== | ||
| − | This is a request for information that should be placed immediately before the generated content. For views that generate | + | 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 onPrepareContent for that purpose. |
| − | Although parameters are passed by reference, this is not the event to modify article data. Use onPrepareContent for that purpose. | + | |
===Parameters=== | ===Parameters=== | ||
| − | See the onPrepareContent event for additional discussion of these parameters. Note that | + | See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value. |
| − | unlike onPrepareContent, these parameters are passed by value. | + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. |
| − | *<code>context</code> The context of the content being passed to the plugin. | + | *<code>&article</code> The article that is being rendered by the view. |
| − | *<code>article</code> The article that is being rendered by the view. | + | *<code>¶ms</code> An associative array of relevant parameters. |
| − | *<code>params</code> An associative array of relevant parameters. | ||
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated. | *<code>limitstart</code> An integer that determines the "page" of the content that is to be generated. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator. | String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | === | + | ===Example=== |
| − | *<tt> | + | *<tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/content/vote/vote.php#L29 plugins/content/vote/vote.php]</tt> |
==onContentAfterDisplay== | ==onContentAfterDisplay== | ||
===Description=== | ===Description=== | ||
| − | This is a request for information that should be placed immediately after the generated content. For views that generate | + | 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 onPrepareContent for that purpose. |
| − | Although parameters are passed by reference, this is not the event to modify article data. Use onPrepareContent for that purpose. | + | |
===Parameters=== | ===Parameters=== | ||
See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value. | See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value. | ||
| − | *<code>context</code> The context of the content being passed to the plugin ( | + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. |
| − | *<code>article</code> The article that is being rendered by the view. | + | *<code>&article</code> The article that is being rendered by the view. |
| − | *<code>params</code> A JRegistry object of merged article and menu item params. | + | *<code>¶ms</code> A JRegistry object of merged article and menu item params. |
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated. | *<code>limitstart</code> An integer that determines the "page" of the content that is to be generated. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator. | String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | ==onContentBeforeSave== | |
| − | + | ===Description=== | |
| − | + | This is an event that is called right before the content is saved into the database. You can abort the save by returning false. In the case of <code>JModelLegacy</code> for example the error will then be set by calling <code>$this->setError($table->getError);</code> to be displayed to user. | |
| − | === | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===Parameters=== | ===Parameters=== | ||
| + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. | ||
*<code>article</code> A reference to the JTableContent object that is being saved which holds the article data. | *<code>article</code> A reference to the JTableContent object that is being saved which holds the article data. | ||
*<code>isNew</code> A boolean which is set to true if the content is about to be created. | *<code>isNew</code> A boolean which is set to true if the content is about to be created. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
Boolean. Result will affect the saving process. See description for details. | Boolean. Result will affect the saving process. See description for details. | ||
| − | |||
| − | |||
| − | |||
==onContentAfterSave== | ==onContentAfterSave== | ||
===Description=== | ===Description=== | ||
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. | 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. | ||
| + | |||
===Parameters=== | ===Parameters=== | ||
| + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. | ||
*<code>article</code> A reference to the JTableContent object that is being saved which holds the article data. | *<code>article</code> A reference to the JTableContent object that is being saved which holds the article data. | ||
*<code>isNew</code> A boolean which is set to true if the content is about to be created. | *<code>isNew</code> A boolean which is set to true if the content is about to be created. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
None. Result will be omitted. | None. Result will be omitted. | ||
| − | |||
| − | |||
| − | |||
| − | == | + | ==onContentPrepareForm== |
===Description=== | ===Description=== | ||
| − | Called | + | 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. |
| + | |||
===Parameters=== | ===Parameters=== | ||
| − | *<code> | + | *<code>form</code> The JForm object to be displayed. Use the $form->getName() method to check whether this is the form you want to work with. |
*<code>data</code> An object containing the data for the form. | *<code>data</code> An object containing the data for the form. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
*<code>boolean</code> True if method succeeds. | *<code>boolean</code> True if method succeeds. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == | + | ===Example=== |
| + | *[https://www.github.com/joomla/joomla-cms/tree/master/plugins/user/profile/profile.php#L168 plugins/user/profile/profile.php] | ||
| + | |||
| + | ==onContentPrepareData== | ||
===Description=== | ===Description=== | ||
| − | Called | + | 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. |
| + | |||
===Parameters=== | ===Parameters=== | ||
| − | *<code> | + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. |
*<code>data</code> An object containing the data for the form. | *<code>data</code> An object containing the data for the form. | ||
| + | |||
===Return Value=== | ===Return Value=== | ||
*<code>boolean</code> True if method succeeds. | *<code>boolean</code> True if method succeeds. | ||
| − | === | + | |
| − | * | + | ===Example=== |
| − | *< | + | *[https://www.github.com/joomla/joomla-cms/tree/master/plugins/user/profile/profile.php#L51 plugins/user/profile/profile.php] |
| − | *< | + | |
| − | *< | + | ==onContentBeforeDelete== |
| + | ===Description=== | ||
| + | This is an event that is called right before the content is deleted from the database. You can abort the delete by returning false. In the case of <code>JModelLegacy</code> for example the error will then be set by calling <code>$this->setError($table->getError);</code> to be displayed to user. | ||
| + | |||
| + | ===Parameters=== | ||
| + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. | ||
| + | *<code>data</code> A reference to the JTableContent object that is being deleted which holds the article data. | ||
| + | |||
| + | ===Return Value=== | ||
| + | Boolean. Result will affect the saving process. See description for details. | ||
| + | |||
| + | ===Example=== | ||
| + | *[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/joomla/joomla.php#L89 plugins/content/joomla/joomla.php] | ||
| + | |||
| + | ==onContentAfterDelete== | ||
| + | ===Description=== | ||
| + | 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. | ||
| + | |||
| + | ===Parameters=== | ||
| + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. | ||
| + | *<code>article</code> A reference to the JTableContent object that has been deleted which holds the article data. | ||
| + | |||
| + | ===Return Value=== | ||
| + | None. Result will be omitted. | ||
| + | |||
| + | ===Example=== | ||
| + | [https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/finder/finder.php#L61 content/finder/finder.php] | ||
| + | |||
| + | ==onContentChangeState== | ||
| + | ===Description=== | ||
| + | This is an event that is called after content has its state change (e.g. Published to Unpublished). | ||
| + | |||
| + | ===Parameters=== | ||
| + | *<code>context</code> 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). Use this to check whether you are in the desired context for the plugin. | ||
| + | *<code>$pks</code> An array of primary key ids of the content that has changed state. | ||
| + | *<code>$value</code> The value of the state that the content has been changed to. | ||
| + | |||
| + | ===Return Value=== | ||
| + | None. Result will be omitted. | ||
| + | |||
| + | ===Example=== | ||
| + | [https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/finder/finder.php#L80 content/finder/finder.php] | ||
| + | |||
| + | ==onContentSearch== | ||
| + | |||
| + | ==onContentSearchAreas== | ||
| + | |||
| + | |||
<noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude> | <noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude> | ||
Revision as of 06:28, 5 February 2014
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. This list gives a brief description of each event, what their parameters are, and some examples of their use in core plugins.
onContentPrepare[edit]
Description[edit]
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.
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.&articleA 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).¶msA reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.pageAn integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.
Return Value[edit]
None. Results are returned by modifying the referenced arguments. Sometimes a boolean might be returned to check for success or failure of the event.
Example[edit]
onContentAfterTitle[edit]
Description[edit]
This event only exists in Joomla 
. 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 onPrepareContent for that purpose. Note this event has special purpose in com_content for use in handling the introtext.
Parameters[edit]
See the onPrepareContent event for additional discussion of these parameters.
contextThe 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). Use this to check whether you are in the desired context for the plugin.&articleThe article that is being rendered by the view.¶msAn associative array of relevant parameters.limitstartAn integer that determines the "page" of the content that is to be generated.
Return Value[edit]
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.
onContentBeforeDisplay[edit]
Description[edit]
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 onPrepareContent for that purpose.
Parameters[edit]
See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value.
contextThe 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). Use this to check whether you are in the desired context for the plugin.&articleThe article that is being rendered by the view.¶msAn associative array of relevant parameters.limitstartAn integer that determines the "page" of the content that is to be generated.
Return Value[edit]
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.
Example[edit]
onContentAfterDisplay[edit]
Description[edit]
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 onPrepareContent for that purpose.
Parameters[edit]
See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value.
contextThe 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). Use this to check whether you are in the desired context for the plugin.&articleThe article that is being rendered by the view.¶msA JRegistry object of merged article and menu item params.limitstartAn integer that determines the "page" of the content that is to be generated.
Return Value[edit]
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.
onContentBeforeSave[edit]
Description[edit]
This is an event that is called right before the content is saved into the database. You can abort the save by returning false. In the case of JModelLegacy for example the error will then be set by calling $this->setError($table->getError); to be displayed to user.
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.articleA reference to the JTableContent object that is being saved which holds the article data.isNewA boolean which is set to true if the content is about to be created.
Return Value[edit]
Boolean. Result will affect the saving process. See description for details.
onContentAfterSave[edit]
Description[edit]
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.
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.articleA reference to the JTableContent object that is being saved which holds the article data.isNewA boolean which is set to true if the content is about to be created.
Return Value[edit]
None. Result will be omitted.
onContentPrepareForm[edit]
Description[edit]
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.
Parameters[edit]
formThe JForm object to be displayed. Use the $form->getName() method to check whether this is the form you want to work with.dataAn object containing the data for the form.
Return Value[edit]
booleanTrue if method succeeds.
Example[edit]
onContentPrepareData[edit]
Description[edit]
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.
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.dataAn object containing the data for the form.
Return Value[edit]
booleanTrue if method succeeds.
Example[edit]
onContentBeforeDelete[edit]
Description[edit]
This is an event that is called right before the content is deleted from the database. You can abort the delete by returning false. In the case of JModelLegacy for example the error will then be set by calling $this->setError($table->getError); to be displayed to user.
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.dataA reference to the JTableContent object that is being deleted which holds the article data.
Return Value[edit]
Boolean. Result will affect the saving process. See description for details.
Example[edit]
onContentAfterDelete[edit]
Description[edit]
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.
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.articleA reference to the JTableContent object that has been deleted which holds the article data.
Return Value[edit]
None. Result will be omitted.
Example[edit]
onContentChangeState[edit]
Description[edit]
This is an event that is called after content has its state change (e.g. Published to Unpublished).
Parameters[edit]
contextThe 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). Use this to check whether you are in the desired context for the plugin.$pksAn array of primary key ids of the content that has changed state.$valueThe value of the state that the content has been changed to.
Return Value[edit]
None. Result will be omitted.