Bob's Guides

Notify Snippet Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $20.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

Notify will let you send an email notification to Subscribers on your site, or to members of selected groups, (or to all active users) when a page is created or updated (or just when you feel like sending them a message). Rather than sending the whole page, Notify sends a message with a link to the new or updated page. Optionally, you can specify tags for the message and only subscribers with those tags set will receive the email. Notify works in conjunction with the Subscribe extra, which lets users register at your site and manage their preferences (tags), and user-group memberships if you choose to enable that.

(Jump to Properties Table.)

Notify will also send Tweets to Twitter and (optionally) post the Tweets to your Facebook page. There is an option to shorten any URLs present in any of the Notify Tpl chunks using several URL shortening services (TinyUrl, bit.ly, and is.gd) Other services present in earlier versions of Notify no longer exist.

Installing Notify for MODX Revolution

(Install Subscribe and Login before installing Notify.) To install Notify, go to Package Manager (Extras -> Installer) on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository. Put Notify in the search box and press Enter. Download Notify, then click on the button that takes you back to Package Management. Click on the "Install" button next to Notify in the grid. The Notify package should now be installed.

During the installation, the Notify TV will be connected to the site's default template. If you need to attach it to other templates, you'll have to connect it manually by editing the TV, checking the boxes on the "Template Access" tab, and clicking on the "Save" button.

If you want Notify to post to Twitter and/or Facebook, you'll need to set the four Twitter properties (see below).

Using Notify

Notify uses a front-end form to send notifications to subscribers, and Messages to Twitter and/or Facebook. When you click on the "Launch Notify" button of the Notify TV when editing a resource, (having set the desired radio-button option) you are forwarded to the Notify resource, where the Notify snippet pre-fills and displays the Notify form. Note that sending updates with Notify is always strictly manual. No updates to subscribers, Twitter, or Facebook are ever sent automatically. For some people, receiving an update every time you save a page can get pretty annoying, so Notify only sends updates when you tell it to by submitting the form with one of the update options checked. Once you have it set up, this only takes a few clicks of the mouse.

To launch the Notify form:

1. Go to the Create/Edit Resource form for a document
2. Click on the "Template Variables" tab
3. Select the Notify area, if necessary
4. Select the type of update you want from the radio options
5. Click on the "Launch Notify" button

That will launch the Notify Form (see below for launching Notify from NewsPublisher or another snippet or plugin).

The Notify snippet pre-fills the Notify form. The values for the email, email subject, and Tweet come from the Notify Tpl chunks. The four radio buttons below the "Launch Notify" button set which chunks are used for the Email text and Tweet text. For both email and Twitter, there is a Tpl chunk for notifying users of new resources and one for announcing updates to existing resources. The two custom Tpls (one for the email and one for Twitter) can be used for anything you want. Finally, there is a blank option, which will display the form with the Email text and Tweet text fields empty. If you want to change any of the default Tpl chunks, be sure to duplicate them (adding the prefix "My"). Notify will look first for the Tpl chunks prefixed with 'My', then in the Tpl chunks specified in the snippet properties or in a property set.

You can change the text in any of the fields before submitting the form. If you change the text of the email, click on the "Submit" button without checking any of the "Send" checkboxes, you'll see a preview of the email in the Preview window.

You can't add MODX tags to the message. All MODX tags are processed as the Tpl chunk is retrieved, so by the time you're entering the message, it's too late. You can, however, add user field placeholders, in this form {{+fieldName}}. The username and all fields of the User Profile will be set as user placeholders. If you use the &useExtendedFields property, any extended fields will be set as well.

The various options are independent, so you can send a single email, send a message to subscribers, or send a Tweet without activating the other options. When you click on the "Single Email" checkbox, an input field will appear where you can enter either the email address or the username of a user on the site.

