Private Messages Notifications

This tutorial is for designers of phpBB 3 styles. Before reading it you should be familiar with phpBB 3 template system and phpBB 3 templates.

In phpBB 3 there are several template variables that can be used to handle private messages in page header:

• S_NEW_PM. This flag is set when user has a new private message. It is intended to be used for one time notification only, so once user changes page it disappears. Value is ether "1" or "0".
  
• S_USER_NEW_PRIVMSG. This variable shows number of new private messages. Unlike S_NEW_PM it always shows number of new messages, not once.
  
• S_USER_UNREAD_PRIVMSG. This variable shows number of unread private messages. Private messages are treated as unread if they are unread, but not new to current session.
  
• PRIVATE_MESSAGE_INFO_UNREAD. This is a string that shows "X unread message(s)" (lang variables UNREAD_PM or UNREAD_PMS). It is empty if there are no unread messages.
  
• PRIVATE_MESSAGE_INFO: This is a string that shows private messages status. If there are no new messages it shows "0 new messages" (lang variable NO_NEW_PM). If there are new private messages it shows "X new message(s)" (lang variables NEW_PM or NEW_PMS)
  
• U_POPUP_PM / UA_POPUP_PM: url of private message notification popup. It is used in javascript that shows new pm notification. Difference between U_ and UA_ versions is &: in U_ its &, in UA_ its &
  
• U_PRIVATEMSGS: url to private messages ucp module.
  
• U_RETURN_INBOX / UA_RETURN_INBOX: urls to inbox in usercp pm module. Difference between U_ and UA_ versions is & in url: for for U_ its &amp, for UA_ its &
  
• S_DISPLAY_PM: set if private messages should be displayed.
  
• S_USER_PM_POPUP: set if pm popup should be displayed.
  

Those template variables are enough to handle all types of notifications and buttons.

Few examples:

Standard pm text

In overall_header.html in subSilver template in phpBB 3 beta there is this code:

First line <!-- IF not S_IS_BOT --> checks if user is a bot, second line <!-- IF S_USER_LOGGED_IN --> checks if user is logged in, then <!-- IF S_DISPLAY_PM --> checks if pm urls should be shown.

Code in proSilver template is much simplier:

It just shows text regardless of number of new/unread private messages.

Then there is private message text code.
<a href="{U_PRIVATEMSGS}"> is url to private messages module of user control panel.
Then there is a small icon and text "X new message(s)".
Then <!-- IF PRIVATE_MESSAGE_INFO_UNREAD --> checks if there are unread private messages and shows {PRIVATE_MESSAGE_INFO_UNREAD} if there are. Why use <!-- IF --> for it? Because of comma after <!-- IF -->. That comma wouldn't look good if {PRIVATE_MESSAGE_INFO_UNREAD} is empty.

Use different color for new/old pm notifications

Create 3 css classes:

• .pm-old - when there are no new private messages. most likely it will be same color as other links.
  
• .pm-new - when there are new private messages. something that user would immediately notice.
  
• .pm-unread - when there are unread private messages. something that user should notice.
  

Then in header code would be like this (modified code is highlighted):

Now that you know all variables and have seen few examples you should be able to create custom pm notification in your phpBB style.