mailbox Follow @yiiframework

Features ¶

• Enable/disable user-to-user messaging, Ie. disable to make simple customer support messaging between admin/users only.
• Enable/Disable Inbox/Sent/Trash
• Works with Yii-User / Rights modules
• Custom themes / multiple layouts
• Enable/disable trashcan/recycling
• Enable/disable dragndrop trash
• Enable/disable users can see when recipient reads their message.
• Html Purify Admin/User input separately
• Create site news plugin using publicly accessible mailbox

To Do ¶

I will try to get these features working within a few days...

• CC Your newsletter etc to local mailbox using templates

Notes ¶

I am currently developing this module as part of another project. As the project progresses I will continue to update this extension. So please be warned that right now this module is still being developed and unknown bugs/issues may exists. Once all the features have been implemented I will do more extensive bug/browser compatibility checks and hopefully have a stable release candidate for v1.0. So if you decide to use this module in your project it's recommended that you follow this extension for updates until I get a stable version released (ie. v1.0).

Requirements ¶

Yii 1.1 or above

Browser Requirements ¶

This module uses Javascript for some of it's features, however, you do not need Javascript enabled to use this module. All features in this module using Javascript should degrade gracefully.

The only known compatibility issues so far are in the HTML/CSS.

• FF 3+
• IE 5.5+
• Chrome 1+
• Safari 4+
• Minefield 3+
• Flock 2+
• Seamonkey 2+
• Konqueror 3+
• Epiphany 2+
• Iceape 2+
• Iceweasal 3.5+

I have also tested this module on Netscape 10 and Opera 9 but could not find older versions to test. I will get all browsers to display properly before releasing v1.0.

Usage ¶

Unzip to modules directory.
Install data/structure.sql

If you want to alter the table names edit the following lines in MailboxModule.php

const TBL_CONV = '{{mailbox_conversation}}';
    const TBL_MSG = '{{mailbox_message}}';

Add Module ¶

Add the module inside your main config file.

