How to develop JMailAlerts Plugin for any component?

Note: This Blog is targeted towards Developers!

We will be going through a detailed step by step process of writing a JMailAlerts Plugin.

Extending JMailAlerts needs you to create special plugins of the type 'emailalerts'

Before we Proceed:

1. Replace your new plugin name “myplugin”

2. The code required adding a custom xml parameter is skipped

A. File Structure

jma_my_plugin(folder)

1. jma_myplugin.xml(file)

2. jma_myplugin.php(file)

3. jma_myplugin(folder)

a. tmpl(folder)

i)  jma_myplugin.php(file)

ii) jma_myplugin.css(file)

b.form(folder)

i) form_jma_myplugin.xml(file)

4. language(folder)

a. en-GB(folder)

i)  en-GB.plg_emailalerts_jma_myplugin.ini(file)

ii) en-GB.plg_emailalerts_jma_myplugin.sys.ini(file)

B. File Naming convention

• The Plugin prefix 'jma_' is reserved for plugins developed by us i.e. Techjoomla.com. Plugins developed by 3PD's should use the prefix 'jmac_'

• Make sure the plugin name indicates its purpose.

• In this tutorial, we shall be talking about the plugin "Latest Events - Eventlist for JMailAlerts".Its named as "jma_myplugin" .

C. Code for all files needed is given below

Go on creating corresponding files with sample code given below

jma_myplugin.xml

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="emailalerts" method="upgrade">
	<name>plg_emailalerts_jma_myplugin</name>
	<author>TechJoomla</author>
	<authorEmail>[email protected]</authorEmail>
	<authorUrl>www.techjoomla.com</authorUrl>
	<copyright>Copyright(C)2009-15 TechJoomla</copyright>
	<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
	<creationDate>26th Oct 2015</creationDate>
	<version>2.5.5</version>
	<description>My Plugin Description</description>
	<files>
		<filename plugin="jma_myplugin">jma_myplugin.php</filename>
		<folder>jma_myplugin</folder>
		<filename>index.html</filename>
	</files>
	<languages folder="language/en-GB">
		<language tag="en-GB">en-GB.plg_emailalerts_jma_myplugin.ini</language>
		<language tag="en-GB">en-GB.plg_emailalerts_jma_myplugin.sys.ini</language>
	</languages>
	<config>
		<fields name="params" addfieldpath="/plugins/emailalerts/jma_myplugin/jma_myplugin/fields">
			<fieldset name="basic">
				<field name="plugintitle" type="text" default="PLG_JMA_MYPLUGIN_TRANSLATABLE_PLUGIN_TITLE" label="PLG_JMA_MYPLUGIN_PLUGIN_TITLE" description="PLG_JMA_MYPLUGIN_DESC_PLUGIN_TITLE" />
				<field name="category" type="jmacategoriesmtpluginadmin" default="1" label="PLG_JMA_MUPLUGIN_ALLOWED_CATEGORY" element="jma_myplugin" multiple="multiple" description="PLG_JMA_MYPLUGIN_DESC_ALLOWED_CATEGORY" key_field='id' value_field='title' extension="com_content" published="1" />
			</fieldset>
			<fieldset name="legacy" label="PLG_JMA_MYPLUGIN_USER_PARAMS" description="PLG_JMA_MYPLUGIN_USER_PARAMS_DESC" addfieldpath="/plugins/emailalerts/jma_myplugin/jma_myplugin/fields">
				<field name="catid" type="jmamyplugincategories" default="1" label="PLG_JMA_MYPLUGIN_CATEGORY" element="jma_myplugin" multiple="multiple" description="PLG_JMA_MYPLUGIN_DESC_CATEGORY" key_field='id' value_field='title' />
				<field name="count" type="text" default="5" label="PLG_JMA_MYPLUGIN_COUNT" class="required validate-numeric input" description="PLG_JMA_MYPLUGIN_DESC_COUNT" />
			</fieldset>
		</fields>
	</config>
</extension> 

jma_myplugin.php

<?php

/**
 * @version     SVN: <svn_id>
 * @package     JMailAlerts
 * @subpackage  jma_myplugin
 * @author      Techjoomla <[email protected]>
 * @copyright   Copyright (c) 2009-2015 TechJoomla. All rights reserved.
 * @license     GNU General Public License version 2 or later.
 */

// No direct access.
defined('_JEXEC') or die();

jimport('joomla.plugin.plugin');

// Load language file for plugin frontend
$lang = JFactory::getLanguage();
$lang->load('plg_emailalerts_jma_myplugin', JPATH_ADMINISTRATOR);

// Include plugin helper file.
$jma_helper = JPATH_SITE . '/components/com_jmailalerts/helpers/plugins.php';

if (JFile::exists($jma_helper))
{
	include_once $jma_helper;
}
// This is needed when JMA integration plugin is used on sites where JMA is not installed.
else
{
	$jma_integration_helper = JPATH_SITE . '/plugins/system/plg_sys_jma_integration/plg_sys_jma_integration/plugins.php';

	if (JFile::exists($jma_integration_helper))
	{
		include_once $jma_integration_helper;
	}
}

/**
 * Latest alerts plugin for JMailAlerts Component.
 *
 * @package     JMailAlerts
 * @subpackage  Emailalerts.myalerts
 * @since       2.5.1
 */
