ActivationEmail Plugin Tutorial
I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.
This plugin for MODX Revolution sends an email message to users when they are activated manually in the MODX Manager and (optionally) a second message to deactivated users.
- Emails to both activated and deactivated users can be turned on and off with properties
- Both messages are in Tpl chunks that can be modified to meet your needs
- The messages can be personalized to include the username or full name, the site name, and a URL link
- The Site Name and an included URL link can be customized with properties.
Report bugs and suggestions here.
Ask any questions about using this plugin here.
- Go to System | Package Management
- Click on the "Download Extras" button
- Type "ActivationEmail" in the search box and press Enter.
- Click on the download button next to the Activation Email package
- Wait until the download button changes to "downloaded"
- Click on the "Finish", button
- You should see the ActivationEmail package in the grid
- Click on the "install" button next to the package
- Click on "OK" to close the console
- Check to make sure that the plugin and the two chunks were installed
Checking the Install
The first thing to do is to make sure the plugin is installed properly. Create a new user with your email address. Activate and deactivate the user a few times and see if you get an email message. If you don't, make sure your email system is working by downloading and installing the QuickEmail snippet.
The deactivation email is off by default so you won't get it unless you change the sendOnDeactivation property of the plugin to True. If you won't be using that feature, don't bother.
Once the email is arriving. The odds are that you will want to modify one or both of the Tpl chunks containing the message forms (if not, you're done -- sit back and relax). In order to keep the Tpl chunks from being overwritten by upgrades, duplicate and rename them.
Duplicating and Renaming the Chunks
- On the left side of the screen, click on the Elements tab
- Right-click on the ActivationEmailTpl chunk in the chunk section of the Elements tree and select "Duplicate Chunk"
- Call the new chunk "MyActivationEmailTpl"
- If you will be sending a deactivation email, do the same thing for the DeactivationEmailTpl
- Don't change the content of the new chunk(s) yet
Creating the Property Set
Like the Tpl chunk(s), you don't want the properties to be overwritten during an upgrade, so you should create a property set for your own settings.
- Edit the plugin and click on the "Properties" tab
- Click on the "Add Property Set" button
- Check the "Crete New Property Set" checkbox
- Use the name MyActivationEmailProperties; add a description if you like
- Highlight the name and save it to the clipboard
- Click on the "Save" button
- In the "Value" column, double-click on ActivationEmailTpl (or right-click and update it)
- Paste in the name from the clipboard (or type in MyActivationEmailTpl)
- Do the same for the DeactivationEmailTpl if you'll be using that
- Important: Click on the "Save Property Set" button
Connecting the Property Set
Now we need to tell MODX to use our own property set with the plugin
- Still editing the plugin, click on the System Events tab
- Scroll down to the OnUserBeforeSave event (note: *Not* OnBeforeUserFormSave)
- You may have to look on multiple pages to find it
- Make sure it has the checkbox checked
- Double-click in the Property Set column (column 4)
- Using the drop-down list, select the MyActivationEmailProperties set
- Important: Click on the "Save" button to save the plugin
Retesting and Configuring
Activate and deactivate your user a few times. Make sure the emails are still arriving and that the messages are correct.
Edit the plugin and click on the "Properties" tab. Make sure you are editing your own property set, not the default properties, by selecting MyActivationEmailProperties in the drop-down list at the upper left of the grid. You can see what each property does by clicking on the little plus sign next to it in the grid. Set the properties to meet your needs. Be sure not to edit anything except the "Value" column.
When you're finished click on the "Save Property Set" button. Notice that any properties you change show up in green once you save the set. That shows that they have different values than the default properties
You may have to clear the site cache to before your changes take effect.
Customizing the Tpl Chunks
The two Tpl chunks can be completely rewritten to meet your needs. Be sure to edit the two duplicate Tpl chunks, not the ones that were installed with the Activation Email package. Be sure to include the [[+username]] placeholder so the user will be addressed by name.
The other placeholders are optional. All will be set to appropriate system settings, but you can set their values in the property set you created. You can also modify them or remove them if you wish. Since you've renamed the Tpl chunks, your changes will survive any upgrades.
Note that the [[+username]] placeholder should not change, even if you use the &useFullname property. You may also use the optional [[+fromName]] placeholder if you have set that property.
The following properties control the behavior of the ActivationEmail plugin. If you need to alter any of them be sure to create a property set and specify it on the System Events tab as described above. When changing the property values, always be sure that you're modifying your property set and not the default properties. The default properties are locked to remind you to do so.
|&sendOnActivation||Send activation email||`1`|
|&sendOnDeactivation||Send deactivation email||`0`|
|&activationEmailTpl||Tpl chunk for activation email||`ActivationEmailTpl`|
|&deactivationEmailTpl||Tpl chunk for deactivation email||`DeactivationEmailTpl`|
|&activationURL||URL to send activated users to||site_url System Setting|
|&deactivationURL||URL to send deactivated users to||site_url System Setting|
|&sitename||site name to use in message||site_name System Setting|
|&useFullname||Use full name in msg instead of username||`0`|
|&activeSubject||Subject for activation email messages||Registration Approved|
|&activeSender||Email Sender for activation email messages||emailsender System Setting|
|&activeFrom||Email From address for activation email messages||emailsender System Setting|
|&activeFromName||Email From Name for activation email messages||site_name System Setting|
|&activeReplyTo||Reply To address for activation email messages||emailsender System Setting|
|&deActiveSubject||Subject for deactivation email messages||Status Changed to Inactive|
|&deActiveSender||Email Sender for deactivation email messages||emailsender System Setting|
|&deActiveFrom||Email From address for deactivation email messages||emailsender System Setting|
|&deActiveFromName||Email From Name for deactivation email messages||site_name System Setting|
|&deActiveReplyTo||Reply To address for deactivation email messages||emailsender System Setting|
If you have the book and would like to download the code, you can find it here.
If you have the book and would like to see the updates and corrections page, you can find it here.
MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:
- Installing MODX
- How MODX Works
- Working with MODX resources and Elements
- Using Git with MODX
- Using common MODX add-on components like SPForm, Login, getResources, and FormIt
- MODX security Permissions
- Customizing the MODX Manager
- Using Form Customization
- Creating Transport Packages
- MODX and xPDO object methods
- MODX System Events
- Using PHP with MODX
Go here for more information about the book.
Thank you for visiting BobsGuides.com
— Bob Ray