Monday, August 22, 2011

Making the "Web's best php shoutbox" even better for your Moodle site

In my last post, if you were observant enough, you would have noticed an interesting-looking block on the lower right-hand corner of my Moodle course page. That's the section with the red border. Today's post is about that intriguing block with the text "Whisper" inside it. At the end of this post, you will know how to install a profanity-filtered chat widget that can identify the post by it's poster's Moodle account firstname. The widget also shows who is currently online. Best of all, this chat widget is free to use! Two versions of this chat widget exist - one version that is tested and running on both Moodle 1.9.x AND Moodle 2.x; and one version (with avatars) that so far as of 1st September 2011, has only been tested on Moodle 1.9.x.

Figure 1. Check out the area shown in red border.

I. ShoutPro shoutbox

One the most useful feedback tools on my Moodle site is a little shoutbox by ShoutPro.

Figure 2. The ShoutPro logo

The standard ShoutPro (version 1.5.2) allows you to create a shoutbox on your website. It just needs PHP and stores the posts in a flat file.

II. ShoutBox for Moodle
To be honest, ShoutPro was not my first choice of chat widgets for my Moodle site. Moodle's Shoutbox was the first. Let me enlighten you with a little flashback. Eight months ago I was happily using the Shoutbox block for my Moodle 1.9.7 site.
Figure 3. I have fond memories of Shoutbox. Check out those avatars!
On my Moodle site, those days are now long gone.

I loved Shoutbox and it works fine with newly created Moodle 1.9.x sites. But my site was undergoing a state of flux with me installing any mod, block or filter that looked interesting or pedagogically valuable. So the next thing I knew was an install of Shoutbox would elicit lines of cryptic PHP error codes.

III. Downloading  ShoutPro 1.5.2
So for almost a year I was living without my beloved Shoutbox. It was then that I discovered ShoutPro 1.5.2 and I installed it with gutso. With nearly 34,000 downloads of its installation zip file, ShoutPro's tag line is "the web's best php shoutbox". I'm a believer. Here's a list of its features.

Figure 4. The ShoutPro website where you can try out the shoutbox on the left of the screen. 
You can download the original ShoutPro 1.5.2 zipfile from this website.

Figure 5. Clicking on the Help link on the widget brings this tags/icon/smilies list.
Use for fun, but best used with discretion. Meaning, it's easy to get carried away on this chat widget!

IV. The problem with vanilla ShoutPro
ShoutPro was not only useful, but very popular among my students. In fact it was a little bit too popular. I say "was" because my students were using it to post all kinds of fun (read: meaningless, at times just thrash-talking each other) text posts. The main reason for this was that it allowed them to be anonymous. The interface allowed anyone to create a fictitious username to post a message. Some of the cheekier ones even used variations of my name to post on the shoutbox. It soon became a distraction among my student during my Computer Lab classes. I love my students and want the best for them, but this was too much!

Figure 6. A typical ShoutPro shoutbox being used in a typical way when the user
can hide behind someone's username or even a make-believe username.

I was in a dilemma. Having lost the ability to add a Shoutbox block eons ago due to some diosyncrasy with my Moodle site, I had to depend on ShoutPro as a substitute to get text feedback from students who needed help. Never mind that others in the class were misusing (abusing?) it with mindless chatter, unfortunately the standard ShoutPro code allowed them to hide behind make-believe usernames. No way I could get mad at them for something that the technology allowed them to do. Notwithstanding the rule that you were supposed to pay attention to the lecturer in the computer lab, I allowed it and tolerated it simply because its main function was for my students to send feedback to me. Oh how I longed for a way to stop the fictitious usernames hiding.

V. Modifying ShoutPro for Moodle (making the Whisper widget)
Then soon came a time that I was determined to modify it - Moodlerise it actually. So on August 13th 2011, I finally found out how to modify it so that it automatically used your Moodle username. All thanks to this post by Brian Lowe on a forum. Whoa! This was it. I dove head-first into the ShoutPro code and followed Brian's instructions and code.

