MessageManager Snippet 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 $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-commercial extras with a clear conscience.


PayPal

MessageManager lets users see and delete their messages in the front end of the site. They can also mark the messages as read or unread. The messages are the same ones available in the Manager as part of the MODX messaging system.

Depending on the configuration, users can also reply to messages and send messages to another user, to all members of a User Group, or to all users on the site. Optionally, users can opt in or out of receiving message based on their membership in a particular user group.

(Jump to MessageManager snippet Properties Table.)

(Jump to mmAjax snippet Properties Table.)

Installing MessageManager

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 MessageManager in the search box and press Enter. Click on the "Download" button, and once the package is downloaded, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to MessageManager in the grid. The MessageManager package should now be installed.

Usage

Users can access MessageManager simply by visiting the Message Manager resource. They have to be logged in to the front end of the site in order for MessageManager to know which messages are theirs. Clicking on a message subject reveals the message and marks it as read. Right-clicking on a message opens a context menu that allows users to delete the current message, reply to it, mark it as unread, or send a new message. Messages can also be bulk deleted using the checkboxes next to the messages and the "Delete" button.

When replying to a message, users can quote the original message by clicking on the "Quote" button.

When the "New Message" option is selected from the context menu, users can have the option to send a message to an individual user, to all members of a User Group, or to all users on the site. You can control which of these options appear by setting the recipient_options property of the MessageManager snippet.

You can select which User Groups are allowed to use MessageManager, which groups are shown in the "User Groups" dropdown menu, and which Users can be sent messages.

Login

If the current user is not logged in to the current context (e.g., 'web'), MessageManager will redirect the user to the Resource whose ID is set in the redirect_to property of the MessageManager snippet. If the redirect_to property is not set, MessageManager will redirect to the Login page if its pagetitle is "Login" or to the resource specified by the site_start System Setting if no Login page is found.

If you have &redirecToPrior=`1` in your Login snippet tag, the user will be redirected back to the MessageManager page after successfully logging in.

Controlling Which Users Can Use MessageManager

Only users with the messages permission in the Context Access ACL entry for the current context will be able to use MessageManager.

In addition to the messages permission, the allowed_groups property of the MessageManager snippet controls who can use MessageManager. The property takes a comma-separated list of User Group Names or IDs. If the current user is logged in, but not a member of any of the groups, they will see an error message. If the allowed_groups property is empty, all users will be allowed to use MessageManager.

If you use the allowed_groups property, be sure the User Group names are spelled correctly or the IDs are correct. Otherwise, some users will not be able to user MessageManager.

Recipient Options

When a user selects "New Message" from the context menu, they can send messages (optionally) to individual users, to selected user groups, or to all users. The available options are controlled by the recipient_options property of the MessageManager snippet. The default setting is user,usergroup,all. To change the options, just leave out one or two of the options. You must have one option selected, or no messages will be sent.

The captions for the Options are lexicon strings in the default.inc.php lexicon file. If you change them in Lexicon Management in the Manager, your changes will survive upgrades to both MODX and MessageManager. Look in the messagemanager namespace and the default topic.

 

The options above are properties of the MessageManager snippet. The ones below are properties of the mmAjax snippet.

 

Limiting the User Group List

The exclude_groups property of the mmAjax snippet controls which User Groups will appear in the drop-down menu when a user selects "New Message -> User Group". The property takes a comma-separated list of User Group names or IDs to exclude from the list. If the property is empty, all groups will be shown.

If the property below (user_group) is not empty, it will override exclude_groups and only the specified group will be shown in the dropdown.

Opting Out of the Message System

The user_group property controls which users will show up as possible recipients if the user selects "New Message -> User". If the property is empty, all users on the site will be shown. The property takes the name or ID of a single user group, because that's all the "user/getlist" processor understands. Only users who are members of the specified group will be shown. Since users can belong to more than one User Group, any user can be placed in the group.

If this property is set, the exclude_groups property will be ignored when producing the User Group dropdown. Only the group specified in user_group will be shown.

The Subscribe extra can be configured to allow users to select user groups they want to belong to when they register, so you can use it to allow users to opt-in to the Message System. It also allows them to change their preferences later.

Even if a user has opted out of receiving messages, they can still reply to a message sent to them before they opted out, but they will not receive any new messages.

MessageAlert Snippet

This snippet is provided to let you notify users of any available messages. Except for the numbers, the results are lexicon strings in the default.inc.php file.

As with the captions described above, if you change them in Lexicon Management in the Manager, your changes will survive upgrades to both MODX and MessageManager. Look in the messagemanager namespace and the default topic.

To add the alert message, put code like this anywhere in the page template or the page content:

<div id = "mm_alert">
    <p id="mm_alert_message">You have [[!MessageAlert]]</p>
</div>

The code above will result in a message like one of the following:

You have no messages
You have 4 messages (2 unread)
You have 1 message (0 unread)

MessageManager Snippet Properties

Property Description Default
recipient_options Options for sending messages; these options show up in the dropdown list when sending a new message; you must include at least one option user,usergroup,all
redirect_to Id of Resource to redirect to if user is not logged in (e.g. the Login page); If this is not set, MessageManager will redirect to the Login page if its pagetitle is "Login", or the site_start page if not
allowed_groups Comma-separated list of User Group names or IDs that are allowed to access MessageManager; if empty all groups are allowed

mmAjax Snippet Properties

Property Description Default
exclude_groups Comma-separated list of User Group IDs or names that can not be sent bulk messages; if empty all user groups can be sent messages empty
user_group User Group ID or name that has opted to receive messages; if empty, all users can be sent a message empty

 

 

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