Subscribe Snippet Tutorial
If you use this extra and like it, please consider donating. The suggested donation for this extra is $15.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.
Subscribe provides a double-opt-in User registration system. It uses some parts of the Login package, so be sure the Login package is installed before using Subscribe.
Subscribe 1.3.0 and later are compatible with MODX 3
(Jump to System Settings Table.)
About Subscribe
Subscribe provides a request-to-subscribe message that will appear on pages at your site. When Users choose to subscribe and submit the registration form, they receive an email message with a link to confirm their registration. The request-to-subscribe message will not be shown to Users who are logged in (they will see a logout link). You can also hide the request-to-subscribe message on selected pages with the &noShows property in the SubscribeRequest snippet tag.
As soon as a User submits the Registration form, a User record and a User Profile for the User are saved in the MODX database, but with the User marked as inactive. When the User responds by clicking on the link in the email, they are taken to the site, marked as active, logged in, and sent to a "Registration Confirmed" page.
The default registration form also includes the option of checkboxes for the User to indicate interests. The User's interests will be saved as a comma-separated list in the comment field of the User's Profile (or, optionally, in an extended field of your choice). This allows you to send email messages to Users based on their interests (the "Notify" extra will do this for you). You can also design systems that respond to User interests by customizing menus, or forwarding Users to particular parts of the site on login, etc.
There is also a Manage Preferences form that lets the user change their interests and/or group memberships at any time. It also allows the user to unsubscribe.
If you are installing or upgrading from version 1.2.0 of Subscribe or later, you shouldn't have to make any changes. You can click here to skip over the upgrade notes.
Upgrading from Version 1.1.3 or earlier
If this is a new install or you are upgrading from Subscribe 1.1.4 or newer, you can skip down to the next section.
Important: For Newer Versions, the captions and values in the PrefList Tpl chunk have been reversed from the order in earlier versions to conform to the standard for MODX TV Input Values. The correct order now is:
Caption One==Option1||Caption Two==option2||Caption Three==option3
Be sure to put them all on one line.
In Version 1.1.4, these System Settings have new names to avoid conflicts with other components:
- cssPath -> sbsCssPath
- cssFile -> sbsCssFile
- jsPath -> sbsJsPath
- jsFile -> sbsJsFile
The installed CSS has changed in Version 1.1.4 to make the Logged-in and Logged-out displays larger and easier to read. If you are using the default CSS file, you may have to make adjustments to your site's CSS file to compensate for the larger size.
As of Version 1.1.4, a number of element, setting, and directory names have changed and quite a few internal changes were made to make Subscribe easier to configure and to avoid conflicts with other extras. All of the default chunks and snippets have been renamed.
Since everything was changing, I took the opportunity to refactor Subscribe from the ground up to streamline the code and, hopefully, to make it much easier to use and configure.
The good news is that the new version installs everything you need except the login page and automatically configures everything (with the exception of the System Setting for the login page if your login page has an alias other than "login"). Be sure to read this whole section carefully before upgrading from Versions 1.1.3 and earlier. The upgrade is easier than it sounds. The simplest method, by far, is to completely uninstall and remove the old version, including any Resources except the Login page. It is strongly recommended that you uninstall and remove Subscribe before upgrading.
All "sm" and "Sm" prefixes have been changed to "sbs" and "Sbs" to avoid conflicts with other extras. If you've created a custom CSS file be sure to back it up outside the subscribe directory, though it will be of limited use because many of the classes and IDs have changed.
IMPORTANT! If upgrading from a version < 1.1.4, you must either delete the Subscribe Resources (except the Login page) or change their aliases. If you don't, the install will be corrupted. You may want them for reference, but it's not necessary. If you do keep them, be sure to change the aliases on all but the Login Resource. Subscribe will create new Resources for you in a folder called "Subscribe Folder". These are the resources that will be used by Subscribe. You can delete your old resources once you are satisfied with the new ones. Be sure not to copy the contents of your old resources into the new ones since the tags have changed. If you delete the resources, be sure to empty the trash (click on the trashcan icon above the Resource tree) to remove them from the database.
I apologize for the inconvenience. Future upgrades should go much more smoothly.
If you have created any new Tpl chunks for Subscribe, they will survive the upgrade, but they may not be in the Subscribe category after the install and they really won't be of any use, because all the Tpl chunks have changed.
In the new version, your login page should have an alias of "login". Be sure the page exists before installing Subscribe so that the package can set the sbs_login_page_id System Setting correctly. If you forget, or your Login page has a different alias, set that System Setting manually in System | System Settings (namespace: subscribe) after the install is finished.
Upgrading from Version 1.1.4
Subscribe Version 1.1.4 added new users to the Subscribers User Group with a Role of Subscriber. As of Version 1.2.0, Users can be assigned to multiple groups with multiple roles and can (optionally) control their own user group membership on the Manage Preferences page. See the sections below on managing groups and creating the groups and roles.
Letting users manage their User Group memberships is optional. If you have a working version of Subscribe and want to keep doing what you're doing, the new version should work as the old one did.
Be sure that all User Groups and Roles exist before anyone registers.
In Version 1.2.0, the placeholders in the Register and Manage Preferences chunks (sbsRegisterFormTpl and sbsManagePrefsFormTpl) have changed. For backward compatibility, the old placeholders will still work, but if you want to let users manage their User Group memberships, you'll need to use the new ones. The new placeholders are:
[[+sbs_interests_caption]] [[+sbs_interest_list]] <br class="clear"/> [[+sbs_groups_caption]] [[+sbs_groups_list]]
They are now the same for both chunks
There are several new System Settings. The &sbs_show_interests and &sbs_show_groups settings control whether the Interests and Groups sections of the Register and Manage Preferences forms are displayed. For backward compatibility the first is true by default and the second is false. In Version 1.2.0 and newer versions you can use these properties to show either section or both. See the section below on Controlling the Forms.
There is also a &userRoles System Setting (see below) to control the roles users will get in their User Groups.
Note: If you have any Subscribe System Settings, chunks, or snippets with the prefix 'sm' you can remove them. They are left over from pre-1.1.4 versions and are no longer used. They caused conflicts with another extra.
Installing Subscribe
The Subscribe install can be slow because of the creation of System Settings. Be patient.
If you are upgrading from a previous version. You will see messages during the install about things that already exist and can't be updated. This is normal.
To install Subscribe, go to 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 Subscribe in the search box and press Enter. Click on the "Download" button. When the download has finished, click on the "Back to Package Management" button. That will bring you back to your Package Management grid. Click on the "Install" button next to Subscribe in the grid. The Subscribe package should now be installed.
If you have not installed the Login package, do that before continuing and create a Login page (if you don't already have one) with the alias of "login". The minimum content for that page is:
[[!Login]]
Displaying the Request to Subscribe Message
Put the following tag in the <body> section of any templates for pages that should show the request-to-subscribe. In the &noShows property, put a comma-separated list containing the IDs of other pages where the request should not be shown. By default, the request is not shown on the Login, Registration, Thanks for Registering, Manage Preferences, and Confirm Register pages. Add the IDs of any other pages it should not be shown on to the &noShows property in the snippet tag in the template. The tag will be replaced by the "Request to Subscribe" message (which, by default, appears horizontally on a single line) for users who are not logged in and by the "Logout" link for users who are logged in.
The SubscribeRequest snippet must be called uncached because it needs to evaluate the user's login status.
[[!SubscribeRequest]]
or
[[!SubscribeRequest
&noShows=`##,##,##`
]]
Replace "##" with the Resource IDs of any pages where you don't want to show the Subscribe Request.
Upgrade note: As of Subscribe 1.2.0, the registration confirmed page is no longer in the noShows list by default so that when users follow the registration email link they will see the "Manage Preferences/Unsubscribe" option. I strongly recommend that you leave this alone, but if you don't want to show it there, you can send the ID in the &noShows property in the SubscribeRequest snippet tag in your template(s).
Of course you're free to create your own subscribe request or link and your own login/logout link and leave the tag above out of your template, but it's usually easier to create your own Tpl chunks to use in place of the built-in ones used by the Subscribe Request snippet (sbsLoggedOutDisplayTpl and sbsLoggedInDisplayTpl). Change the loggedOutDisplayTpl and loggedInDisplay System Settings to point to your own Tpl chunks.
Creating the User Group and Role
Version 1.1.4 of Subscribe adds new users to the Subscribers User Group with a Role of Subscriber (via the Register snippet). IMPORTANT: Both the group and the role must exist before the first user registers. This is still the default option in Version 1.2.0, but it also allows you much finer control and (optionally) lets users manage their own group memberships (see below).
To create the User Group, go to Security | Access Controls | User Groups & Users tab. Click on the "New User Group" button. Enter Subscribers for the name. Add a description if you want one. Then, click on the "Save" button.
To create the Role, click on the "Roles" tab, then on the "Create New" button. Enter Subscriber for the role, add a description (optional), and enter a number between 0 and 9999 (I use 50) for the "Authority" level. Then click on the "Save" button.
Managing the Forms
As of Version 1.2.0, you have multiple options for both the Register and Manage Preferences forms. You can set the sbs_show_interests System Setting to true to show the Interests List section and you can set the sbs_show_groups System Setting to true to show the User Groups section. You can show either or both.
If every user will be assigned to the same User Group(s) with the same Role(s), let the Register snippet handle this. Leave the sbs_show_groups System Setting off and, in the Register snippet tag of the sbsRegisterFormTpl chunk, use the &usergroups property:
&usergroups=`usergroup1:role1,usergroup2:role2`
If, instead, you would like to let the user select the User Groups to which they want to be assigned, remove that property from the Register snippet and change the sbs_show_groups System Setting to true. Note that you can override the System Settings with properties in the snippet tag, but if you do that, be sure to do this in *both* the sbsRegisterFormTpl and sbsManagePrefsFormTpl chunks.
If you want even finer control, you can create Context Settings or User Settings with the same names as the System Settings and have a different form for different Contexts or different Users. Context Settings override System Settings, User Settings override both, and properties in a snippet tag override everything else.
The User Groups shown on the form come from the sbsGroupsListTpl chunk. They are in this form:
User Group One==group1||User Group Two==group2
The part before the == is the Caption to be shown on the form. The part after the == is the actual Group name (they can be the same if you like). Be sure the name of each User Group is the same as the part after the == sign in the Tpl chunk (they are case-sensitive).
In order for Subscribe to know what Role to use for each group, you must also set the sbs_user_roles System Setting. It takes this form:
group1:role1,group2:role2
Note that the Groups selected by the user (and their roles) are independent of the ones set in the Register snippet tag. You can use either or both methods. For example, you might want all users to be assigned to the Subscribers Group with a role of Subscriber, but let the users select additional groups to belong to. In that case, leave the default &usergroups line in the Register snippet tag and add the other groups to the sbsGroupsListTpl and the sbs_user_roles System Setting.
If you do let users select their own groups and/or interests, you can add new ones at any time by editing the sbsPrefListTpl and/or sbsGroupListTpl chunks. If you add new User Groups, be sure to adjust the sbs_user_roles System Setting to assign the user roles in the new groups.
Subscribe System Settings
The Subscribe System Settings containing page IDs will be set automatically during the install, but you may want to check to make sure they are set correctly, especially if you are upgrading from a previous version. Go to System | System Settings and select the "subscribe" namespace in the dropdown menu at the top of the grid (the "core" namespace will be showing by default). Note that the "subscribe" namespace may be not be on the first page of the list. You can click on the plus sign next to a System Setting to see a description for the setting.
In the current version, rather than setting properties in multiple places, you only need to set the basic System Settings and they'll be used by all parts of the subscribe package. This means you shouldn't need to modify any tags in the Chunks or Resources. The Settings can be overridden by properties in the various Subscribe tags, but you should rarely, if ever, need to do that.
Testing
Before testing, clear the cache and make sure that the following resources are published and hidden from menus (unless you want to show the Register page in the menu).
- Register
- ConfirmRegister
- Thank You for Registering page
- Manage Preferences
- Registration Confirmed
- Unsubscribe
Due to a bug in the Login snippet (Version 1.7.3), users responding to the registration email are logged in as the (anonymous) User rather than as themselves. Be sure you have Version 1.8.0 of the Login package (or newer).
Test your system by visiting the site from another browser where you are not logged in to the Manager. When you are logged in to the Manager and are previewing the site, your login status is ambiguous. You're logged in, but not to the 'web' context, so Subscribe's login status checks can give odd results.
It's recommended that you test the Subscribe system as installed before modifying it to meet your needs (but check the Login Page ID System Setting to make sure it is set correctly).
Go to the Register page and register as a new User. See if you get the email and, if so, use the link in the email to confirm the registration. You should end up on the Registration Confirmed page. If that doesn't all happen, check the publication status of the resources -- all should be published. If they are, check the various Resource IDs in the Subscribe System Settings.
Next, log in to the Manager. Check to make sure that the new User exists and is active. Go to Security | Manage Users. Right-click on the new user and select "Update User". Check the comment field of the User Profile to make sure that the interests are recorded there (or the Extended Fields tab if you have chosen that option). Delete the User.
Customizing Subscribe
You will definitely want to change the preferences list used in the Registration form and the Manage Preferences form. To set the available preferences, duplicate the sbsPrefListTpl chunk (call it MysbsPrefListTpl) and edit the entries. Then set the prefListTpl System Setting to "MysbsPreflistTpl".
The format for the Preferences List Tpl chunk is a series of Caption==value pairs separated by ||:
Caption One==Option1||Caption Two==option2||Caption Three==option3
The caption (to the left of the == signs) is what will be shown in the form. The value (to the right of the == signs) is what will be stored in the database. 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.
If you want to show the User Groups section of the form, you will need to follow a similar process with the sbsGroupsListTpl chunk. You'll also need to change the showGroups System Setting and the userRoles System Setting. You may also want to remove the &userGroups property in the Register snippet tag in the sbsRegisterFormTpl chunk.
There is JavaScript validation for all fields in the Register form. All fields are required. The Username and Password fields are required to be at least 6 characters long and the two Password fields must match. The Email field is also checked to make sure it's a valid address. The User must also check at least one of the "Interests" checkboxes if that section is shown and select at least one User Group if that section is shown.
By default, the user's preferences are stored in the comment field of the User Profile. This is the preferred method because retrieving the user's preferences in code and displaying them on a page will be much faster and easier. If you need the comment field for something else, though, you can change the method used and have the preferences stored in an extended field of the User Profile. To do so, just go to System | System Settings, select the "subscribe" namespace, and change the Use Comment Field setting to No. The user's preferences will be stored in an extended field in the User Profile called "interests". If you need to change the name of that field, you can modify the Subscribe Extended Field System Setting.
Styling the forms
The "request-to-subscribe" message is styled to appear on a single horizontal line, but you can restyle it with CSS to appear in another form since the message and all buttons are contained in identifiable <span> tags with the text inside them in <a> tags.
The default styling for the message is float:right, but you can change the CSS file. Be sure to change both the loggedInDisplay and the loggedOutDisplay sections. You may want to leave the float, but keep other elements from wrapping around the message. If so, you can add <div style="clear:both"></div> above, and/or below the message in your template. See the section below on modifying the CSS file. If you modify the existing file, your changes will be overwritten when you upgrade Subscribe.
Both the Register form and the "request-to-subscribe" message are styled with the /assets/components/subscribe/css/subscribe.css file, as are the two popup windows. See the section below on modifying the CSS.
The popups are done with CSS and a tiny bit of embedded JavaScript to toggle their visibility. You can modify their position and appearance in the subscribe.css file.
To change the message in the popups, duplicate the sbsPrivacyDialogTextTpl and sbsWhyDialogTextTplchunks. Add "My" as a prefix to their names and modify the following two Subscribe System settings to match: whyDialogTextTpl and privacyDialogTextTpl.
As currently styled, the popups will automatically expand to match the content length.
Modifying the CSS
If you want to modify the CSS of JS used for Subscribe, it's best to duplicate the subscribe.css and/or subscribe.js file so they won't be overwritten by upgrades:
assets/components/subscribe/css/subscribe.css assets/components/subscribe/js/subscribe.js
You can specify the files to be used with the your CSS file with the sbsCssPath, sbsCssFile, sbsJsPath, and sbsJsFile System Settings. If your files are in the same directory as the originals, you only need to modify the sbsCssFile and/or sbsJsFile settings, but note that your files will be deleted if you uninstall Subscribe.
If you want to add the CSS to your main CSS file, set the sbsCssFile System Setting to none and the CSS file will not be loaded.
You can do the same with the SbsJsFile System Settings. By setting it to none, the JS file will not be loaded and your form can use the Register snippet's validation or your own custom validation.
The subscribe-min.js file is used only by the registration form and is loaded automatically by the snippet that presents the form, based on the sbsJsPath and sbsJsFile System Settings. The JavaScript used to display the two popup windows in the subscribe request is in the sbsLoggedOutDisplayTpl chunk. If you need to change it, see the following section.
By default, The registration form uses subscribe-min.js. You can change that by setting the sbsJsFile System Setting.
Modifying the Tpl Chunks
All the Tpl chunks used by Subscribe are settable with properties. When MODX is looking for a property, it will use a property set in the snippet tag, but if no property is set there, it will check the System Settings table for the property. Because Subscribe uses the same properties in different chunks and snippets, the Tpl chunk names are set as System Settings. You can override them with properties in the snippet tags and chunks, but using the System Settings is easier and more reliable.
If you want to modify any of the default Tpl chunks, duplicate them and change the name by adding "My" as a prefix. Then, modify the value of the appropriate Subscribe System Setting by adding "My" as a prefix. Go to System | System Settings and select the "subscribe" namespace in the drop-down list at the top of the grid. You can click in the plus sign to see a description of each setting. Double-click on the value of the setting you want to change, change it, and click somewhere else in the grid. Be careful — the names are case-sensitive, and if you misspell them in the System Settings grid, Subscribe will continue to use the default Tpl chunks, CSS, and JS files.
Unsubscribe
As of Version 1.2.0, Subscribe has an Unsubscribe class that can create a secure unsubscribe link to include in emails. This feature is for use by the Notify and EmailResource extras. It does not affect the operation of Subscribe, but the code is there if you want to roll your own system to provide such a link in bulk emails.
Modifying the Resources
You may be able to make the resources look the way you want by modifying the CSS. If not (for example, you need to translate the resources), duplicate the resources and change the appropriate System Setting so Subscribe will be able to find it. Your new resources and settings will survive upgrades, but won't be removed if you uninstall Subscribe.
Interest Report
As of Version 1.2.1, Subscribe will display a table showing the active user count for interest tags, User Groups, or both. To see the report, just view the "Interest Report" Resource in the Subscribe folder. The snippet that produces the report uses the Subscribe System Settings to decide what to show. You can override the settings with properties in the InterestReport snippet tag on the "Interest Report" page. Usually, this won't be necessary, but if you want to show User Group membership and don't allow users to manage their groups, you can use &sbs_show_group=`1` in the tag and put the groups in the sbsGroupListTpl chunk. Note that the groups don't have to have anything to do with Subscribe, so you can use this as a general report for User Group membership.
Subscribe System Settings
| Setting | Description | Default |
|---|---|---|
| sbs_register_page_id | Resource ID of the Subscribe Register page (with the registration form) | (set automatically) |
| sbs_login_page_id | Resource ID of the Login page | (set automatically) |
| sbs_confirm_register_page_id | Resource ID of the Subscribe Confirm Register page | (set automatically) |
| sbs_manage_prefs_page_id | Resource ID of the Subscribe Manage Preferences page | (set automatically) |
| sbs_registration_confirmed_page_id | Resource ID of the Subscribe Registration Confirmed page (the page the user is sent to after clicking on the link in the registration email) | (set automatically) |
| sbs_thank_you_page_id | Resource ID of the Subscribe Thanks for Registering page (the page the user is sent to immediately after submitting the registration form) | (set automatically) |
| prefListTpl | Tpl to use for the list of user preferences | sbsPrefListTpl |
| groupListTpl | Tpl to use for the list of user groups | sbsGroupListTpl |
| checkboxTpl | Outer Tpl to use for the list of user preferences | sbsCheckboxTpl |
| loggedOutDisplayTpl | Tpl to use for the Subscribe logged-out display | sbsLoggedOutDisplayTpl |
| loggedInDisplayTpl | Tpl to use for the Subscribe logged-in display | sbsLoggedInDisplayTpl |
| whyDialogTpl | Outer Tpl to use for the Why Subscribe popup dialog | sbsWhyDialogTpl |
| whyDialogTextTpl | Tpl to use for the text in the Why Subscribe popup dialog | sbsWhyDialogTextTpl |
| privacyDialogTpl | Outer Tpl to use for the privacy Subscribe popup dialog | sbsPrivacyDialogTpl |
| privacyDialogTextTpl | Tpl to use for the text in the privacy Subscribe popup dialog | sbsPrivacyDialogTextTpl |
| sbsCssPath | Path to Subscribe CSS file | {assets_url}components/subscribe/css/ |
| sbsCssFile | File name of Subscribe CSS file; set to 'none' for no CSS file | subscribe.css |
| sbsJsPath | Path to Subscribe JS file | {assets_url}components/subscribe/js/ |
| sbsJsFile | File name of Subscribe JS file; set to 'none' for no JS | subscribe.js |
| sbs_use_comment_field | If set to 'Yes' user preferences are stored in the comment field of the User Profile. If set to 'No', prefs are stored as an extended field in the user profile in the field specified by the 'sbs_extended_field' setting. Default: 'comment'. The | 1 |
| sbs_extended_field | Name of field to store user prefs in user profile extended fields. Ignored unless useCommentField is set to 'no | interests |
| language | Language to use for Subscribe | en |
| sbs_secret_key | Used by Notify and EmailResource to provide a secure unsubscribe link | (set automatically) |
| sbs_unsubscribe_page_id | Resource ID of the Unsubscribe page | (set automatically) |
| sbs_user_roles | Comma separated list of groupname:role pairs | |
| sbs_show_Interests | If true, the Interests section will be shown on the Manage Preferences and Register forms | true |
| sbs_show_groups | If true, the User Groups section will be shown on the Manage Preferences and Register forms | false |
| sbs_field_name | Field name to use for interest list checkboxes - no need to change this unless there is a conflict with something else on the page | interests |
| sbs_groups_field_name | Field name to use for User Group checkboxes - no need to change this unless there is a conflict with something else on the page | groups |
My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be 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
