My first Plugin

[jbruni]

I will share some experiences from the "making of" my first Plugin.

Please, download it and unzip: http://br.geocities.com/joaohbruni/plugin_1.5_notify_admin.zip

You will see there are only 4 files in there:

1- notifyadmin.xml  (the Plugin installation and configuration file)

2- notifyadmin.php (this is the Plugin itself)

3- en-GB.plg_system_notifyadmin.ini  (language file - english)

4- pt-BR.plg_system_notifyadmin.ini  (language file - portuguese)

What this plugin does? It sends a notification e-mail when an Author edits an article.

In Joomla! 1.5, the users who are Authors are allowed to EDIT their articles AFTER they are already PUBLISHED.

That´s nice.

I am building a website with Joomla! 1.5, and I need to receive an e-mail when this thing happens (an author edit an article). So, I started making the plugin...

There were TWO fronts:

1- Installation, Configuration and Language issues.
2- The code to detect the situation and send an e-mail, without changing the core itself.

[jbruni]

Let´s see the XML file:

Code: Select all

<?xml version="1.0" encoding="iso-8859-1"?>
<install version="1.5" type="plugin" group="system">
    <name>System - Notify admin plugin</name>
    <version>1.0.1</version>
    <author>J Bruni</author>
    <creationDate>November 2007</creationDate>
    <copyright>(C) 2007 J Bruni. All rights reserved.</copyright>
    <license>GNU/GPL</license>
    <authorEmail>[email protected]</authorEmail>
    <authorUrl>www.radiosai.org.br</authorUrl>
    <description>Notify administrator when article is edited by author</description>
    <files>
        <filename plugin="notifyadmin">notifyadmin.php</filename>
    </files>
    <languages>
        <language tag="en-GB">en-GB.plg_system_notifyadmin.ini</language>
        <language tag="pt-BR">pt-BR.plg_system_notifyadmin.ini</language>
    </languages>
    <params>
        <param name="subject" type="text" size="18" default="" label="Subject of notification e-mail" description="Text between brackets at beggining of notification e-mail subject" />
        <param name="recipient" type="text" size="45" default="" label="Recipient(s) of notification e-mail" description="Comma-separated list of e-mail addresses to receive notification e-mail" />
    </params>
</install>

The first declaration in important:



It means the Joomla! version is 1.5, the extension type is plugin, and the type of plugin is system.

What type of plugin is your plugin? What types of plugin exist? Look at the Plugins installed, at the Administrator interface... you will see the following types:

- authentication
- content
- editors
- editors-xtd
- search
- system
- user
- xmlrpc

I don´t know if there are more types of plugin. (See more on this: What Are Extensions?)

When making your own Plugin, substitute in the XML file:

- name (full name of the Plugin)
- version (version of the Plugin)
- author (your name)
- creationDate (follow the month / year format)
- copyright  (copyright info)
- license (GNU/GPL is Joomla´s license)
- authorEmail (your e-mail)
- authorUrl  (your URL)

Next, there is the description

Notify administrator when article is edited by author

This string can be translated in the language file!  Yes, it appears in the administrator interface, and can be translated!

Then, a list of the files used by the plugin (except language ones and the XML itself):


   
        notifyadmin.php
   


Well... in our case, there is a single file. Attention to the naming conventions. The plugin, the XML file and the php file have the same name.

Next, the language files:


   
        en-GB.plg_system_notifyadmin.ini
        pt-BR.plg_system_notifyadmin.ini
   


The naming is important. First, the language id ("en-GB", "pt-BR", etc.), then a dot, then "plg", then a underscore, then the type of plugin ("system", in our case), then another underscore, then the name of the plugin, then a dot, and finally the "ini" extension.

And, at last, the configuration parameters that will appear in the admin interface.


   
       
       
   


I simply downloaded some Joomla! 1.5 plugins from the Extensions Directory and looked at how the "param" declarations were. It becomes easy to find out how to do it yourself.

Here, we have TWO parameters, both TEXT type.
The first, subject, for the e-mail subject.
The second, recipient, to store the e-mail destination address.

What is important:

