YShout: A Free PHP + AJAX Shoutbox

YShout is a lightweight package that allows you to easily add a shoutbox to your website. YShout is also completely free of charge, and since it's licenced under the Creative Commons Attribution 2.5 License, you can modify it to your heart's content and use it on any commercial or noncommercial website. YShout outputs proper XHTML, […]

YShout is a lightweight package that allows you to easily add a shoutbox to your website.

  • YShout is also completely free of charge, and since it's licenced under the Creative Commons Attribution 2.5 License, you can modify it to your heart's content and use it on any commercial or noncommercial website.
  • YShout outputs proper XHTML, and is styled with valid (and completely customizeable) CSS.
  • YShout is also non-intrusive, so you can stop worrying about ruining your perfect markup.
  • YShout is fully styleable via CSS, so you can tailor its look to fit your website perfectly. It also comes with configurable options, so you can mold YShout to your needs.

I requires PHP4 or above to function properly and doesn't use a database, instead logging shouts to flat text files.

How do I install it?

First off, make sure you have YShout downloaded and unarchived.

Part 1: Setup

  1. Upload the "yshout" directory to your server. Chmod it and all items inside the folder to 777.
  2. YShout is dependent on Prototype, so add the following code to your header: <script src="yshout/js/prototype.js" type="text/javascript"></script><script src="yshout/js/yshout.js" type="text/javascript"></script>
  3. YShout's look is defined through CSS, so add the following code to your header: <link href="yshout/css/yshout.css" type="text/css" rel="stylesheet">
  4. Add the below line into your page's source code where you want YShout to load:
     
    <div id="yshout"></div>
  5. Now you just need to add the Javascript to initialize YShout upon the page's load. Add this at the bottom of your HTML file, just before the closing body tag: <script type="text/javascript">loadYShout();</script>

That's it! You're done! You've just completed the basic setup, and you have a fully functional YShout install. Here's some stuff you should know:

  • Administration. After being logged in (/login [password]), click the nickname of the user to see information about them. The default password is fortytwo.
  • Commands. YShout features user commands to make your life as an admin easier. Type /help to get a list of commands.
  • History. To view the chat's history, just go to http://example.com/path/to/yshout.php?history, replacing the URL with the path to your yshout.php.
If you're looking to customize YShout a bit further, continue reading below.

Part 2: Customizing YShout

There are numerous aspects of YShout you can tweak, including various options and the look.
  • Server-side. On the server side, there are a couple of options you can tweak, right up at the top of yshout.php.
     $prefs = array ( 'adminPassword' =&gt; 'food', 'shoutMaxLines' =&gt; 15, 'logMaxLines' =&gt; 200, 'curseFilter' =&gt; false, 'floodTimeout' =&gt; 2500, 'refreshInterval' =&gt; 5000, 'showTimestamps' =&gt; true ); 
    • adminPassword: The password to login and administrate the shoutbox.
    • shoutMaxLines: The maximum amount of shouts shown at once; older shouts are truncated.
    • logMaxLines: The maximum amount of shouts in the log; older shouts are truncated.
    • curseFilter: If true, replaces those damn **** curses wth asterisks.
    • floodTimeout: The amount of time (in milliseconds) flood control is enabled.
    • refreshInterval: The amount of time (in milliseconds) between shoutbox refreshes.
    • showTimestamps: If true, timestamps are shown next to messages.
  • Client-side. YShout boasts a few client-side configurable options as well. All of them are called through the loadYShout() function.
     loadYShout({ yPath: 'yshout/', fileIndex: 1 }); }); 
    • yPath: Allows you to use YShout in other directories. Just set yPath to a relative path to the yshout directory. Defaults to '/yshout'.
    • fileIndex: Allows you to use different shoutboxes on different pages. Just set a different index on each page, but make sure to specify filenames in yshout.php, as demonstrated below:
       $logFiles = array ( 1 =&gt; 'main.txt', 2 =&gt; 'second.txt' ); 
  • CSS: YShout is fully styleable through CSS; take a look at the default stylesheet to get an idea of how much control you have over the design. The class names are self-explanatory, so you shouldn't have any trouble figuring out what is what. Have fun!

YShout, Shoutbox