Notify pre-fills the email subject, email message, and Tweet fields for you, but you can put whatever you want into them. If you just want to email your subscribers to tell them what you had for breakfast, you can do that. The only page-specific information will be the URL (filled in by Notify) and any Resource Content tags that you include in the Tpl chunk (e.g. pagetitle, introtext, description , etc.). You're free to add, or delete any of them. In other words, you can use Notify to send any email message to your subscribers, optionally selected by Group(s) and/or Tag(s). Just remember that MODX placeholders are not available to you if you do this, though user placeholders are.

Notify will create a Property Set for you, called "NotifyProperties". Notify already specifies that Property Set in the Notify snippet tag for you. If you don't change that name, Notify will also make sure the Property Set is connected to the Notify snippet when you upgrade. If you use another name for the Property Set, you'll have to remember to reconnect it to the snippet when you upgrade or your updates to Twitter, Facebook, and/or the URL shortening service may stop working.

Placeholders

You can personalize the message sent to each user by using placeholders. All user-specific placeholders, including the unsubscribe_url, now take this form: {{+username}}, {{+email}}, {{+unsubscribe_url}}.

[[+pagetitle]]
[[+description]]
[[+TvName]]
 ... etc.

Tpl Chunks

Important: If you are using the default Tpl chunks, duplicate them and add the prefix 'My' to each one before installing any Notify upgrade. Notify will look first for those prefixed chunks. If it doesn't find them, it will look for the ones specified in the Tpl-related properties. The chunks prefixed with 'My' will not be altered during future upgrades, so you can use them without having to specify them in the snippet properties or in a property set. In other words, you no longer need to specify your own customized Tpl chunks in the properties. Just prefix them with 'My'. Notify will use them automatically and they will survive upgrades.

Groups

As of Version 1.2.0, User Groups can be entered in the form with buttons like the tags. Notify uses the chunk specified in the &groupListChunkName property as the source of the group buttons. That property defaults to the sbsGroupListTpl chunk in the Subscribe category. The chunk should be formatted as follows:

DisplayedGroupName==ActualGroupName||DisplayedOtherGroupName==ActualOtherGroupName

Email is only sent to active users. The &groups property can contain a comma-separated list (no spaces) of User Groups to send to. You can also add them to the form by clicking on the buttons below the input. The buttons come from the content of a Tpl Chunk specified in the &groupListChunkName property. It defaults to the SbsGroupListTpl chunk (see the format for the tags Tpl chunk in the next section). By default, Notify sends to members of the "Subscribers" User group, but you can change that by setting the &groups property of the snippet. Whatever is set will appear in the Notify form, but you can change it there. If you leave the Groups field in the Notify form blank when submitting the form, the email message will be sent to all active users on your site.

Tags

The &tags property is blank by default, so the email is sent to all members of User Groups specified in the &groups property. If you enter tags in the Tags field, only users who have those tags (interests) will receive the email.

You can fill in the user interests for each user as a comma-separated list (no spaces) in the "Comment" field of the User Profile (or optionally in an extended field of the User Profile), but the Subscribe package will do that for you by letting users choose their interests when they register. Subscribe will also let users manage their own interest lists, and unsubscribe, through a link set in emails sent to them by Notify. See the Subscribe package documentation for more information on how the tags are stored.

If you are using the Subscribe package, Notify will use the sbsPrefList Tpl chunk from that package (or another chunk you specify in the Notify &prefListChunkName property) to put tag buttons under the tags input field. Clicking on one of the buttons will toggle that tag in the "Tags" input field. If you register at Bob's Guides (it's free!), you can see this system in action.

If you're not using the Subscribe package and you'd rather use an extended field of the User Profile instead of the comment field, you can create two new System Settings:

sbs_use_comment_field   (set the value to 'No')
sbs_extended_field   (name of the extended field you want to use)

You'll have to create the extended field for each user unless the Subscribe extra has done it for you. You'll also have to create a chunk to hold the list of user preferences (tags) and set the &prefListChunkName property to point to it. By default, the chunk used will be sbsPrefListTpl, which is the default chunk used for tags in the Subscribe extra. If you have created a new preference list chunk for Subscribe, be sure to set the Notify &prefListChunkName property to point to it.

The format for the Preferences List Tpl chunk is a series of Caption==value pairs separated by || symbols.