NOW, my students need not enter a separate username prior to a post. They can post their text directly, and lo an behold, the modified ShoutPro (I call it "Whisper") stamps their $USER->firstname in their post. In fact each shout, I mean whisper, on the ShoutPro is also date and time-stamped. I spent a lot of time figuring out how to date/time stamp a post in a concise format of Mon, 22.8.11, 11:42 PM.

VI. The effect of using the Whisper widget on your Moodle site
The net effect of these enhancements? The number of playful (meaningless jibes?) posts by my students fell by 95%. When in the past, the end of a 2-hour lecture would reveal to me about 40 playful posts, this time only one or two posts were made by some brave students.

Figure 7. The Whisper widget. Now it's less fun to use. Less whimsical posts. 
More seriousness = more learning?

How does one explain this phenomenon? Simple. The mask of anonymity is now removed. No more fictitious username to hide behind. Several hardworking students still use it as expected to ask meaningful questions. Ah, at last! A tool to give me serious feedback and to discourage playful, meaningless non-productive online chatter. Now, my wish and aim is for more students to use the modified shoutbox to give me more feedback or to pose questions about their assignments.

I think my students were bored to tears with my voice, mind maps and PowerPoint presentations. Reflecting on the situation, maybe engaging students has more to do with the teacher than with flashy, snazzy and cool Moodle gadgetry. As teachers, we should not over-rely on technology because technology will make a poor teacher look worse in the classroom. I think I should get a pointer or two from Art Lader who decided to go on a Moodle fast. He choose to use Moodle-out-of-the-box in his classes. In the hands of a skilled, creative and inspired teacher, Moodle-out-of-the-box, without any third-party modules or blocks, should be enough. Do you agree with this, or is this a debatable point? Hmm.

So, my Whisper widget now fits nicely on the left of my Moodle courepage as a HTML block.

VII. Showing current online users on the Whisper widget
The modified Whisperbox also shows the current online students, as a name list just above the Whisperbox input textarea. A nice touch when you have a few students online. It could be a pain if your class has about 100 students! No chance of that happening with me - my classes are around 10 to 25 students. If your class is more than 30 students, you can poke around the php code and remark or remove that part of the code.

Figure 8. The ShoutPro block is (I prefer to call it my Whisperbox block) is shown on the extreme right of the image.
Notice that the Moodle usernames are displayed without any image avatar of the user.
But that's okay. It ain't exactly the same as Shoutbox.

VIII. Test-drive the Whisperbox widget
For a working demo, please check out my production site at
Username: student
Password: moodle

XI. Configuring a Moodle HTML block
This is how I configured a Moodle HTML block to access my Whisperbox chat widget:

Figure 9. Setting up the Whisperbox widget in a HTML block.

The HTML code shown above is:
<iframe width="200" height="900" frameborder="0" src="../shout/whisperbox/shoutbox.php"></iframe>

X. Comprehensive Profanity filter
The problem with chat is that anyone, and I mean anyone, can type anything. So to keep the chat text clean and free from profanity, I have included a 263(!) profanity word list inside the Whisper widget. I used Ms Excel to produce the required text that can be recognised by the Whisper widget. I've done the work for you so any common profanity is replaced by asterisks. Even the first character of the swear word is asterisked-off. No, I'm not going to give you an example. This channel is rated G for General. Now, how about that for a child-safe and clean chat environment?

[Update, Monday 29th August 2011]
I have updated the profanaties.php file so that this time, the entire word is asterisked off. Download the zip file containing the original profanities.php file as well as the updated one from

Version B: NEW! (works and tested on Moodle 1.9.x. NOT tested on Moodle 2.x)
In this version, when you post a message in the chat widget, your moodle user avatar will be displayed!

Click on the download image below (zip file was last updated on 1/9/2011)! The zip file contains just the modified shoutbox.php. Just replace the original shoutbox.php of Version A, with this shoutbox.php file. Make sure you backup the shoutbox.php of Version A in case you need it in future.

Version C: EVEN NEWER! (works and tested on Moodle 1.9.x. NOT tested on Moodle 2.x)
In this version, when you post a message in the chat widget, your moodle user avatar will be displayed and the format of the text has been enhanced! The username is now in gray bold. The day/date/time stamp is smaller in size and is in gray color too. See the image below:

