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.


PayPal

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.

Features

  • 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.

Installation

  • 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.

Properties

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.

Property Effect Default
&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

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

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