- The name of the parameter (will be used in the plugin code).
- You can set a default value.
- The label and the description attributes are also translated! 

Yes! In the portuguese language file, they are translated, and in the admin interface, they appear translated. It is wonderful!

[jbruni]

Now, let´s see the plugin php code.

First, the "skeleton":

Code: Select all

<?php
defined( '_JEXEC' ) or die( 'Restricted access' );

class plgSystemNotifyadmin 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.
    *
    * @access   protected
    * @param   object $subject The object to observe
    * @param    array  $config  An array that holds the plugin configuration
    * @since   1.0
    */
   function plgSystemNotifyadmin(& $subject, $config)
   {
   
      parent::__construct($subject,$config);
   }

   function onAfterRoute()
   {

      // THE "TRUE" CODE COMES HERE

   }

}
?>

What should be noticed here?

1- The name of the class: "plgSystemNotifyadmin"
First, plg, then the cappitalized type of plugin (System), then, the cappitalized name of the plugin ("Notifyadmin")

2- The name of the constructor: must be the same name of the class.

3- The name of the event function:
Well, this took me quite some time to find out the correct event to use.
Look at the index.php from Joomla!'s root. There you will find the triggering of some events:

$mainframe->triggerEvent('onAfterInitialise');
$mainframe->triggerEvent('onAfterRoute');
$mainframe->triggerEvent('onAfterDispatch');
$mainframe->triggerEvent('onAfterRender');

Well... if you name a function inside your plugin class with the same name of an event that is triggered, you know what will happen? Yes! Your plugin function will be called when the event happens! (or "the event is triggered")

Which event to choose? I didn´t know, so I tried "OnAfterDispatch"... It didn´t work the way I wanted. Then I discovered that "OnAfterRoute" was the right one (the right moment) for this situation. It worked perfectly!

So, simply naming the function with the event name (OnAfterRoute) does the magic of being called when the event is triggered. Isn´t it wonderful?

[jbruni]

So, here is the "REAL" plugin code:

Code: Select all

<?php
   function onAfterRoute()
   {

      $user =& JFactory::getUser();
      $isAuthor = ($user->usertype == 'Author');
      $isSaving = (JRequest::getCmd( 'task' ) == 'save') && (JRequest::getCmd( 'option' ) == 'com_content');

      if ($isAuthor && $isSaving) {

         $lang   =& JFactory::getLanguage();
         $lang->load( 'plg_system_notifyadmin' , JPATH_ADMINISTRATOR );

         $msg = $user->name . ' <' . $user->email .'> ' . JText::_( 'has edited article' ) . ' "' . JRequest::getVar( 'title' ) . ""\n";
         $URI =& JFactory::getURI();
         $msg .= 'URL: ' . $URI->current() . '?view=article&catid=' . JRequest::getInt( 'catid' ) . '&id=' . JRequest::getInt( 'id' ) . '&Itemid=' . JRequest::getInt( 'Itemid' ) . '&option=com_content' . "\n";

         $mail =& JFactory::getMailer();
         $mail->setSubject( '[' . $this->params->get( 'subject' , JText::_( 'ARTICLE EDITED' ) ) . '] ' . JRequest::getVar( 'title' ) );
         $mail->setBody($msg);
         $mail->addRecipient( $this->params->get( 'recipient' , $mail->From ) );
         $mail->Send();

      }

   }
?>

Let´s see step by step:


$user =& JFactory::getUser();
$isAuthor = ($user->usertype == 'Author');
$isSaving = (JRequest::getCmd( 'task' ) == 'save') && (JRequest::getCmd( 'option' ) == 'com_content');


What are the conditions to send the notification e-mail?
First, the user must be an Author.
Second, he/she must be saving an existing article.

Looking at the finished code, it seems easy... but, how did I find that?

Before, I used "file_put_contents" php function to show me some information about $_REQUEST and some Joomla! objects... as JUser, JSession, JMail... and the global $mainframe!

(And I also did a lot of Joomla! 1.5 API Reference searches ans researches.)


global $mainframe;

$user =& JFactory::getUser();
$session =& JFactory::getSession();
$mail =& JFactory::getMailer();

