AcyMailing 5 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.
Create a newsletter tag
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. 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.
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.
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.
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.
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)
acymailing_generateautonews(&$email)
This function enables you to accept or block a Newsletter generation from our Smart-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.
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).
Create a new custom field type
Please download this example plugin to create your own custom field type. This example plugin is fully self-documented.
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 is deleted
When the user is deleted, the function onAcyBeforeSubscriberDelete($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 after adding it to the queue), just before the send process starts, the function onAcySendNewsletter($mailid) is triggered
When a list is created
Just before a list is created, the function onAcyBeforeListCreate($list) is triggered
When a list is modified
Just before a list is modified, the function onAcyBeforeListModify($list) is triggered
When a list is deleted
Just before a list is deleted, the function onAcyBeforeListDelete($elements) is triggered $elements is an array of list IDs.
When the user clicks on a link
Just before the user is redirected to the final url, the function onAcyClickLink($subid,$mailid,$urlid) is triggered $subid is the ID of the user from the acymailing_subscriber table. $mailid is the ID of the Newsletter. $urlid is the ID of the clicked link.
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
Insert a user in AcyMailing
Get a user subscription
Subscribe or remove a user from one or several lists
Create a Newsletter
Insert an e-mail in the queue
Send a Newsletter to a single user
Sometimes you want to send a pre-saved Newsletter to a single user only... In that case you should not bother with the queue system and use this code (it will send the Newsletter ID 67 to the user "user@example.com"):
Create a list
Delete a list
How to load the Joomla API
If you want to use the Acymailing API without Joomla, you first need to include the Joomla API. Please add these lines first in your script and don't forget to replace "PATH_TO_YOUR_JOOMLA_SITE_ROOT_FOLDER" by the real value:
Last updated