The Joomla! Community Magazine™

Joomla! 3.2 New Features: Post-Install Messages

Written by | Sunday, 01 December 2013 00:00 | Published in 2013 December
Among the many new features released with version 3.2 of Joomla!, the one that most caught my interest, and perhaps one of the less publicized but certainly very useful for administrators and interesting for developers, is the so-called "post-installation messages". These inform the site administrator about features that require your attention after the successful installation of an extension.

Let's examine in a little more in detail the characteristics and how they can be used by extension developers. If you have already installed Joomla! 3.2, you may have noticed in the control panel an informational message like the image below. By clicking the "Review Messages" button, you will be notified of the availability of the new "Two-factor authentication" that requires your attention. This is the first example of a concrete application which uses this new feature.PIM-Administration-Control-Panel

What is it?

It is a system for managing the post-installation and upgrade messages, and it can be used when installing or upgrading extensions. For example, after installation, many extensions require configuration tasks that are mandatory for the proper functioning of the extension itself, and that for their intricacy, cannot be automatically enabled. The aforementioned "Two-factor authentication", for example, using the new notification system, informs you that the feature is available but in order to do the job right some configuration settings are required on your part.

Il messaggio postinstallazione

How it works

The work is done by the new component com_postinstall that manages the interaction between the notification system and the extensions, through the definition of two functions:

  • action (actions to perform, ex. redirect to configuration page)
  • condition (when to display the message, ex. after install)

The data is stored in the new table # _postinstall_messages.

Basically it is an excellent example of how to use the new Joomla! Rapid Development Framework appilcation alias FOF (one of the many new features introduced from 3.2) to rapidly develop Joomla! extensions.

How to use it in your extensions

The use of the post-install messages notification system by extension developers is fairly simple. Suppose we want to use this system to notify the site administrator that after the extension has been installed (condition), some configuration tasks need to be done. In our case, the extension is supposed to be a plugin type system, that is named "example", and we want to redirect the administrator after clicking on the notification message button, to the plugin configuration page (action).

We need to add two things compared to a normal extension:

  • create a file containing the definition of the two functions (postinstall_action, postinstall_condition)
  • insert the extension information in the table # _postinstall_messages

For simplicity's sake I created a new folder named "postinstall" in the root of my plugin, and created  the file actions.php that will contain the code for the two functions I'm going to define. This file will be referenced in the table #_postinstall_messages in the fields action_file and condition_file.

Let's define in detail the two functions (postinstall_action, postinstall_condition).

The postinstall_condition function: this will handle the notification condition of the messsage. In our case the condition will be when the plugin is installed but not enabled:

function example_postinstall_condition()
{
	$db = JFactory::getDbo();
	$query = $db->getQuery(true)
		->select('*')
		->from($db->qn('#__extensions'))
		->where($db->qn('type') . ' = ' . $db->q('plugin'))
		->where($db->qn('enabled') . ' = ' . $db->q('1'))
		->where($db->qn('folder') . ' = ' . $db->q('system'))
		->where($db->qn('element') . ' = ' . $db->q('example'));
	$db->setQuery($query);
	$enabled_plugins = $db->loadObjectList();
	return count($enabled_plugins) == 0;
}

 

The postinstall_action function: this will be activated when the admin clicks the button that is shown in the notification message. In our case the actions are: the plugin is set as enabled, and the admin is redirected to the plugin configuration page:

function example_postinstall_action(){
 // Enable the plugin
 $db = JFactory::getDbo();
   $query = $db->getQuery(true)
 	->select('*')
 	->from($db->qn('#__extensions'))
 	->where($db->qn('type') . ' = ' . $db->q('plugin'))
 	->where($db->qn('enabled') . ' = ' . $db->q('0'))
 	->where($db->qn('folder') . ' = ' . $db->q('system'))
 	->where($db->qn('element') . ' = ' . $db->q('example'));
 $db->setQuery($query);
 $enabled_plugins = $db->loadObjectList();
 
 $query = $db->getQuery(true)
 	->update($db->qn('#__extensions'))
 	->set($db->qn('enabled') . ' = ' . $db->q(1))
 	->where($db->qn('type') . ' = ' . $db->q('plugin'))
 	->where($db->qn('folder') . ' = ' . $db->q('system'))
 	->where($db->qn('element') . ' = ' . $db->q('example'));
 $db->setQuery($query);
 $db->execute();
  
  //Redirect the user to the plugin configuration page
 $url = 'index.php?option=com_plugins&task=plugin.edit&extension_id='
           .$enabled_plugins[0]->extension_id ;
 JFactory::getApplication()->redirect($url);
}

The last thing that we need to do to finish our work is to insert configuration data in the table #_postinstall_messages. To do this we use the manifest files scriptfile tag: 

 

<scriptfile>example.script.php</scriptfile>

 

In order to be able to run a script during the installation or upgrade of our extension, in particular we need to update these fields:

  •   action and condition_method  

with the names of the respective functions previously defined as example_postinstall_action () and example_postinstall_condition ()

  •   action_file and condition_file

with the name of the file which contains the respective function (in our case actions.php).

The code could look something like this:

class plgSystemexampleInstallerScript
{
  /*
  * $parent is the class calling this method.
  * install runs after the database scripts are executed.
  * If the extension is new, the install method is run.
  * If install returns false, Joomla will abort the install and undo everything already done.
  */
 function install( $parent ) {
     $db = JFactory::getDbo();
     $query = 'INSERT INTO '. $db->quoteName('#__postinstall_messages') .
              ' ( `extension_id`, 
                  `title_key`, 
                  `description_key`, 
                  `action_key`, 
                  `language_extension`, 
                  `language_client_id`, 
                  `type`, 
                  `action_file`, 
                  `action`, 
                  `condition_file`, 
                  `condition_method`, 
                  `version_introduced`, 
                  `enabled`) VALUES '
              .'( 700,
               "PLG_SYSTEM_EXAMPLE_POSTINSTALL_TITLE", 
               "PLG_SYSTEM_EXAMPLE_POSTINSTALL_BODY", 
               "PLG_SYSTEM_EXAMPLE_POSTINSTALL_ACTION",
               "plg_system_example",
                1,
               "action", 
               "site://plugins/system/example/postinstall/actions.php",
               "example_postinstall_action", 
               "site://plugins/system/example/postinstall/actions.php", 
               "example_postinstall_condition", 
               "3.2.0", 
               1)';
     
     $db->setQuery($query);
     $db->execute();
  }
 /*
  * $parent is the class calling this method
  * uninstall runs before any other action is taken (file removal or database processing).
  */
 function uninstall( $parent ) {               
  $db = JFactory::getDbo();
  $query = 'DELETE FROM '.$db->quoteName('#__postinstall_messages'). 
           ' WHERE '. $db->quoteName('language_extension').' = '.$db->quote('plg_system_example');
  $db->setQuery($query);
  $db->execute();
 }      
}        

If you want to deepen the topics covered here please read:

Read 265558 times
Tagged under Developers, English