Developer Documentation

Dear developer,

Joomla! is not only the best CMS because of its core team; Joomla! is empowered by all the third-party extensions, professional or not, which add so many functionalities to any website.
Based on this success, we decided to open AcyMailing to any addition using a the powerful Joomla Plugin system.

• Introduction
• Create a newsletter tag
  • acymailing_getPluginType()
  • acymailing_replacetags(&$email,$send=true)
  • acymailing_replaceusertags(&$email,&$user,$send=true)
  • acymailing_generateautonews(&$email)
• Create a filter
• Create an action
• Other plugin triggers
  • When the user is created
  • When the user is modified
  • When the user subscribes to a list
  • When the user unsubscribes from a list
  • When a Newsletter is added to the queue
  • Cron trigger
• API
  • Subscription via url
  • Get the AcyMailing mailing lists
  • Insert a user in AcyMailing
  • Subscribe or remove a user from one or several lists
  • Create a Newsletter
  • Insert an e-mail in the queue
  • Create a list
  • Delete a list

Introduction

AcyMailing uses the Joomla Plugin system to handle its tag system.

So the first thing you have to do is to create a standard Joomla plugin with the group "acymailing" and install it on Joomla.

Create a newsletter tag

We recommend you to download and install our fully commented example plugin :

You can then modify the installed file plugins/acymailing/example.php and plugins/acymailing/example.xml to meet your needs.

• acymailing_getPluginType()
• your_own_function_name()
• acymailing_replacetags(&$email,$send=true)
• acymailing_replaceusertags(&$email,&$user,$send=true)
• acymailing_generateautonews(&$email)

Functions are called if they exist, you don't have to define them all.
If you don't want to display interface but simply want to modify the content, then don't add the acymailing_getPluginType() function.

acymailing_getPluginType()

This function enables AcyMailing to display your tag on our tag system (on the interface after you click on the button "Tag").
If you don't want your tag to have an user interface simply don't add this function (for example, the AcyMailing statistics plugin does not need any user interface so this function is not included in it).

If you want to have a tag interface, you have to return us an object with :

• name : Name of your plugin (this name is only useful on the user interface, it can be anything you want)
• function : Name of the function AcyMailing should trigger on the user interface.
  On the tag interface, if the user clicks on your tag name, AcyMailing has to trigger your plugin and your plugin only.
  For that you have to tell us a name of function. Please make sure this name is unique!
• help : This argument is only useful if you plan to send us a documentation about how the user can use your plugin.
  If you specify the help attribute, AcyMailing will display an help button on your tag interface to give the user the possibility to read the documentation.

Show / hide php code

function acymailing_getPluginType(){
$onePlugin = new stdClass();
$onePlugin->name = 'Tab title for the tag interface';
$onePlugin->function = 'acymailingMyUniqueNameFunction';
$onePlugin->help = 'plugin-mypluginname';
return $onePlugin;
 
}

Your own function name

Using the function acymailing_getPluginType, you returned to AcyMailing a name and an unique function name to call.
You should create this function on your own plugin which will be triggered if the user clicks on your tag name on our interface.
For the time plugin, this function is called acymailingtagtime_show but it could be anything else, it just has to be unique.

On the following screenshot, we called it acymailingMyUniqueNameFunction.

Show / hide php code

    //This is the function name I specified in the previous $onePlugin->function argument.
 //This function will be triggered if my tab is selected on the interface
 //If you don't want an interface on the tag system, just remove this function
 function acymailingMyUniqueNameFunction(){
 
 //In this file you can use the javascript function setTag('your tag'); and insertTag(); which will set the tag and insert it in your Newsletter.
 //Please only use insertTag() if you want the tag to be direclty inserted but if you use only setTag('your tag') then the user will be able to see it and click on the insert button.
 //Your content will be inserted inside a form, you can add a submit button or whatever you want, it will do the job (if you want to add a search option).
 echo '<div onclick="setTag(\'{myowntag}\');insertTag();">Click here to insert my tag</div>';
 
 }

You don't have to return anything.
This function is called so that you can display anything you want on your tag interface.
For example, on the AcyMailing time plugin, we give to the user the choice to insert different kind of time.

AcyMailing makes your life easier and handles the tag insertion.
You can use two javascript function to do that:

• setTag(yourtag) : this function will set the tag in AcyMailing. You have first to call this function if you want the tag to be inserted in the Newsletter.
  If you call this function, a button "add the tag" will be automatically displayed on your interface and the user will be able to click on it to insert your tag.
• insertTag() : you may want to add this function after calling the setTag function to directly include your tag in the Newsletter.