$info = "\nRequest:\n" . print_r($_REQUEST, true) . "\n";
$info .= "\nUser:\n" . print_r($user, true) . "\n";
$info .= "\nSessiont:\n" . print_r($session, true) . "\n";
$info .= "\nMail:\n" . print_r($mail, true) . "\n";
$info .= "\nMainframe:\n" . print_r($mainframe, true) . "\n\n";

file_put_contents("/path/to/a/directory/notifyadmin.txt", $info, FILE_APPEND);


Yes, I installed the plugin very BEFORE it was finished, so I could TEST & DEVELOP. With a minimum package, I installed the plugin via admin interface, and then started working in the code, and uploading the new versions of notifyadmin.php via FTP.

Then, with the snippet above inside OnAfterRoute function, I worked in the front-end, logging as an author, and editing an article.

With the output generated through "file_put_contents", I was able to identify how the conditions I needed (Author saving an article) were registered in the variables.

Answer: usertype == "Author" and task == "save" and option == "com_content"

This was "discovered" this way: using the front-end and looking at the "log" file generated inside the event handler (OnAfterRoute).

So, I was able to code:


$user =& JFactory::getUser();
$isAuthor = ($user->usertype == 'Author');
$isSaving = (JRequest::getCmd( 'task' ) == 'save') && (JRequest::getCmd( 'option' ) == 'com_content');


And the condition to send the notification e-mail was:


if ($isAuthor && $isSaving) {
//SEND THE NOTIFICATION
}


Now, let´s see the code that SENDS the notification, once the conditions are TRUE (an Author is saving an article)

What comes next was in fact the LAST piece of code I made. Everything was already working, except the TRANSLATION... the strings in the language file were not being used. Why?! Hummmm... I didn´t know I needed to explicitly LOAD the plugin language file. As I wasn´t successfull with the JPlugin loadLanguage function, I arranged myself with the following solution, found in a forum thread:


$lang  =& JFactory::getLanguage();
$lang->load( 'plg_system_notifyadmin' , JPATH_ADMINISTRATOR );


Why the plugin language file goes into the Admin... don´t ask me.

Following, we have some lines to build the e-mail body, with some useful information:

- author name
- author e-mail
- name of the edited article
- link to the article

For example: "John edited "Love is all you need", link: http://...."

Researching the API, and the "log" file, and analyzing an article URL, one can find everything needed:

- author name  =  $user->name
- author e-mail  =  $user->email
- name of the edited article  =  $_REQUEST['title']  or better:  JRequest::getVar( 'title' )
- link to the article... for this we need the catid, the id and the Itemid, all provided in JRequest...


$msg = $user->name . ' <' . $user->email .'> ' . JText::_( 'has edited article' ) . ' "' . JRequest::getVar( 'title' ) . "\"\n";
$URI =& JFactory::getURI();
$msg .= 'URL: ' . $URI->current() . '?view=article&catid=' . JRequest::getInt( 'catid' ) . '&id=' . JRequest::getInt( 'id' ) . '&Itemid=' . JRequest::getInt( 'Itemid' ) . '&option=com_content' . "\n";


Note the use of JText. If that string is present in the language file... it will be translated!  :laugh:

And what comes next? Let´s generate and send the e-mail? Yes, it´s time to use the plugin parameters! The "SUBJECT" string and the "RECIPIENT"!

To have access to the plugin parameters, use the following code pattern:      (thanks, Pentacle!)


$this->params->get( '[i]parameter[i]' )


Finally, the easiest piece of code, which sends the e-mail using JMail:


$mail =& JFactory::getMailer();
$mail->setSubject( '[' . $this->params->get( 'subject' , JText::_( 'ARTICLE EDITED' ) ) . '] ' . JRequest::getVar( 'title' ) );
$mail->setBody($msg);
$mail->addRecipient( $this->params->get( 'recipient' , $mail->From ) );
$mail->Send();


What should be noticed?

The use of $this->params->get to access the plugin parameters.


$this->params->get( 'subject' , JText::_( 'ARTICLE EDITED' ) )
$this->params->get( 'recipient' , $mail->From )


First, the name of the parameter (as defined in the XML file); second, an optional DEFAULT value.