class PlgEmailalertsjma_myplugin extends JPlugin
{
	/**
	 * Constructor
	 *
	 * @param   object  &$subject  The object to observe
	 * @param   array   $config    An array that holds the plugin configuration
	 *
	 * @since   2.5
	 */
	public function __construct(&$subject, $config)
	{
		parent::__construct($subject, $config);
		$this->loadLanguage();

		if ($this->params === false)
		{
			$jPlugin = JPluginHelper::getPlugin('emailalerts', 'jma_myplugin');
			$this->params = new JParameter($jPlugin->params);
		}
	}

	/**
	 * Method to get the HTML and CSS output for this plugin.
	 *
	 * @param   string   $id                 The userid or email of the user to whom email is being sent.
	 * @param   string   $date               The date when last email alert of which this plugins is part of was sent to this user.
	 * @param   array    $userparam          The final array of plugin parameters which are derived
	 * in the order of increasing priority of - plugin params, user params, data tags.
	 * @param   integer  $fetch_only_latest  Parameter that decides if only the latest content is to be sent out in the email.
	 *
	 * @return  array
	 *
	 * @since   2.5.1
	 */
	public function onEmail_jma_myplugin($id, $date, $userparam, $fetch_only_latest)
	{
		$areturn = array();
		$areturn[0] = $this->_name;
		$areturn[1] = '';
		$areturn[2] = '';

		// If no userid or no guest user, return blank array for html and css.
		if ($id === null)
		{
			return $areturn;
		}
		
		// Call to function which fetched the record for sending alerts 
		$list = $this->getList($id, $date, $userparam, $fetch_only_latest);

		$areturn[0] = $this->_name;

		if (!empty($list))
		{
			// Get all plugin parameters in the variable, this will be passed to plugin helper function.
			$plugin_params = $this->params;

			// Create object for helper class.
			$helper = new pluginHelper;

			// Call helper function to get plugin layout.
			$ht         = $helper->getLayout($this->_name, $list, $plugin_params);
			$areturn[1] = $ht;

			// Call helper function to get plugin CSS layout path
			$cssfile    = $helper->getCSSLayoutPath($this->_name, $plugin_params);
			$cssdata    = file_get_contents($cssfile);
			$areturn[2] = $cssdata;
		}

		return $areturn;
	}

//The above function will provide “Email template”(Layout) and CSS required to generate the preview of mail to be sent from the plugin configuration.

	/**
	 * Method to get the list of alert items based on user preferences.
	 *
	 * @param   string   $id                 The userid or email of the user to whom email is being sent.
	 * @param   string   $last_alert_date    The date when last email alert of which this plugins is part of was sent to this user.
	 * @param   array    $userparam          The final array of plugin parameters which are derieved
	 * in the order of increasing priority of - plugin params, user params, data tags.
	 * @param   integer  $fetch_only_latest  Parameter that decides if only the latest content is to be sent out in the email.
	 *
	 * @return  array
	 *
	 * @since   2.5.1
	 */
	private function getList($id, $last_alert_date, $userparam, $fetch_only_latest)
	{
		//Your code to get list of items of alert 
	}

// In above function you can write the code to get the alert items from the database e.g If you are developing a plugin for jomsocial latest photos then you can write the code to get the latest photos from the database and return the data to function “onEmail_jma_myplugin()”, which will apply the layout styling to the data and will generate the preview.
}

jma_myplugin/tmpl/jma_myplugin.php

<?php

/**
 * @version     SVN: <svn_id>
 * @package     JMailAlerts
 * @subpackage  jma_myplugin
 * @author      Techjoomla <[email protected]>
 * @copyright   Copyright (c) 2009-2015 TechJoomla. All rights reserved.
 * @license     GNU General Public License version 2 or later.
 */

// No direct access.
defined('_JEXEC') or die();
?>

<h2 class="subTitle">
	<?php echo JText::_($plugin_params->get('plugintitle')); ?>
</h2>

// CODE TO SHOW ALERT ITEMS LIST

 jma_myplugin/tmpl/jma_myplugin.css

/**
 * @version     SVN: <svn_id>
 * @package     JMailAlerts
 * @subpackage  jma_myplugin
 * @author      Techjoomla <[email protected]>
 * @copyright   Copyright (c) 2009-2015 TechJoomla. All rights reserved.
 * @license     GNU General Public License version 2 or later.
 */

.jma_myplugin
{
font-family: Helvetica;
text-align:left;
border-spacing: 7px;
margin-top: 5px;
width: 100%;
min-height: 82px;
font-size:12px;
padding-bottom:0;
padding-top:5px;
vertical-align:top;
}
.jma_myplugin_th
{
font-size:12px;
font-weight:bold;
}

.jma_myplugin_td_60
{
width:60%;
}

.jma_myplugin_td_20
{
width:20%;
font-style:italic;
font-size:10px;
}

.jma_justify{
text-align:justify;
}

I hope these guidelines have brought you much closer in terms of understanding on how you can reach out to your site audience for promoting usage as well as the popularity of your site using a simple and flexible extension J!Mail alerts.

Feel free to add a comment if you’ve any queries. Have fun developing “J!MailAlerts” plugin for your extension!