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!

Ratings and Recommendations by outbrain