Example:

Caption One==Option1||Caption Two==option2||Caption Three==option3

The "caption" (to the left of the == signs) is what is shown in the Subscribe extra Register and Manage Preferences forms. The "value" (to the right of the == signs) is what will be stored in the database. It is also used for the tag buttons in the Notify form and is what you should use in the Notify "Tags" input field. Make sure that there are no spaces except in between the words of the caption and that the preferences list is all on one line in the Tpl chunk.

In the Notify form, clicking on a tag button will add or delete that tag from the "Tags" field of the form. The tag buttons shown are based on the tags in the chunk specified in the Notify &prefListChunk property.

Require All Tags

By default, a user will receive an email if he or she has a tag that matches *any* of the tags selected in the form. As of Notify Version 1.1.1, you can add a checkbox to the form that will let you select only users who have *all* the selected tags. You might have a 'developers' tag and a 'modx' tag, for example. With the checkbox unchecked, if you select those two tags in the form, users with either tag will get the email. With "Require All Tags" checked, however, only users with both tags will get the email. Because Notify responds to the checkbox, this option is settable on a per-email basis.

If you don't need this feature, you shouldn't need to do anything. If you do want it, and are using a customized Tpl chunk for the form (rather than the default one), you need to know that the form Tpl has changed. Just insert the following code in your NotifyFormTpl chunk.

<label for="nf_require_all_tags">
    <input type="checkbox" id="nf_require_all_tags" name="nf_require_all_tags" [[+nf_require_checked]]/> [[%nf.require_all_tags? &namespace=`notify` &topic=`form`]]
</label>

The code can go anywhere in the form, but just below the section containing the tag buttons is a good location.

The "Require All Tags" checkbox is unchecked by default. If you would like to change that, add &requireAllTagsDefault=`1` to the Notify snippet tag or set that property to 'Yes' in the Property Set.

Mailgun

The MailgunX class is included with Notify. In order to use Mailgun, you need to go to Mailgun and create an account. Mailgun requires you to set DKIM and SPF records and verify the domain. The method for this varies depending on the domain registrar. Follow the directions at Mailgun. This is a bit of a hassle, but on the plus side, it will increase the deliverability of your emails by quite a bit and prevent them from ending up in the spam folder. If you would like to track opens and clicks, you'll also need to set a CNAME record.

Get a Mailgun API key through your Mailgun dashboard and set it in the Mailgun properties of the Notify snippet (in your NotifyProperties property set as described earlier). You may also wish to get a Mailgun sandbox domain to use during testing and set that in the Notify properties as well. Note that when using the sandbox domain, Messages will still be sent to users. You can set the &testMode to Yes to prevent the messages and tweets from being sent.

Don't forget to set the &mailService property to MailgunX in your property set.

The additionalHeaders property

Notify 1.4.0 adds this property to allow you to add custom headers to your emails. Do *not* use this for standard email fields and headers: to, from, reply-to, etc., this property is for custom headers of your own. The property takes a JSON-formatted string in the following form:

`{"X-header1":"someValue","X-header2":"someOtherValue"}`

You can use the &additionalHeaders property for Cc and Bcc headers, but it's not recommended. Using those fields assumes that the message will be exactly the same for each user, and with some mail services, Bcc headers are not hidden as they should be. Instead, just add the users that should get copies of the message to the User Group that will get the messages.

Launching Notify from NewsPublisher

Recent versions of NewsPublisher will launch Notify after successfully saving a new or updated resource. If the &shownotify property in the NewsPublisher tag is set to 1, you'll see a checkbox for launching Notify at the bottom of the NewsPublisher form. It will contain radio options for selecting the Tpl chunk used by Notify. If the notifychecked property is set to 1, the checkbox will be checked by default. For security, in order to run Notify, the current user needs view_user permission in the 'web' context and must be a member of the Administrator user group (the role doesn't matter).

If you'd like to launch Notify from your own code in a plugin or snippet, the process is very simple. Here's some sample code:

