Bob's Guides

EmailResource Plugin Tutorial

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-premium extras with a clear conscience.

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.

Fully Updated for MODX 3

Limitations

Not all web pages will look good when emailed. For example, .svg images generally won't be displayed, and interactive JavaScript usually won't work. There's a good discussion of what will and won't work here.

Pages that use the MODX base template in MODX 2 will look terrible when emailed, as do those that use the Bob's Guides default template. It may take some trial and error to develop templates and pages that look good when emailed. In both cases, copying the HTML from "view original" in Gmail, pasting it into a file, and viewing the file produces a view exactly like the original page. So the problem is definitely in the mail client.

Keep in mind that each mail client has its own quirks and limitations, and that the result will also depend on the size of the user's screen.

The limitations of various mail clients is another good reason to use Notify, which sends a link to the page on your website, instead of an email version of the page. When the user visits the link, the page will look just as it always does.

How EmailResource Works

The package works in 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 Extras -> Installer on the MODX Top menu to open Package Manager. Click on the "Download Extras" button. That will take you to the Revolution Repository. 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.

If a page you want to email uses a different template than the site's default template, you'll need to edit that template. On the Template Variables tab, check all the EmailResource TVs and save the template. That will connect all the TVs, so they'll show up when you edit the resource.

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 (see the paragraph above).

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.

Some of 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 automatically placed in the 'comment' field of the User's Profile (or in an extended field of the User Profile) for use by EmailResource. As of Subscribe Version 1.2.0, users can manage their tags on a "Manage Preferences" page.

Using Subscribe is strongly recommended, but if you choose not to install it, you can still put the users' preferences (tags) in an extended field of the User Profile (say, because you need the comment field for something else). Just create two new System Settings:

    sbs_use_comment_field
    sbs_extended_field

Set the first one to No and the second one to the name of the extended field you would like to use (the default is interests). If Subscribe is not installed, you will need to create the extended field for each user and list the tags in it manually. Be careful that they are spelled correctly.

User Group Management

You can create and assign the User Groups manually, but as with tags, the Subscribe extra will assign the User Groups and roles automatically and will (optionally) let users manage their own User Group memberships. See the Subscribe documentation for more information on how to use this feature.

Unsubscribe Link

Important: In order to use this feature, you must have Subscribe Version 1.2.0 or later installed.

If Subscribe is installed, EmailResource will include an unsubscribe link at the bottom of every email when you send bulk email. This is required for all bulk email by the USA CAN-spam act, so it is *very* strongly recommended. If Subscribe Version 1.2.0 or later is installed, this will be done automatically. The link is injected just above the closing body tag, or appended to the end of the message if there is no body tag.

The unsubscribe message comes from the Tpl chunk named in the unsubscribe_tpl property. The default chunk is called unsubscribeTpl, but if you need to modify it, you should duplicate it (call it myunsubscribeTpl and set that name in the property, so it won't be overwritten if you upgrade or reinstall EmailResource. Be sure to have the [[+unsubscribeUrl]]> tag in your chunk inside an href tag. EmailResource will replace the tag with a secure URL that is different for each user.

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

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.

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 template, write a short note in the Resource Content field, and send it off to the Users. That note can be as short or as 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_list property of the EmailResource plugin (if you're using it). As always, remember to save the resource before viewing it.

Copyright © 2011-2024
Bob Ray