Joomla! Discussion Forums

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.

Let´s see the XML file:



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!

Now, let´s see the plugin php code.

First, the "skeleton":



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?

So, here is the "REAL" plugin code:



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.

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!)



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

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



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.

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.



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:



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

Yes, Pentacle, you are right.

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



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!!

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" 

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 

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:



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


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

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.

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.

Thanks for sharing greatwitenorth.

I added (line 28)


and (line 31)


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

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


best

jimpa

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!!!

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!

OMG you don't know how timely this is... I've been sitting here for 2 weeks trying to learn how to do this myself. I'm going to have to really study this.. In my case I want to write a plug-in that will happen at registration time. and ONLY at registration time.
Hopefully with how well you've documented your work I can finally make mine succeed.
Thanks a milion!!!
How were you able to "search" the framework to find out what to "hook" into? I look at it and get lost really fast.

For registration, you can take a look at user events:
http://dev.joomla.org/component/option, ... er_events/

And there is a full list of all events for plugins in Joomla! here:
http://dev.joomla.org/component/option, ... s:plugins/

wow! tyvm!! idk why I couldn't find that information myself... your a life saver... I'm going to forget for now about making this a cb plug-in and just make it a j! plug-in

Hello Jbruni,

It seems to me you made a very usefull plugin.
Just what we needed for our site.
One question:
I want to have more than one recipients a notification when an author changes an article.
Is that possible ?
And when yes: how do I configure it ?

Kind regards,

Peter

Find this line in the plugin and after that add new recipients with these 3 methods:

I needed a Joomla 1.0 version...
For any interested in a similar extension (supporting both J!1.0 and 1.5)
First release did notify about new entries only. I asked the developer for a "notify on change" feature...
here it is:
http://extensions.joomla.org/component/ ... Itemid,35/

CU

I create a plugin named extranews. Here is the declaration of plugin:
But When I call JText::_('SOMETEXT'), it's still show SOMETEXT only not the difinition text.

After I install, I did not see 2 above language files in /language/en-GB and /language/vi-VN folders.

I try with:
I found 2 files in /plugins/content/extranews/lang folder.

But both of 2 statements, I can not call the definition tetx through JText::_('SOMETHING');

What is the problem or my declaration in XML is wrong?

Thanks

P/S: My Joomla is 1.5.3

Hi

I'm looking for a way to use notification but only when i want to do that. For example, i would like to tick a checkbox and notify users when i add a new article but i don't want to do same thing on edit. It is posible to let users check only when he want to notify others? I use Joomla for our company intranet, so only trusted users can add articles.

P.S: it is posible to use this plugin in 1.0.15 also?

Thanks

thanks for sharing

how to call a plugin when editting content from the front-end? I tried all plugin-types (content, editor etc) , the only thing that consistently manages to crash the page is ' editors-xtd'.
And with which event to call?

o, I got it. plugin type 'system' will do that. I just forgot to put my actual plugin file in that directory.

can you please give me more details about calling a plugin in frontend? The plugin i need should allow Publishers to notifiy teams when add/edit a content by selecting an email address from a dropdown list.

thank you

as I said: make it a plugin with type 'system. then call it any time you like. see wiki for event handlers:
http://docs.joomla.org/Reference:Conten ... gin_System
hope that helps.