Dextercowley: add information about installing the plugin

2009-02-06T23:16:35Z

add information about installing the plugin

Dextercowley: new tip for using plugins to make automatic changes when an article is saved.

2009-02-06T23:06:24Z

new tip for using plugins to make automatic changes when an article is saved.

New page

==Overview==
Plugins are the simplest extensions to write. A simple plugin requires only two files. Yet plugins can be extremely handy.

One common case for using plugins is doing some customized processing every time an article is saved. For example:
* Change the published state of an article.
* Add standard text to articles.
* Set the Section or Category for an article.

Let's see how you can use a simple plugin to do these types of tasks.

==First Plugin==
A simple plugin has two files. One is an XML file that tells Joomla! how to install the plugin. The other is the actual plugin PHP code.

To make it as easy as possible for people to write plugins, Joomla! includes example plugins in every installation. In our example, we are writing a "content" plugin, since we are working with articles. So the two example files we can use as guidelines are <tt>plugins/content/example.xml</tt> amd <tt>plugins/content/example.php</tt>.

The XML file for our example is called <tt>modifyarticle.xml</tt>. We just copied the file <tt>plugins/content/example.xml</tt> to <tt>modifyarticle.xml</tt> and put it in a new folder outside of the Joomla! installation. (''We will use the Joomla! install program later on to add this to our Joomla! system. So for now we want to keep this separate from Joomla!.'') Then we edited it as follows:
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
<name>Modify Edited Articles</name>
<creationDate>January 2009</creationDate>
<author>Joomla Doc Team</author>
<authorEmail>myemail@myemail.com</authorEmail>
<authorUrl>http://joomlacode.org</authorUrl>
<copyright>Copyright (c) 2009</copyright>
<license>GPL</license>
<version>1.0.0</version>
<description>Example plugin for Joomla! wiki.</description>
<files>
<filename plugin="modifyarticle">modifyarticle.php</filename>
</files>
</install>
</source>
Next, we copy the file <tt>plugins/content/example.php</tt> to <tt>modifyarticle.php</tt> and put it in the same folder outside of the Joomla! installation. Then we edit this file so it reads as follows:
<source lang="php">
<?php
/**
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/

// Check to ensure this file is included in Joomla!
defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.plugin.plugin' );

class plgContentModifyArticle extends JPlugin
{

/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @param object $subject The object to observe
* @param object $params The object that holds the plugin parameters
* @since 1.5
*/
function plgContentModifyArticle ( &$subject, $params )
{
parent::__construct( $subject, $params );
}

/**
* Example before save content method
*
* Method is called right before content is saved into the database.
* Article object is passed by reference, so any changes will be saved!
* NOTE: Returning false will abort the save with an error.
* You can set the error by calling $article->setError($message)
*
* @param object A JTableContent object
* @param bool If the content is just about to be created
* @return bool If false, abort the save
*/
function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
$user =& JFactory::getUser(); // get the user
if ($user->usertype == 'Author') { // unpublish if user is "Author"
$article->state = 0; // from dev 11:59
}
return true;
}
}
</source>
Notice that the <tt>example.php</tt> file has six methods plus the constructor. These document the six possible events that you can use for plugins. In our example, we want to modify the article just before it is saved to the database. So we call our method (or function) "onBeforeContentSave". This method name must be exactly as shown. The name is what tells Joomla! when to run our plugin.

In standard Joomla!, when a user in the "Author" group first submits a new article, it is set to "Unpublished". However, once the article has been published, this user can edit the article and it stays published. In our example, we want to change this so that, each time an article is edited by a user in the "Author" group, it gets changed back to "Unpublished".

The code above does that. First, we get the user. Then, if the user is in the "Author" group, we change the article's "state" to zero, meaning "Unpublished". Notice that the method has <tt>$article</tt> as a parameter, so its fields and methods are all available to us.

==Add Standard Text==
Once we have the basic framework, changing the plugin to do other things is simple. For example, say we want to add standard text to any article submitted by a user in the "Author" group. Here is the code for the "onBeforeContentSave()" method:
<source lang="php">
function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
$newText = '<p>This is my new text to add to the article.</p>';
$user =& JFactory::getUser(); // get the user
if ($user->usertype == 'Author') {
if ($article->fulltext) {
if (strpos($article->fulltext, $newText) == 0) {
$article->fulltext .= $newText;
}
}
else {
if (strpos($article->introtext, $newText) == 0) {
$article->introtext .= $newText;
}
}
}
return true;
}
</source>
In this code, we have some standard text we put in the <tt>$newText</tt> variable. Then we deal with a complication of the <tt>$article</tt> object. Joomla! articles can have an optional "Read more..." break. If they don't have one, the entire text of the article is in the <tt>introtext</tt> field. If there is a "Read more..." break, then the part of the article after the break is in the <tt>fulltext</tt> field.

So, in the code, we have to handle both cases. If there is something in <tt>fulltext</tt>, then we add the standard text there. Otherwise, we add it to <tt>introtext</tt>.

There is one other complication. We don't want to add the standard text if it already there. Otherwise, we would keep adding more copies of it each time the article is edited. So we test to see if it already part of the article's text and we only add it if it isn't already there.

Notice that the second parameter of this method is <tt>$isNew</tt>. This is a boolean that is <tt>true</tt> if this is a new article. So we could test for that if we only wanted to add the text for new article submissions.

==Set the Section or Category==
Setting the Section or Category ID of an article is very easy. For example, in the Sample Website, this code
<source lang="php">
$article->sectionid = '4';
$article->catid = '25';
</source>
would change the article's Section to "About Joomla!" and Category to "The Project". Note that you need to use the "id" fields for the Section and Category. In this example, you also might want to remove these fields from the front-end form (by using a [[How_to_override_the_output_from_the_Joomla!_core|template override]])

It is useful to understand that any of the article's fields are available here. Below is a partial list:
* title: article's title
* alias: article's alias
* state: 0 for unpublished, 1 for published, -1 for archived
* created: date created
* created_by: user id of author
* created_by_alias: author alias field
* modified: date last modified
* modified_by: user id of last author to modify
* metakey: Metadata Information / Keywords
* metadesc: Metadata Information / Description
* access: 0 for public, 1 for registered, 2 for special

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

@@ Line 92: / Line 92: @@
 The code above does that. First, we get the user. Then, if the user is in the "Author" group, we change the article's "state" to zero, meaning "Unpublished". Notice that the method has <tt>$article</tt> as a parameter, so its fields and methods are all available to us.
 ==Add Standard Text==
@@ Line 132: / Line 141: @@
 would change the article's Section to "About Joomla!" and Category to "The Project". Note that you need to use the "id" fields for the Section and Category. In this example, you also might want to remove these fields from the front-end form (by using a [[How_to_override_the_output_from_the_Joomla!_core|template override]])
 It is useful to understand that any of the article's fields are available here. Below is a partial list:
 * title: article's title
@@ Line 144: / Line 154: @@
 * metadesc: Metadata Information / Description
 * access: 0 for public, 1 for registered, 2 for special
 [[Category:Tips and tricks]]
 [[Category:Tips and tricks 1.5]]

Make changes to an article automatically using a plugin - Revision history

Dextercowley: add information about installing the plugin

Dextercowley: new tip for using plugins to make automatic changes when an article is saved.