The message post appears before the username. I think it looks nicer. Just a matter of taste.

The PHP file contains the latest version of shoutpro.php with some enhancements over Version B. Not tested with Moodle 2.x, I'm afraid.

XII. Chmod Privileges
For information on chmod privileges, refer to the original ShoutPro installation documentation found inside the zip file. Please be mindful that my ShoutPro files on my Moodle site are kept in a subfolder named whisperbox. You can rename that subfolder into something else, for example myshout.

With regards to the download zip file that extracts to a folder structure of


Here are the chmod instructions (based on the original Shoutpro instructions)

  • If your web server is not running a variation of Unix or Linux, skip this step.
  • chmod-ing is a process that allows ShoutPro to edit the files in its directory. If you do not know how to chmod, try right clicking on a file on your web site through your FTP program. Look for "Permissions", "Attributes", "Properties", or something like that. If you see a window pop up with three rows of checkboxes (for Read, Write, and Execute) as well as three columns (for Owner / User, Group, and World / Public), then you're set.
  • chmod the whisperbox folder 777 (make it readable, writable, and executable by everyone).
  • chmod the folder "lists" inside the shoutbox folder 777 (make it readable, writable, and executable by everyone).
  • chmod the file "lists/names.php" 777
  • chmod the file "shouts.php" 777 

XIII. Folder structure of the Whisper widget
Here is the folder structure of the download zip file's files vis-a-vis the ShoutPro files. If you extract the downloaded zip file, it will create the shout folder and the whisperbox subfolder automatically. You should then proceed to FTP the shout folder to your moodle site's main moodle folder. I.e,

your moodle folder/shout/whisperbox

Hence, the code that accesses your moodle folder/config.php is found inside the file
your moodle folder
/shoutbox.php and it looks like this:


Feel free to dissect the code, modify it and to use if with great effect on your Moodle site. Version A of Whisperbox should work with Moodle 2.x as well. It is fully customisable and can be coded so that its colour scheme matches with your Moodle site's theme.

XIII. Some security issues and how I countered them
A few words on security.  In the original ShoutPro, you can save your username with a password so that others cannot use your same password and masquerade as you. That password info is found in the file \lists\names.php in encrypted form. In my download zip file, I have been careful to delete any user panel password information.

Also the config.php file contains this line of code:

$thepassword = "mysecretpassword"; //IMPORTANT!  Change this file to your password.
                                                                  //Otherwise anyone will be able to clear your shoutbox.

Just thought that you might want to know this.

XIV. Stopping hacker injected code in its tracks
But wait there's more! On the Net there is an article on ShoutPro's security vulnerability and how to hack ShoutPro. I won't tell you where the webpage is for fear of compromising other ShoutPro shoutboxes elsewhere. Basically, the hacker will "inject" some PH code into the chat window that starts with php system(...) commands that includes the codes. Once someone went to my site and injected code that had fopen(...), fwrite(...) and fclose(...) PHP code. That in effect inserts a file into my system. Scary. The solution is to counter such attempts with prophylactic (what's that word? Look it up a dictionary, man!) code of your own.
          On my site, I have since modified the ShoutPro code so that it will replace any PHP injected code with null values. So any (as far as I know) malicious PHP-like code gets stopped in its tracks before it gets ingested into my ShoutPro system. So no fear there. Now you get an idea what prophylactic code means. Heh.

XV. In summary
To summarise, this post has shown you how to install a child-safe and made-for-Moodle chat widget that you can setup in a Moodle block. It shows you who is online at any on time. The post is immediately identified by the user's Moodle account firstname. It comes with a comprehensive profanity word filter. The text version works on Moodle 1.9.x and Moodle 2.0. The avatar version has only been tested on Moodle 1.9.x. Its colours can be customised by editing the css files. This Whisperbox can be used mainly for your students to ask you questions and to provide you with feedback. The Moodle username identification and date/time stamp feature discourages nonsense posts and encourages students to engage with you on a proper and matured plane. What more can you ask for?

