Table of Content

• Plugin Installation & Activation
• User Interface Setup
• Plugin Configuration
• Custom Themes
• Notification Process
• Template Functions

Plugin Installation & Activation

In order to use the plugin, you must of course first get the files on your server. If you are upgrading from a previous version of the plugin, you need to follow steps 1 and 2 described below. If you are installing the plugin for the first time, you can go directly to step 2.

Step 1 - Deactivation and deletion of the old version

1. Make a backup of your database in case anything goes wrong.
2. Get to the "Plugins" » "Installed" page and find the plugin in the list.
3. Click on the link to deactivate the plugin (below its name).
4. Click on the link to delete the plugin files (below its name) and confirm the deletion in the next screen.

The plugin files have now been deleted. Don't worry, the database is still holding all the configuration information and the messages of your users. You can now proceed to Step 2 in order to install the new files.

Step 2 - Upload and activation of the new version

1. In the WordPress administration panel, get to the "Plugins" » "Add New" page and click on the link "Upload".
2. Select the zip file containing the version of the plugin you want to install and start the upload process.
3. Now get to the "Plugins" » "Installed" page and activate the plugin.

The plugin should now be active. You can verify this by checking that you see the "User Messages" menu item under the Settings menu of your WordPress administration interface.

Back to the table of content

User Interface Setup

The plugin is now activated. You need your users to be able to access a page on your site where they can write and read messages.

1. In the WordPress administration panel, get to the "Settings" » "User Messages" page and select the "User Interface" tab.
2. You can click on the "Create this page" button. A new page will be created on your site as a draft.
3. If everything goes well, the ID of the page should be displayed in the text box next to the button and you are shown a link to edit the page. Edit this page and publish it so that your users can start accessing the plugin features. You can change the page title but the content of the page shall only be the shortcode {user-messages /}.

The interface to the plugin is much more usable if your page is displayed without sidebar. Please check if your theme provides one. Else, you can also use a page based on the default theme. Copy the file "page-without-sidebar.php" located in the plugins "extras" directory to your theme's directory. Now edit the page where the plugin's user interface is displayed and select the template named "No Sidebar".

You are also able to add a widget to the sidebar for faster access to the interface.

1. In the WordPress administration panel, get to the "Appearance" » "Widgets" page.
2. You should be able to see a widget named "User Messages". You can drag it to the sidebar. Note that this widget is only displayed to logged in users. Indeed, guests are not authorized to send messages.

Back to the table of content

Plugin Configuration

You will find the options of the plugin in the "Settings" » "User Messages" page. The page is organised in panels to group options by categories. Here is a description of the options

General settings

User quota

This value sets the maximum number of messages that a user can keep in his folders. If a user exceeds his quota, he cannot receive any more messages.

User quota warning

This value sets a warning threshold to ask the user to delete some messages. If a user has more messages than this, he will not be able to send messages until he deletes some messages in his folders. However, he will still be able to receive messages until he exceeds his quota (see previous option).

Max. Recipients for Private Messages

You can limit the number of recipients to whom a user can send private messages at once. 0 means no limit. 3 for example means that the users will not be able to send a message to more than 3 other users at the same time.

Max. Recipients for Role Messages

This is the same as above but for roles.

User Display Name

You can choose how the user names are shown and sorted in the send message/email pages.

Notifications

The plugin sends notifications by email when some events happen: a user exceeds his quota, he is reach the quota warning value or simply he receives a new message. On this panel, a button allows you to send to yourself some sample notifications. This will allow you to check if the notification system is working and also to see the messages as the users receive them.

Notify on public message

Users are notified by email when they receive a new message. If you uncheck this option, the users will not be notified if they receive publi messages (sent to everybody).

Notification batch size

To avoid sending too many notification emails at the same time, you can adjust here the number of notifications sent in each batch. You can increase this value if too many notifications get accumulated in the system.

Notification task interval

Notifications are queued and processed by batch. This is the time between each task execution in minutes. You can try a lower value if too many notifications get accumulated in the system.

New message notification

You can customize the generic notification email sent when a user receives a new message.

Inbox full notification

You can customize the generic notification email sent when the message box of a user is full.

Quota exceeded notification

You can customize the generic notification email sent when a user exceeds his quota and is thus forbidden to send messages.

Within the notification subject and body, you can use the tags %BLOG_NAME%, %BLOG_URL%, %USER_MESSAGES_URL%, %TOTAL_MESSAGE_COUNT%, %UNREAD_MESSAGE_COUNT%, %USER_QUOTA%, %RECIPIENT_NAME%, %MESSAGE_AUTHOR%, %MESSAGE_SUBJECT% and %MESSAGE_CONTENT%. They will be replaced by the appropriate value.

User Interface

These options allow to configure the user interface of the plugin.

ID of the post or page where the interface shall be displayed

This is the ID of the page where you will see the user interface. You should have already seen this option when setting up the user interface.

Theme URL

