ActivationEmail Plugin Tutorial
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-premium 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.
1.2.0 Update Notes
The MODX event this plugin was connected to no longer exists. It hasn't worked for some time, but no one filed an issue. The upgrade changes the connection to two more reliable events. ActivationEmail now works in both MODX 2 and MODX 3. Two critical typos in the default message Tpl chunks have been fixed.
Important: If you have modified any of the properties of the snippet, make sure you have created a property set as described below, or your changes won't survive the upgrade. You may need to re-attach your property set to the plugin after the upgrade.
Due to a recently discovered bug in MODX, the properties cache is not cleared when you save the plugin, so if you decide to change any of the plugin properties now or in the future, be sure to clear the cache in the Manager so your changes will take effect.
Report bugs and suggestions here.
Ask any questions about using this plugin here.
- Go to Extras | Installer
- 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 finishes
- Click on the "Back to Package Manager", 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 Be sure the clear the cache in the Manager after making the change.
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 "Create 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 "OnUserActivate" 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
- Do the same for the "OnUserDeactivate" event.
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