$id = 12; /* Set to the ID of the page with the Notify tag */
$pageId = 22; /* Set to the ID of the page being created or updated */
$pageType = 'new';  /* or 'existing', 'custom', or 'blank' */
$url = $modx->makeUrl($id, "", "", "full");
$_SESSION['pageId'] = $pageId;
$_SESSION['pageType'] = $pageType;
$modx->sendRedirect($url);

Notify and Articles

Notify works fine with Articles. I've sent literally hundreds of notifications about my Articles blog posts. Once you've attached the Notify TV to whatever template you use for your Articles posts, it works as expected. Notify will use the URL shortener specified in the Notify properties rather than the one used by Articles. The only other thing to remember is that the tags used by Articles and Notify are independent. Notify will ignore the Articles tags and Articles will ignore the Notify tags. This is intentional because the Notify tags match up with the limited list of Subscriber interests and the Articles tags are to help users find Articles.

Email Log

For each email update, Notify writes a log file to the core/components/notify/notify-logs directory. The file is named for the resource and date and time of the update. It also includes the mail service used.

The log shows the message sent, the users and their email addresses, and if possible any problems in sending the email to each user. The &maxLogs property determines how many logs are kept. When the limit is reached, Notify will delete the oldest log. The default is 5, but you can set it to any number or 0 for unlimited logs. The logs are sorted roughly by pagetitle, so the newest log could be in the middle of the list — Check the date and time.

When using Mailgun, the Mailgun log (at mailgun.com) can give you information about bounces, clicks, opens, and other issues that won't appear in the Notify send log.

Setting the Notify Properties

Notify has many properties, but for most of them, the default values will work fine. You'll need to set the Twitter properties to send Tweets. If you use MailGun, you'll need to fill in the MailGun settings.

Depending on the URL shortening service you use, you may also have to set the URL shortener properties if you want short URLs. If you want to change the Tpl chunks, you'll want to duplicate them and use a Property Set as described above to set the properties that tell Notify their names so your changes won't be overwritten when Notify is upgraded. If you use a Property Set, don't forget to specify it in the Notify snippet tag on the Notify page like this:

[[!Notify@NotifyProperties]]

The tag above is already set in the install, so if you change the name of your property set, you'll have to change that snippet tag to match.

Controlling Who Uses Notify

The snippet is controlled by the allowedGroups property. The plugin is controlled by the allowedGroups System Setting. Both are comma-separated lists of allowed user groups. The default is the administrator group. Make sure they match or the property value will override the System Setting value for the snippet.

Notify Template and CSS

If you need to modify the Notify Template, duplicate it and change the Template of the Notify page to your new Template. The Notify form CSS file is assets/components/notify/css/notify.css. If you would like to modify it, create a new file and change the reference in the Notify Template (after duplicating the Template and resetting the Template of the Notify page).

Posting Updates to Twitter

In order for Notify to post updates to Twitter, you'll need to create a Twitter App at the Twitter Dev site (if you don't have one already). Log in to Twitter before following the link.

Follow the instructions at that URL for creating a new application. Once you have it all set up, you can go to the the URL above and select the "My Applications" breadcrumb at the top left. Then, click on your Twitter username and select the "OAuth Tool" tab. you should see the four keys you need to set the Notify properties.

See the section above on creating a Property Set if you haven't done so already. To set the properties, edit the Notify snippet and click on the "Properties" tab. Then select your Property Set by clicking on the word "Default" just above the grid on the right. Double-click on a value to change it, and when you're done, click on the "Save Property Set" button (*not* the "Save" button). Don't forget to specify the Property Set in the Notify snippet tag as described above.

Once you've cleared the cache, you can post an update to Twitter from the Template Variable tab of the Create/Edit Resource panel in the Manager. Notify will pre-fill the Tweet TV for you, but you can edit it to contain whatever you like. Notify will enforce the 140-character limit on the length of the tweet.

Posting Updates to Facebook

