Bob's Guides

MessageManager 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.

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.)

(Jump to MessageAlert snippet Properties Table.)

Installing MessageManager

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 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.

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

mmAjax Snippet Properties

MessageAlert Snippet Properties

Copyright © 2011-2023
Bob Ray