Please don't add a form on your tag interface, AcyMailing already did it so you can directly add some submit button if you want to give the possibility to the user to search or sort your columns.

acymailing_replacetags(&$email,$send=true)

This function enables you to replace your global tags.

What we call global tags is a tag which does not depend on the user information.
So this tag is the same for all users.

AcyMailing will trigger this function during the preview and only one time during the send process.

There are two parameters for this function:

• $email which is an object with the:
  • body : body of the Newsletter in HTML
  • altbody : body of the Newsletter in plain text version
  • subject : subject of the Newsletter
• $send indicates if the Newsletter will be sent (set to true) or displayed on the browser (set to false)

You don't have to return anything, simply directly modify the Newsletter the way you want.

Show / hide php code

function acymailing_replacetags(&$email,$send=true){
$email->body = $email->body.' I just added this text to the html version';
$email->altbody = $email->altbody.' and this text to the text version';
$email->subject = 'Hello, the subject is : '.$email->subject;
if(!$send){
$email->body .= 'This Newsletter is displayed on the browser';
}
}
 

acymailing_replaceusertags(&$email,&$user,$send=true)

This function enables you to replace your personal tags.

AcyMailing will trigger this function each time an e-mail is sent or displayed (on the archive version for example) for each user.

The last parameter $send enables you to know if the Newsletter will be sent (set to true) or displayed on the browser (set to false)

Show / hide php code

function acymailing_replaceusertags(&$email,&$user,$send = true){
$email->body .= '<br/>this e-mail is for '.$user->name;
$email->body .= ' (ID: '.$user->subid.'; email:'.$user->email.')';
if($send){
$email->subject .= ' this message is sent';
}
}
 

acymailing_generateautonews(&$email)

This function enables you to accept or block a Newsletter generation from our auto-Newsletters feature.
For example, this function is used in our Joomla content plugin to check if there are new articles created since the last generated date. If not, we will stop the Newsletter generation.