That's all for now. I hope that you have fun using my improved ShoutPro for Moodle shoutbox, i.e., Whisperbox. So go ahead, give it a try today and start "whispering.

FINALLY, the link at the bottom of the comments list will allow you to download the shout code in the form of a ziped file named If you set it up correctly on your Moodle site, it should look like this:

Until the next time, happy Moodling!
Frankie Kam


The ShoutPro Team
Main Staff:
Eric Hysen - Founder, Owner, Main Programmer
Chris Miller - Programmer
Ian aka mm3guy - Programmer, Mod Developer

Chase Sechrist - PHP and Security Assistance
René Maathuis - PHP Assistance
Alex Lo - PHP Assitance
Shane Spencer - JavaScript Assistance
To the guys above, if you are reading this, U want to say that YOU GUYS ROCK!


If you like this post or site
a small donation would be nice but would last only a day,
otherwise leaving a comment (or a compliment) below will last me a month!


  1. As of today, I have included a profanity-filter that asterisks out profanities from a 264-word list.

  2. Here is a modified version of the file profanities.php. The zip file contains 2 versions of the profanity list. The entire word is asterisked off (profanities.php), or all but the first letter is asterisked off (profanities.php_ori). Download it from:

  3. Yvonne of the Netherlands experienced a problem as she has a 6 hour difference between her local time and the moodle server she is using.
    To solve her problem, I had to squash a hidden (until now) bug in the shoutbox.php original code as follows:

    Go to shoutbox.php, line 193. Modify the code so that it becomes like this:

    Line 193: $date = substr($date,-18,8);
    Line 194: $date = str_replace (".0", ".", $date);
    Line 195: $date = str_replace (" 0", " ", $date);
    Line 196: $shout = $shout." (".$jd.", ".$date.", ".$time.")";

    Basically, just two changes to the code and you are home.
    (at line 193) Change 18 to 8
    (at line 196) Insert the code ", ".$time.
    You can go to this discussion forum to be super-clear:

    I've purposely set my config.php's
    $timeoffset = 6;
    and I've tested it on my Moodle site at
    USername: student
    Password: moodle

    Works for me. Just thought you might want to know this. Now this improved Shoutpro widget (Whisperbox) is perfect.

  4. I can't get it to work. Do I need to change permissions as per the ShoutPro 1.5.2 instructions? I get my site homepage appearing in the html shoutbox block, so I guess I've got the link address or folder hierarchy wrong.

    In your readme.txt there is no mention of any obligatory edits, so what could the problem be?

  5. I note also that in the readme.txt you write:

    the code that accesses yourMoodleFolder/config.php
    is found inside the file yourMoodleFolder/shout/whisperbox/index.php

    ... but there is no index.php file at this location.


  6. Hi David,

    Firstly, are you using Moodle 1.9.x or Moodle 2.x? I haven't tried it on Moodle 2.x yet, but if you are using Moodle 2.x, then you can go here to get more help from Nicholas and/or Yvonne (who said that it worked on her Moodle 2.1 site).

    Secondly, I assume you are talking about Version1? The zip file contains the complete set of files and works with Moodle 1.9.x and Moodle 2.x. Version2, consists of a modified shoutpro.php file which I have only tested on Moodle 1.9.x.

    Thirdly, yes you should follow the chmod instructions outlined in the website. The chmod instructions are also inside the documentation folder in the download zip file. Nicholas (in the forum mentioned above)has some experience with the chmods.

    SO SORRY for the confusion. Too many late nights and too many variants of this plugin. Yes there is NO index.php file. What I meant was that the file *shoutpro.php* (NOT index.php <-- bad typo) accesses the config.php file found in the moodlefolder, which in Moodle 1.9.x is two parent folders up. So somewhere inside the shoutpro.php file you will see the code:


    I specifically mentioned this because Moodle 2.x has a different folder structure, then you have to be mindful of the require_once code, to be sure that it access the config.php file with the correct path.

    Thanks for highlighting the error in the article. I've made the correction on this blog article in red.

    Also, the file include.php accesses the moodlefolder/shout/whisperbox/config.php file. It is this local config.php file inside the whisperbox folder that houses the $timeoffset setting and other settings.

    So there are two config.php files.

    Hope this helps you out. If you still can't get it to work, please let me know your version. And it might be good to also contact the other Moodlers who have got it to work on their sites.

  7. Hey Frankie,

    Thanks for getting back so quickly.

    I am using Moodle 2.0.2 and will follow up with Nicholas and Yvonne, as you suggest.

    Re. the chmods, there is a slight confusion: in the ShoutPro notes, they say to set the shoutbox folder to 777, but in your package, there is no shoutbox folder. I tried setting the shout folder and the whisperbox folders to 777 but to no effect.

    Re. the config.php files, I checked the path to the higher one (two levels up also in Moodle 2.x) and made the personalized changes to the local config.php.

    I'm sure the mistake is on my part, and it's probably a very simple oversight.

    I'll let you know how it goes.


  8. Hi David

    The installation instructions on ShoutPro notes refer to the original zip download from the website. THAT zip file extracts to a folder named shoutbox.

    In MY zip download file, the folder "shoutbox" has been renamed to "whisperbox". I actually use multiple copies of the system throughout my Moodle site, so for one course, the files are stored in mymoodlefolder/shout/dca-it. In another course, I use the files in mymoodlefolder/shout/whisperbox, etc.

    Hope it works out for you. ;-)

  9. Hey Frankie, you need to get your red pen out again.

    You wrote: What I meant was that the file *shoutpro.php* (NOT index.php <-- bad typo)

    I think you mean shoutbox.php NOT shoutpro.php

    I haven't fixed my own problem yet, but am optimistic :-)

  10. David, I took out a pink pen this time. From the way you are able to scrutinize details and identify things, you are not that far away from getting the WhisperBox to work on your site, I think.

  11. Just called Yvonne and she walked me through her install. Turns out that the two files that ShoutPro first suggests setting to chmod 666 actually have to be 777.

    Now it works!

  12. Hi David. Thanks for sharing what worked and what didn't. Glad it worked out for you. Hope you have fun using the WhisperBox.

    If you are feeling adventurous, please let me know if my Avatar-display Version B and/or Version C work for Moodle 2.x (I doubt it!). I don't have a Moodle 2.x site installed due to lack of server hard-disk space (strangely enough).

    My future enhancement for the WhisperBox is to enable a post to include images and Youtube video. It's in the works. I have prototypes of each, but they are really buggy (do not work all the time) and not wise to distribute them.

  13. Hi David

    I checked the documentation.
    It says:

    chmod the file "lists/names.php" 666 (make it readable and writable by everyone).
    IF problems arise chmod it *777* instead

    chmod the file "shouts.php" 666 (make it readable and writable by everyone).
    IF problems arise chmod it *777* instead


  14. I've now made the chmod instructions clearer. David, I hope the time you spent to get Whisperbox working was worth it.

  15. Frankie,
    You are a genius! I installed a commercial shoutbox on my Moodle site and within two days kids were impersonating each other and posting oddball comments. I took it off and immediately began looking around for an alternative when I found your blog. Eureka! Bingo, it works like a charm. Thank you SO MUCH for the great and detailed directions!

    -Tom Clauset

  16. Hi Tom
    I'm so happy it worked out for you! One thing this is true - kids are the SAME half-way around the globe. Haha..have fun and good 'luck' keeping a half-step ahead of them with all this technology stuff and all. Enjoy!

  17. Great stuff! Do you know of anything like this that is similar to Live Chat? I was looking more for a one teacher/one student live chat capability that is only active when the teacher is logged in. Similar to messaging but in real time.

  18. Shoot, the download zips above are not working. Any chance I could still get a copy for my 1.9 site ?

  19. Hi Test Blog. You're in luck!
    Here is the download link:
    Create a folder named shout inside your public_html folder. Extract the mis contents into a mis folder.
    You should have this structure:
    Hope this helps.

  20. Download link:


Ratings and Recommendations by outbrain