That´s it. You have your "notificator" plugin.

I´d like to thank Nicolas Ogier, from "Website Name" plugin, from which I learned a lot.

[jbruni]

The language file has all the used STRINGS that outputs TEXT to the USER, in the following places/ways:

- XML description tag
- XML label and description attributes from param tags
- JText::_( 'string' ) used by the plugin (after loading the plugin language file!)

Code: Select all

# $Id: en-GB.plg_system_notifyadmin.ini
# Joomla! Project
# Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM

NOTIFY ADMINISTRATOR WHEN ARTICLE IS EDITED BY AUTHOR=Notify administrator when article is edited by author
ARTICLE EDITED=ARTICLE EDITED
SUBJECT OF NOTIFICATION E-MAIL=Subject of notification e-mail
TEXT BETWEEN BRACKETS AT BEGGINING OF NOTIFICATION E-MAIL SUBJECT=Text between brackets at beggining of notification e-mail subject
RECIPIENT(S) OF NOTIFICATION E-MAIL=Recipient(s) of notification e-mail
COMMA-SEPARATED LIST OF E-MAIL ADDRESSES TO RECEIVE NOTIFICATION E-MAIL=Comma-separated list of e-mail addresses to receive notification e-mail
HAS EDITED ARTICLE=has edited article

The english language file is kind of... repetitive... don´t you think?

[jbruni]

But... take a look at the portuguese language file!

Code: Select all

# $Id: pt-BR.plg_system_notifyadmin.ini
# Joomla! Project
# Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM

NOTIFY ADMINISTRATOR WHEN ARTICLE IS EDITED BY AUTHOR=Notificar administrador quando um artigo é editado pelo autor
ARTICLE EDITED=ARTIGO EDITADO
SUBJECT OF NOTIFICATION E-MAIL=Assunto do e-mail de notificação
TEXT BETWEEN BRACKETS AT BEGGINING OF NOTIFICATION E-MAIL SUBJECT=Texto entre colchetes no início do assunto do e-mail de notificação
RECIPIENT(S) OF NOTIFICATION E-MAIL=Destinatário(s) do e-mail de notificação
COMMA-SEPARATED LIST OF E-MAIL ADDRESSES TO RECEIVE NOTIFICATION E-MAIL=Lista de endereços de e-mail (separados por vírgula) que irão receber o e-mail de notificação
HAS EDITED ARTICLE=editou o artigo

It´s not repetitive.

It´s important to declare all strings in the english language file because it will be the base for every other translation...

Thank you.

[Pentacle]

Hi Bruni, it's really very good to see you again. :)

Btw, I haven't tried the plugin yet but I'll give it a go when I have time.

I'd like to ask something that I found weird.

Code: Select all

$plugin =& JPluginHelper::getPlugin( 'system' , 'notifyadmin' );
$params = new JParameter( $plugin->params );

Do we have to use that code? I think the constructor pass the params to a property of the class.

This is a code example from one of my plugins:

Code: Select all