You can use the email object and you can access the latest generated date with $email->params['lastgenerateddate'] (this value is a timestamp but won't exist if you trigger this function from somewhere else)

You should return an object with:

• status : TRUE / FALSE
  True: your plugin allows the Newsletter to be generated
  False: your plugin will block the Newsletter generation
• message : In case of you block the Newsletter generation, you can specify a message which will be displayed on the interface and recorded in the log.

 

Show / hide php code

function acymailing_generateautonews(&$email){
 
$return = new stdClass();
$return->status = true;
$return->message = '';
 
if(...){
//If don't want the Newsletter to be generated (because there is no new element for example)
$return->status = false;
$return->message = 'Newsletter blocked because...';
}
 
//You need to return an object with the status and message (reason) in case of the status is set to false.
return $return;
 
}

Create a filter

You can add your own filters to our filter interface.

onAcyDisplayFilters(&$type)

This function enables you to add a new filter type on our filter interface.

You should return a string which will be displayed on the filtering interface and add a new type in $type variable.

Then if your filter is selected, the function onAcyProcessFilter_YOURTYPE(&$query,$filter,$num) will be triggered.

Please have a look at our existing plugins (tagsubscription or tagsubscriber to have an example).

Create an action

You can add your own actions to our filter interface.

onAcyDisplayActions(&$type)

This function enables you to add a new action type on our filter interface.

You should return a string which will be displayed on the filtering interface and add a new type in $type variable.

Then if your filter is selected, the function onAcyProcessAction_YOURTYPE(&$query,$action,$num) will be triggered.

Please have a look at our existing plugins (tagsubscription or tagsubscriber to have an example).

Other plugin triggers

When the user is created

When the user is created, the function onAcyUserCreate($subscriber) is triggered.

When the user is modified

When the user is modified, the function onAcyUserModify($subscriber) is triggered.

When the user subscribes to a list

When the user subscribes to a list, the function onAcySubscribe($subid,$listids) is triggered.

When the user unsubscribes from a list

When the user unsubscribes from a list, the function onAcyUnsubscribe($subid,$listids) is triggered.

When a Newsletter is added to the queue

When the Newsletter is added to the queue, just before the send process starts, the function onAcySendNewsletter($mailid) is triggered

Cron trigger

Using our commercial version (if you created your cron task), AcyMailing will trigger the function onAcyCronTrigger every day automatically.

So you can create a Joomla plugin type AcyMailing with this function and it will be automatically triggered once a day (only once a day even if your cron has a 15 minutes frequency).

There is no argument for this function but you can return a string which will be automatically included in the cron report.

API

Get the AcyMailing mailing lists

Show / hide php code

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
$listClass = acymailing_get('class.list');
 
$allLists = $listClass->getLists();
 
//You can then do a foreach on this variable (which contains an array of objects) and use ->name

Insert a user in AcyMailing

Show / hide php code

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
$myUser = new stdClass();
 
$myUser->email = 'emailaddressoftheuser';
 
$myUser->name = 'myname'; //this information is optional
 
//You can add as many extra fields as you want if you already created them in AcyMailing
//$myUser->country = 'france';
//$myUser->phone = '064872754';
//...
 
$subscriberClass = acymailing_get('class.subscriber');
 
$subid = $subscriberClass->save($myUser); //this function will return you the ID of the user inserted in the AcyMailing table

Subscribe or remove a user from one or several lists

Show / hide php code

$subscribe = array(2,4,6); //Id of the lists you want the user to be subscribed to (can be empty)
 $remove = array(1,3); //Id of the lists you want the user to be removed from (can be empty)
 $memberid = '23'; //ID of the Joomla User or user e-mail (this code supposes that the user is already inserted in AcyMailing!)
 
 if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
 $userClass = acymailing_get('class.subscriber');
 
 $newSubscription = array();
 if(!empty($subscribe)){
 foreach($subscribe as $listId){
 $newList = array();
 $newList['status'] = 1;
 $newSubscription[$listId] = $newList;
 }
 }
 if(!empty($remove)){
 foreach($remove as $listId){
 $newList = array();
 $newList['status'] = 0;
 $newSubscription[$listId] = $newList;
 }
 }
 
 if(empty($newSubscription)) return; //there is nothing to do...
 
 $subid = $userClass->subid($memberid); //this function returns the ID of the user stored in the AcyMailing table from a Joomla User ID or an e-mail address
 if(empty($subid)) return false; //we didn't find the user in the AcyMailing tables
 
 $userClass->saveSubscription($subid,$newSubscription);

Create a Newsletter

Show / hide php code

 
 
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
//We create the Newsletter element that we will save in the database.
//You can use all fields from the database the same way we do it with subject and body.
 
$mail = new stdClass();
//Subject of your Newsletter
 $mail->subject = 'your subject...';
//Body of your Newsletter... the text version will be automatically generated from this html version.
 $mail->body = 'your body...';
//ID of the template attached to this Newsletter so the CSS defined in that AcyMailing template will be applied to your Newsletter.
$mail->tempid = 4;
 
$mailClass = acymailing_get('class.mail');
 
//the save function returns you the ID of the inserted Newsletter so you can then use it to insert e-mails in the queue.
$mailid = $mailClass->save($mail);

Insert an e-mail in the queue

Show / hide php code

//The purpose of this code is to let AcyMailing send an e-mail to a specific user at a specific time.
//You just have to add an entry in the queue and AcyMailing will take care of the rest.
 
$memberid = '23'; //ID of the Joomla User or user e-mail (this code supposes that the user is already inserted in AcyMailing!)
 
$mailid = '45'; //ID of the Newsletter you want to add in the queue
 
$senddate = time(); //When do you want the e-mail to be sent to this user? you should specify a timestamp here (time() is the current time)
 
 
 
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
 
 
$userClass = acymailing_get('class.subscriber');
 
$subid = $userClass->subid($memberid); //this function returns the ID  of the user stored in the AcyMailing table from a Joomla User ID or an  e-mail address
 if(empty($subid)) return false; //we didn't find the user in the AcyMailing tables
 
$db= JFactory::getDBO();
 
$db->setQuery('INSERT IGNORE INTO #__acymailing_queue (`subid`,`mailid`,`senddate`,`priority`) VALUES ('.$db->Quote($subid).','.$db->Quote($mailid).','.$db->Quote($senddate).',1)');
 
$db->query();

Create a list

Show / hide php code

 
 
$newlist = new stdClass();
$newlist->name = 'Your list name';
$newlist->description = 'Your list description'; //this parameter is optional
 
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
$listClass = acymailing_get('class.list');
$listid = $listClass->save($newlist); //This function will create the list and return the ID of the created list
 

Delete a list

Show / hide php code

 
//This code will not only delete a list an all elements related to that list (it won't delete users or newsletters, but only the fact a Newsletter is attached to that list or a subscriber subscribed to that list)
 
 
 
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DS).DS.'components'.DS.'com_acymailing'.DS.'helpers'.DS.'helper.php')){
 echo 'This code can not work without the AcyMailing Component';
 return false;
 }
 
$listClass = acymailing_get('class.list');
$listClass->delete(LIST_ID); //You should replace LIST_ID by the ID of the list you want to delete