Notify does not post directly to Facebook, but you can set up an account at Selective Twitter in about 30 seconds. Once you've done that, simply add the hashtag #fb to any Tweet and the Tweet will be posted to your Facebook page in addition to Twitter. If you set the ¬ifyFacebook property of the Notify snippet, the #fb hashtag will be added automatically to the end of the Tweet and you'll see it in the Notify form. You can remove it manually if you don't want the Tweet to go to Facebook.

You can also use a Twitter App if you want to post *all* your Tweets to Facebook, but I don't recommend doing that if you're a heavy Twitter user because it will load up your Facebook page with lots of Tweets that most visitors won't want to see.

How Notify is Launched

There's no reason you need to know, but you might be curious about how the Notify form is launched from the TV tab of the Create/Edit Resource panel. The method is quite exotic. The Caption of the Notify TV is actually a <button> tag:

    <button id="nf-b" onClick="nf()"> Launch Notify </button>

When the button is clicked, it launches the nf() JavaScript Function. The JavaScript source code is in the Notify plugin, which is connected to the OnDocFormPrerender event. When the Manager form is rendered, that plugin gets information about the current resource, replaces the placeholders in the JS code with the appropriate values, and injects the JS into the section of the Manager form page.

The JS code adds the color to the button and adds the form below the button with hidden input fields containing the page info. When the button is clicked, the JS code checks to make sure the Resource has been saved (popping up a warning if it hasn't), and if it has, submits the form to the Notify page where the information is read from the $_POST array. It's difficult to imagine doing this in any other CMS but MODX without touching a line of the core code.

Troubleshooting

If you create a Property Set and it is not taking effect, double check the name of the Property Set and the name used in the Notify snippet tag. They must match. Make sure the Property Set is connected to the snippet. You should be able to see the Property Set when you click on the Default drop-down on the Properties tab of the Snippet. If it's not there, click on the "Add Property Set" button and select the Property Set. Then click on the "Save" button at the upper right (not the "Save Property Set" button).

If you upgrade Notify and your Property Set is no long shown in Tools | Property Sets, it may mean that the Property Set has an obsolete category. The only solution is to use PhpMyAdmin to edit the modx_property_sets table and change the category of the Property Set to 0.

If you follow the Unsubscribe/Manage Preferences link in a test email using the same browser you used to send the emails, you'll have to log out or Flush All Sessions before doing anything else in the Manager. This is because following the link resets $modx->user, which changes the MODX session in that browser.

Make sure that the value of the allowedGroups property matches the value of the allowedGroups System Setting.

If you are testing on a localhost install, some URL shortening services (bit.ly for one) will fail to produce a valid URL. This is normal — they just don't consider "localhost" a valid domain.

If no emails are being sent using the modMailX service, install the QuickEmail package to help diagnose your problem sending emails.

Adding a New MailService

As of Notify 1.4.0, it's much easier to add support for a new mail service such as Sendgrid, Mailgrid, or CampaignMonitor, for use with Notify. You can create a new class that extends an existing third-party API wrapper class (usually obtained from the mail service's web site) and your class will plug in to Notify.

Include the third-party wrapper class at the top of your class file. Your class should implement the Notify MailService interface found in the mailservice.php file in the Notify model directory. Include that file also at the top of your class file. Add an X to the name of the parent class for your class name, and a .class.php suffix to the class file. Declare your class like this example that implements a hypothetical SendGrid service :

Class SendGridX extends SendGrid implements MailService {}

For your class, start with the MailgunX class file contents and modify it to match what the SendGrid, or other mailservice, expects. Then add the service name (e.g., SendGridX) to the &mailService property of the Notify snippet. You may not need all the methods of the MailService interface, but they all must be present, though the body of unused methods can be empty. You may also want to add your class and the wrapper class to the autoload_classmap.php file in the Notify vendor/composer directory.

This is not a trivial job, but it's much easier than it was before the creation of the MailService interface.

It's also possible to bypass the API wrapper class and write your own base class to interact with the mail service API or add the necessary methods to your own class, but it's usually much easier to use an existing API wrapper as your base class.

Notify Properties

Copyright © 2011-2025
Bob Ray