Web Cash

Here’s the quick and dirty introduction to the Shoutbox class. You’ll find everything you need to know to implement this Shoutbox on your website and style it to your liking.

How Is the Data Stored?

In the initial release of Shoutbox, all of the data is stored in a specially formatted xml file. The tar.gz archive comes with a prepared blank xml file for you. If you delete it and need to start over, here’s what should be in the blank file…

<?xml version="1.0"?>
<messages>
</messages>

By default, this file should be named “shoutbox.xml” and be saved in the same directory where the script is executed from. Alternatively, you could provide your own file name and path to the Shoutbox class when you create it (see the later section on the php code you need to insert into your page).

Where Do the Files Go?

The source code you downloaded should have had four files in it – shoutbox.php, xmlshoutbox.php, shoutbox.css, and shoutbox.xml.

Shoutbox.php defines the parent class, while xmlshoutbox.php defines the child class specifically for using xml as a storage device. Shoutbox.xml is the actual storage file. By default, all three of these files should be in the same directory, but you can change that with a little customization.

Shoutbox.css defines the basic style for the shoutbox. You can place this in your css directory and link it to your site, or simply re-declare the ids and classes in your standard css stylesheet.

The PHP Code You Need to Insert to Use Shoutbox

Now, let’s take a look at how you can get this working on your website. In the current version, you’ll need three basic php statements

$shoutbox = new xmlshoutbox();

This statement creates the actual shoutbox class – $shoutbox. By default, this will create the class by looking for “shoutbox.xml.” If you want to use a different file, pass that filename to the class’s constructor like this…

$shoutbox = new xmlshoutbox( $filename );

Next, you need to see if a new message was sent to the script to be added to the shoutbox. This second line of code checks for updates.

$shoutbox->update($_POST);

Finally, you need to actually output the shoutbox. This final line of code calls a method to output the Shoutbox and the message form. It physically outputs the information (rather than returning it as a string or array), so place this in your template where you want the shoutbox to appear.

$shoutbox->output();

Finally, you need to include the class declaration files (shoutbox.php and xmlshoutbox.php) in your project. You could include these in your general config or common include file. Alternatively, you can use an autoload function, like this…

function __autoload($class) {
	require_once("$class.php");
}

Place that in your common include file and change “$class.php” to include the path to your class files. This will autoload the files if and when the classes are actually used.

Styling the Shoutbox to Match Your Site

One of the things I love about this shoutbox is it is simple to style. It uses clear, concise html that allows you to easily alter any element of the shoutbox to fit into your site’s template.

If you look in the provided css stylesheet (shoutbox.css), you’ll see the basic styles as they’re defined. At the moment, you need to go into the source code to change the html elements and styles (read the developer’s documentation, and then look at the parent constructor).

Here’s the basic css information you need to know…

• #shoutbox-list – this is the id of the first <ul> that surrounds the actual shoutbox
• .message – the class assigned to the message’s <li>
• .author – the class assigned to the author’s <li>
• .pubDate – the class assigned to the <li> for the message’s date and time
• #shoutbox-form – the id for the <ul> that holds the input form
• .class, .textarea, .label, .authInput, and .submit – the classes assigned to the individual <li> elements that hold the form elements

As you can see, everything is broken down into individual <li> elements with appropriately named classes. This makes it easy for you to style each element of the shoutbox the way you want.

Go To It. Implement and Experiment

That should get you off the ground with the current version. I anticipate making some changes soon to add some more functionality – so if you have any feedback or requests be sure to leave a comment somewhere on the documentation pages.

If you want to delve deeper, head to the next page – Inside the Shoutbox Class Source Code (coming soon).

• 1. Shoutbox: Homepage
• 2. Shoutbox: Front End Docs (You’re Here!)
• 3. Shoutbox: Developer’s Docs (Coming Soon!)