if ( $this->params->get( 'frontpage' ) == '1' ) {

But there is a difference between my constructor and yours.  You use $config and I use $params. So can it be $this->config?

edit:typo

[jbruni]

I'd like to ask something that I found weird.

Code: Select all

$plugin =& JPluginHelper::getPlugin( 'system' , 'notifyadmin' );
$params = new JParameter( $plugin->params );

Do we have to use that code? I think the constructor pass the params to a property of the class.

This is a code example from one of my plugins:

Code: Select all

if ( $this->params->get( 'frontpage' ) == '1' ) {

Yes, Pentacle, you are right.

I changed the code, and it worked perfectly. Below, the new version:

Code: Select all

<?php
   function onAfterRoute()
   {
      $user =& JFactory::getUser();
      $isAuthor = ($user->usertype == 'Author');
      $isSaving = (JRequest::getCmd( 'task' ) == 'save') && (JRequest::getCmd( 'option' ) == 'com_content');

      if ($isAuthor && $isSaving) {

         $lang   =& JFactory::getLanguage();
         $lang->load( 'plg_system_notifyadmin' , JPATH_ADMINISTRATOR );

         $msg = $user->name . ' <' . $user->email .'> ' . JText::_( 'has edited article' ) . ' "' . JRequest::getVar( 'title' ) . ""\n";
         $URI =& JFactory::getURI();
         $msg .= 'URL: ' . $URI->current() . '?view=article&catid=' . JRequest::getInt( 'catid' ) . '&id=' . JRequest::getInt( 'id' ) . '&Itemid=' . JRequest::getInt( 'Itemid' ) . '&option=com_content' . "\n";

         $mail =& JFactory::getMailer();
         $mail->setSubject( '[' . $this->params->get( 'subject' , JText::_( 'ARTICLE EDITED' ) ) . '] ' . JRequest::getVar( 'title' ) );
         $mail->setBody($msg);
         $mail->addRecipient( $this->params->get( 'recipient' , $mail->From ) );
         $mail->Send();

      }
   }
?>

The parameters can be directly accessed through $this->params->get( 'parameter' )

Also, the "global $mainframe" declaration was removed, since it was not being used.

I think I´ll edit the previous posts including the new improvements.

Thank you very much!!

[jbruni]

Now you can find the plugin in the Extensions Directory:  :laugh:

>>> Notify Admin <<<

With the recent clean up in the code, I changed the version number from 1.0.0 to 1.0.1 -    version "101" 

[jbruni]

I released J! (1.5 RC3) website with this plugin at november 15th. I couldn´t wait RC4 or stable... It´s a very simple site. No problem. And I am not using the known unstable features.

  http://www.radiosai.org.br



Observation: this is an edit - this post was generated by mistake 

[greatwitenorth]

Great plugin! I needed to be notified when editors updated content too so I added these few lines of code to notifyadmin.php

I added this line after line 26:

Code: Select all

$isEditor = ($user->usertype == 'Editor');

I modified line 29 (or line 30 if you've added the previous line of code) to look like this:

Code: Select all

if ( ($isEditor || $isAuthor) && $isSaving) {

Maybe we can make this a parameter in the admin for the module? Thanks again!

[OwnedThawte]

jbruni,
Very well done with this plugin. I have built a very large college website http://www.lakemichigancollege.edu/ and a co-worker and I make all content changes. We are looking to implement some security measures before handing out editing rights to employees. This is a great step in monitoring that I needed.

My hats off to you, Thank you and keep up the great work.

P.S. One more thing, is there anyway the coding can be modified so that in the E-Mail maybe the before and after product of the results of the users modification can be displayed?

Thanks in advance!
-Stan Jr.

[epleste]

jbruni,
P.S. One more thing, is there anyway the coding can be modified so that in the E-Mail maybe the before and after product of the results of the users modification can be displayed?
Thanks in advance!
-Stan Jr.

I don't think this is currently possible. I've been following the threads for the J1.6 whitepapers and there are a couple of requests for extra handlers to be inserted into the core code around the edit functions so extensions can do this sort of thing.

[epleste]

Great plugin! I needed to be notified when editors updated content too so I added these few lines of code to notifyadmin.php

Maybe we can make this a parameter in the admin for the module? Thanks again!

Thanks for sharing greatwitenorth.

I added (line 28)

Code: Select all

$isPublisher = ($user->usertype == 'Publisher');

and (line 31)

Code: Select all

if ( ($isEditor || $isAuthor || $isPublisher) && $isSaving) {

so I get a complete audit trail for pages (a big ugly email trail but better than nothing)

[jimpa]

Is is possible with this plugin to add the ability to be notified when a new article is created from the backend?


best

jimpa

[rexkramer]

Hello,
recently found your nice plugin in the ext-directory... great solution, especially the notify on "changes"! i am missing the notify functinality in default joomla install. Should be a build-in feature ;-)

Are there any chances for a Joomla 1.0.x version?

Please...
TIA!!!

[jbruni]

Thank you all very much for the comments, suggestions, requests and everything else!

I am sorry to inform that I don´t know when I will have enough free time again to work with this project.

I´d like to make some improvements in the plugin, but I have absolutely no plans on making a version 1.0.x compatible plugin at the moment.

Thanks, again!