EmailResource 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 $10.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

Overview

The EmailResource plugin for MODX Revolution will format and email any resource on your site. It will convert your CSS code to inline styles in the email so that the email will have HTML formatting. The CSS code can be taken from multiple CSS files, resources, or chunks. As of EmailResource version 1.1.2, you can send the email to all members of selected User Groups and you can use tags to send the email to selected members of each User Group.

The package works in a kind of an odd way. It emails the resource when you preview it from the MODX manager. To make that happen, you need to set values for some of the template variables attached to the resource (listed below). You may also want to set the properties of the plugin to the values you want in your email header.

This extra would not exist without the generous support provided by WorkDay Media.

Installing EmailResource for MODx Revolution

Go to System | Package Management on the main menu in the MODx Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put EmailResource in the search box and press Enter. Click on the "Download" button, and when the download has finished," click on the "Return to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to EmailResource in the grid. The EmailResource plugin should now be installed.

Usage

The template variables used to control EmailResource will appear on the EmailResource section of the Template Variables tab when you edit a resource. If you don't see them, it means that you haven't attached the EmailResource TVs to the template used by the resource.

If the "Preview Email" TV is set to "Yes", you will see the email that will be sent instead of the regular resource when you preview it.

If the "Send Test Email" TV is set to "Yes", the email version of the resource will be sent to the address specified in the "Email Address For Test" TV.

If the "Bulk Email on Preview" TV is set to "Yes", the resource will be emailed to all Users in the User Group or Groups specified in the "Groups" TV.

If the "Tags" TV contains a comma-separated list of tags, the resource will be only be emailed to Users in the User Group or Groups specified in the "Groups" TV who have any of the listed tags in the 'comment' field of their User Profile.

The TV values related to sending email are not set by default, because if they were, every time you previewed a resource, you'd be getting a copy of it in your email. You could also accidentally send multiple copies of the same email to Users. To prevent this, the "Send Test Email" and "Bulk Email on Preview" TVs are turned off (set to "No") for a resource as soon as it is emailed, so you have to turn them on and save the resource each time you want to actually send the email. Don't forget to save the resource before viewing it if you want to email.

To review, the plugin is controlled by a set of Template Variables that will appear on the Template Variable tab when editing any resource using a template to which the TVs are attached. Just edit the resource, set the TVs, save the resource, and preview it. All generic TVs to be used across various pages are set to @INHERIT, so if you set them in a parent container, all children will inherit the parent's values for the TVs.

Because the plugin is attached to the OnWebPagePrerender event and only acts when a page is previewed from the Manager, it has no effect for visitors to the front end of the web site. To users in the front end, the resource will appear as it would without the plugin installed. For increased security, the plugin will not execute at all unless you are logged in to the Manager.

Important! In order for EmailResource to operate on the current version of the TVs, you must *Save* the resource before previewing it. Always save the resource before any preview that will send email.

Sending Bulk Email to Subscribers

As of EmailResource version 1.1.2, you can email a resource to all members of specified User Groups. Put a comma-separated list of User Groups in the Groups TV and set "Bulk Email on Preview" to "Yes". If you have tags set up (see below), you can also fill in the Tags box. When you preview the resource by clicking on the "View" button at the upper right, the emails will be sent. Be sure to *save* the resource before previewing or no emails will be sent.

When you send bulk emails, EmailResource will create a log file for each send in the core/components/emailresource/logs directory. The filename will be based on the resource's alias and the date of the send.

Tag-based Sending

You can place a comma-separated list of tags in the 'comment' field of the User Profile for each User. If there are tags present in that field and you specify tags in the Tags TV, only Users with corresponding tags will receive the email. You must still specify the User Groups to send to in the "Groups" TV.

The Subscribe package will allow Users to register on the site and select tags you define. The tags will be placed in the 'comment' field of the User's Profile for use by EmailResource.

CSS files

In order for EmailResources to find your CSS files, they either have to be placed in chunks or resources, or all exist in the same directory (defined in the CssBasePath TV). If your CSS files specify background images, be sure that the url specified in the CSS file contains a full, absolute URL to each image.

EmailResource Template Variables

Template VariableDescriptionDefault
Create Inline CSS Convert CSS to inline styles in email version of resource. Yes
Preview Email Show a preview of the email rather than the original resource when previewing from the Manager. No
Send Test Email Send an email version of the resource to the address specified in the Email Address for Test TV. No
Email Address For Test The email address to send the test email to. emailsender System Setting
CssMode Specifies where the CSS is stored (files, resources, or chunks. FILE
CssFiles Comma-separated list specifying the files, resources, or chunks to use for the CSS styling in the email.  
CssBasePath Base path to the CSS files (ignored if the mode is RESOURCE or CHUNK) — should end with a slash (no spaces in the path). {modx_base_path} assets/components/ emailresource/css/
Bulk Email on Preview Send the email version of the resource to a list of subscribers (not implemented). No
Groups Comma-separated list of User Groups to send to.  
Tags Comma-separated list of tags to select Users by. (A comma-separated list of tags goes in the comment field of the User Profile.)  
Batch Size Number of emails to send at one time. 50
Batch Delay Delay in seconds between batches. 1
Item Delay Delay in seconds between emails. .51

EmailResource Plugin Properties

These properties set the various values for the email header. The "To" address for the test email is set in the Email Address For Test template variable listed above. The other values are set on the properties tab of the plugin itself.

The properties are optional and many of the default values may work for you. For those that don't, you should create a property set called "MyEmailResourcePropertySet" on the properties tab of the plugin so that your values are not overwritten when you upgrade the EmailResource package. After creating the property set, make sure you are editing it rather than the default properties (it's name will show in the drop-down box at the upper-left of the grid). Just double-click on the values you want to change and enter the new value. Don't forget to save the property set, using the "Save Property Set" button when you're done.

Whenever you want to edit the properties, make sure that the name is showing there so that you are not changing the default properties. Any values of the default properties will be overwritten when you upgrade the EmailResource package.

Be sure to attach your property set to the plugin by clicking on the "System Events" tab. Scroll down to the end where the OnWebPagePrerender event is checked. Double-click on the Property Set column and select "MyEmailResourcePropertySet." Then, save the plugin. It will then use your property set for the email setting values.

PropertyDescriptionDefault
mail_from (optional) MAIL_FROM setting for email. emailsender System Setting
mail_from_name (optional) MAIL_FROM_NAME setting for email. site_name System Setting
email_sender (optional) EMAIL_SENDER setting for email. emailsender System Setting
mail_reply_to (optional) REPLY_TO setting for email. emailsender System Setting
mail_subject (optional) MAIL_SUBJECT setting for email. Resource longtitle, or pagetitle if longtitle is empty
template_list (optional but highly recommended) Comma-separated list of Template IDs. List all templates used by resources that might be emailed. This will speed up the site by preventing the plugin from running for pages that will not be emailed. Use no spaces in the list. Remember to update this value if you create a new template for resources that will be emailed.  

A Final Note

You might not want to send a complete resource to Users. You might want, for example, want to send a short message, a note about an updated page, or a link to a new page or section. Remember that EmailResource can send *any* resource to your Users. You can easily create a new resource with a minimal or empty template, write a short note in the Resource Content field, and send it off to the Users. That note can be as short or ad long as you want and can contain links. Be sure to attach all the EmailResource TVs to any template used and to update the template_listproperty of the EmailResource plugin (if you're using it). As always, remember to save the resource before viewing it.

 

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