The appearance of the user interface can be customized by using another theme than the one provided with the plugin. See the Custom Themes Section of this page to know more about this.

Slug for XXX action

These options are shown only if you are using permalinks (see the WordPress manual). The user interface URLs are built on the form http:/www.your-site.com/user-interface-page-slug/action-slug/. You can change the action-slug part in order for example to have URLs in your language. It is recommended that those fields contain only small capitals, numbers and dashes (for example "read-message" is correct, "Read Message" should work but is not recommended and "Read/Message" is incorrect because of the "/").

Roles & Capabilities

You can configure here who is allowed to do which actions. A table show in columns the roles of your site and in rows the capabilities used by the plugin. Checkboxes tell if user having the given role can do the given action. Below is a description of the various capabilities. You can have a short description in a tooltip by placing the mouse cursor over a row.

UM Use Plugin

The user can use the User Messages plugin (he can see the user interface and the widget).

UM Receive Msg

The user can receive messages from other users

UM Send Private Msg

The user can send private messages (the recipient is a single user

UM Send Public Msg

The user can send public messages (the recipient is a selection of user groups

UM Send Email Msg

The user can send emails to the users (the message is sent to the address of the user instead of landing in his Inbox

UM Ignore Public Msg

The user can choose whether to ignore public messages or not

UM Refuse Private Msg

The user can choose whether to allow other users to send him private messages or not

UM Configure Plugin

The user can configure the plugin options

Pending Notifications

This panel does not allow you to configure the plugin but rather to see the status of the notification process. If you don't want to wait for the next scheduled execution (date and time are shown on the panel), you can launch the task manually. A batch of notifications will then be processed immediately.

About

This panel does not allow you to configure the plugin but shows useful information about how to stay informed about the plugin news, how to get support and how to suggest new ideas.

Back to the table of content

Custom Themes

The appearance of the user interface can be customized by using another theme than the one provided with the plugin. You can start with creating your own theme by following those steps. We will assume that your theme is located in the "wp-content/themes/sample-theme" directory

1. Copy the whole "default" directory located in the plugins "themes" directory to your theme's directory and rename it user-messages. You should now have a directory "wp-content/themes/sample-theme/user-messages"
2. In the WordPress administration panel, get to the "Settings" » "User Messages" page and select the "User Interface" tab.
3. Change the theme URL to reflect the new location of the theme directory. For example, it could be "http://www.your-site.com/wp-content/themes/sample-theme/user-messages" assuming your blog home page is "http://www.your-site.com/".
4. If the theme URL is correct, after saving the options you should still see a small icon next to the theme URL text box.
5. You can now start editing the icons and the CSS files, in particular "frontend-style.css" to change the user interface appearance.

Back to the table of content

Notification Process

Sending emails in large quantity can be problematic on hosted websites. Indeed, to avoid execution of spam scripts, many hosts impose limitations such as how many emails can be sent per hour from a script. In order to prevent hitting such a limitation, User Messages queues the notifications and processes them by batch every N minutes. You can see in the settings panel the notifications currently queued and the scheduled time for the next execution of the task.

If you notice that some emails do not reach the users, you can assume that this might be because you are being restricted by your host. You can try the following to send less notifications per hour/day.

• Decrease the "Notification Batch Size" parameter. A smaller number of notifications will be sent each time the task is executed. Use this if your host has restrictions on how many emails are sent in a very short time (few seconds).
• Increase the "Notification Task Interval" parameter. The task will then be executed less often. Use this if your host has restrictions on how many emails are sent in a longer period (emails per hour or per day).

If have many users and/or they send a lot of messages, it can be that the notification queue grows faster than it shrinks. If your host allows you to send many emails per hour/day, you can try the following to send more notifications per hour.

• Increase the "Notification Batch Size" parameter. A greater number of notifications will be sent each time the task is executed. Use this if your host has no restriction on how many emails are sent in a very short time (few seconds).
• Decrease the "Notification Task Interval" parameter. The task will then be executed more often. Use this if your host has no restriction on how many emails are sent in a longer period (emails per hour or per day). Be aware however that due to restrictions with WordPress, you should keep this number above 5 to 10 minutes depending on how much traffic is generated by your site.

Back to the table of content

Template Functions

Since version 2.3.0, if the widget is not enough, you can use some template functions to get some links in your template/theme. Here is how to make a list that will display the links available for your theme:

• <?php if ( function_exists( "um_the_folder_link" ) ) um_the_folder_link(); ?>
• <?php if ( function_exists( "um_the_new_messages_link" ) ) um_the_new_messages_link(); ?>
• <?php if ( function_exists( "um_the_send_message_link" ) ) um_the_send_message_link(); ?>
• <?php if ( function_exists( "um_the_send_email_link" ) ) um_the_send_email_link(); ?>

You can use these functions anywhere in your theme. You can refer to the file user-messages/view/frontend/TemplateFunctions.php to know more about the parameters of those functions.

Back to the table of content