return array( 
...
'modules'=array(
...
'mailbox'=>
    array(  
    'userClass' => 'User',
    'userIdColumn' => 'id',
    'usernameColumn' =>  'username',
        ....more options here....
      ),
    ...
);

Module Options ¶

Full list of module config options.

• NOTE: The following options do not have an affect if you are using an authManager such as Rights. In this case the authManager will control the access.
  • sendMsgs
  • sentbox
  • trashbox
• userClass - the name of the user model class.
• userIdColumn - the name of the id column in the user table.
• usernameColumn - the name of the username column in the user table.
• superuserColumn - the name of the column in your User model that defines whether user is an admin or not.
• deletedUser - text to display if user not found.
• pageSize - number of conversations to display per page.
• authManager - if you want to use an authManager (such as the Rights module) to control the access rules then set to true, if your using the Rights module specifically set to 'rights' in order to include the Rights filter.
• readOnly - enable a read-only mailbox for regular users. Admins will still have fully functional mailbox.
• userToUser - whether to allow user's to message other users. False would means users can only contact admins.
• sendMsgs - whether or not to allow users to send messages.
• sentbox - whether or not to enable/disable sent folder for viewing sent messages.
• trashbox - whether or not to enable/disable trash folder for recycling deleted messages. If trashbox is enabled then you must run the cron() method at least once daily, ideally after midnight or each morning.
• recyclePeriod - number of days to keep deleted items in trash folder before being permanently deleted by the cron() method.
• dragDelete - enable/disable drag-n-drop deleting.
• confirmDelete - wether to ask the user for confirmation before deleting messages. Note that if trashbox is turned off, values of 1 and 2 have the same effect (since messages are always deleted permanently).
  • 0 - Never ask for user confirmation.
  • 1 - Ask for user confirmation, but only when deleting permanently.
  • 2 - Ask for user confirmation when moving messages to trash, and when deleting permanently (ie. deleting from trash).
• recipientRead - whether to allow users, when viewing the sent folder, to see if recipient has read the sent message.
• cssFile - set to custom css file location relative to base URL or set to false to skip css includes.
• menuPosition - set to either 'left' or 'top' to position the mailbox menu. If readOnly set to true this is ignored for user and only applied for admins (since there is no menu in readOnly mode).
• cssFileColumn - custom left menu css.
• juiThemes - apply jQuery UI widget styles. Can be one of the following:
  • 'none' Don't add any jQuery UI themes.
  • 'basic' Add themes to buttons and some elements but keep the background/font color of the parent element. Ie. <body> or #content
  • 'widget' Full jQuery UI styling.
• juiButtons - enable/disable the JUI themes for buttons. Eg. if you want to use Twitter Bootstrap buttons instead.
• juiIcons - whether to add icons to menu buttons (only if juiButtons is enabled)
• defaultSubject - default subject to use when no subject is provided.
• allowableCharsSubject - list of allowable characters to check Subject field against using case-insensitive regular expression. Square brackets '[]', dashes, single quotes, and slashes need to be escaped in order to be used literally.
• adminHtml - HTML Purify options array used to purify HTML input from admins. See http://htmlpurifier.org/live/configdoc/plain.html for list of options. Set to an empty string to strip all HTML tags from message input.
• html - HTML Purify options array used to purify HTML input from non-admins. See http://htmlpurifier.org/live/configdoc/plain.html for list of options. Set to an empty string to strip all HTML tags from message input.
• allowLookupById - whether to allow users to be able to enter user Id's instead of username when sending messages.
• allowUsernameSearch - whether to allow users to be able to search list of usernames to contact when sending messages.
• editToField - whether to allow users to be able to edit the To field when sending messages.
• userSupportList - whether to create a drop down menu for the To field ( from array created by getUserSupportList() method). This attribute is always true for admins unless the getUserSupportList() method returns false.
• linkUser - whether to create a link for the From field to user's profile etc (link created by getUrl() method). This attribute is always true for admins unless the getUrl() method returns false.
• checksums - whether to use checksums when storing messages. Checksums can be used not only for validating data but also to help implement certain spam protection. Eg. if a user copy and paste a message and sends it to multiple users you can easily find these messages by searching for other messages with the same checksum.
• alternateRows - whether to alternate the row colors when viewing message list (ie. inbox etc).
• newsUserId - the Id of the user account used for the site news.

Define Wrapper Functions ¶

Edit the following functions in the file /module/mailbox/MailboxModule.php

*Note if you are using the User module from Yii extensions (Yii-User) then you do not need to configure the following functions. Unless if you'd like to customize the From label or modify how the auto complete is handled.

getUserId($username='')
getUserName($userid='')
getFromLabel($userid)
getUrl($userid)
isAdmin($userid='')

autoComplete($term)

/**
     * Lookup user id by username. If no username supplied return current user id.
     * 
     * @param string $username
     * @return integer user Id that belongs to $username
     */
    public function getUserId($username='') { ... }
    /**
     * Lookup user id by username. If no user id is supplied return current user's username.
     * @param integer $userid
     * @return string username belonging to $userid
     */
    public function getUserName($userid=0) { ... }
    /**
     * Build the label for the From field when viewing the message. Ie. use the userid input to create a string like 'Username', 'Username "First Last"', '<div> ... </div>' , etc
     * @param type $userid
     * @return string label used for From field
     */
    public function getFromLabel($userid) { ... }
    /**
     * 
     * @param integer $userid
     * @return string url to users profile page etc. 
     */
    public function getUrl($userid) { ... }
    /**
     * Check whether given userid belongs to an administrator. If no userid is supplied check whether the current user is an administrator.
     * @return boolean 
     */
    public function isAdmin($userid=0) { ... }
 
    /**
    * Autocomplete function for 'To' field in view/compose. Search for usernames etc that match the string.
    *  
    * @param string $term
    * #return array output json array of usernames and labels.
    */
    public function autoComplete($term) { ... }
 
 
    /**
     * If the config var userSupport is enabled then the module will use this method to
     * create a drop down list of contacts in the To field when the user is creating a 
     * new message. This script should return an array, with keys set to the username 
     * and the value set to the username's label (may be the same). If userToUser messaging 
     * is enabled then this will create a drop down along with regular user input. If 
     * userToUser is disabled then the users will only be able to select contacts from this list.
     * 
     * Tip: If using an authManager you could create a new role called "support" and use 
     * this method to fetch an array of users who are assigned to the "support" role.
     * 
     * @return array array of admin usernames who provide customer support
     */
    public function getUserSupportList() { ... }

Cronjob ¶

Add the following to your PHP cron script...

MailboxModule::cron();

Site News ¶

To setup the site news plugin first create a new user in your database. Add the news user's Id to the module config...

return array( 
...
'modules'=array(
...
'mailbox'=>
    array(
        ...
    'newsUserId' => the news user Id here,
        ...
      ),
    ...
);

You can now create news updates by messaging the site news user (admins only). The site news user can also be added to a drop down list for the admins in the getUserSupportList() method. When you message the news user the subject and message will be publicly viewable via mailbox/news.

Change Log ¶

0.2.1 ¶

• Fixed CSS/display issues
• Browser compatibility testing (display only)

0.2 ¶

• Reorganized module - Changed all config variables to be regular class properties (ie. not static vars) so that they can now be set in the config array.
• Added JUI widget styling
• Added basic site news feature (still in development)
• Added qTip 2 for tooltips and growls (may also be used for other features in the future ie. calendar etc.)
• Added more options to module config
• Added user support list - dropdown/combobox that lets user select from a predefined list of user's to contact.
• Fixed one major bug/issue - In previous version all messages would be deleted when conversation was destroyed.

0.1 ¶

• Initial public release

Bug Fixes ¶

If you are using v0.1 please change line 473 in models/Mailbox.php from this...

$msg_count=Message::model()->conversation($this->conversation_id)->deleteAll();

to this..

$msg_count=Message::model()->deleteAll('conversation_id=:cid',array(':cid'=>$this->conversation_id));

Resources ¶

View Demo