Displaying the Box

Tutorials / A Sample App (Shout Box)

A Shout Box, aka Tag Board, aka Chatter Block, is a way to allow your web site users to leave a short message without having to register. I've heard them called a "new age guestbook", which I suppose describes them well enough. They are a simple application to write, making them a good candidate for an article such as this, which is intended mainly to introduce developers to Sitellite as an application development platform.

Please note that I don't go into full detail in some parts of this article, since other articles already cover topics such as writing boxes, the application layout, forms, and the Sitellite API documentation also already covers the functions used throughout this article.

What is a Shout Box?

A Shout Box consists of a list of comments left by visitors, followed by an input form visitors can use to leave new messages, including their name, a URL, and a message. Shout Boxes are compact, usually the perfect size for them to live in the sidebar of a web site.

Creating Our Shout Box Application

The first step to creating a Sitellite-based application is to create its directory structure. Inside the "inc/app" folder of your Sitellite installation, create a new sub-folder named "shoutbox" and inside that, create the following folders:

boxes	Contains most of our PHP scripts
forms	Contains any forms used by our app
html	Contains our user interface templates
install	Contains the installation files for our app, including our database schema
lib	Contains any PHP classes or functions used by our app

Creating Our Database Schema

CREATE TABLE shoutbox (
  id int not null auto_increment primary key,
  name char(48) not null,
  url char(128) not null,
  ip_address char(15) not null,
  posted_on datetime not null,
  message char(255) not null,
  index (posted_on)
);

Now go to the DB Manager in the Sitellite Control Panel (under the Tools pane in the top right of the screen) and enter the above SQL into the SQL Shell of the DB Manager. This will create the database table for us. Before we can even display our Shout Box, we'll need a way to create some entries. In the "forms" folder, create a sub-folder named "add". In that folder we'll be creating three files:

access.php	Contains the access permissions for our form
index.php	Contains the PHP code for our form
settings.php	Contains the form definition, from which the form will automatically be generated

sitellite_status = approved
sitellite_access = public
sitellite_action = on

<?php

class ShoutboxAddForm extends MailForm {
    function ShoutboxAddForm () {
        parent::MailForm (__FILE__);
    }
    function onSubmit ($vals) {
        db_execute (
            'insert into shoutbox
                (id, name, url, ip_address, posted_on, message)
            values
                (null, ?, ?, ?, now(), ?)',
            $vals['name'],
            $vals['url'],
            $_SERVER['REMOTE_ADDR'],
            $vals['message']
        );

        header ('Location: ' . $_SERVER['HTTP_REFERER']);
        exit;
    }
}

?>

[Form]

[name]

type = text
alt = Your Name

[url]

type = text
alt = URL

[message]

type = text
alt = Your Message

[submit_button]

type = submit
setValues = Submit

http://www.example.com/index/shoutbox-add-form

sitellite_status = approved
sitellite_access = public
sitellite_action = on

<?php

loader_import ('shoutbox.Filters');

$messages = db_fetch_array (
    'select * from shoutbox order by posted_on desc'
);

echo template_simple ('display.spt', $messages);

?>

<?php

loader_import ('saf.Date');

function shoutbox_filter_date ($date) {
    return Date::format ($date, 'M j, Y - g:i A');
}

?>

This defines the filter we'll use to format the posted_on date for displaying it.

<div class="shoutbox" style="height: 250px; overflow: auto">

{loop obj}
<p>
    <a href="{loop/url}">{loop/name}</a> says:<br />
    {loop/message}<br />
    <span class="shoutbox-date">
        {filter shoutbox_filter_date}{loop/posted_on}{end filter}
    </span>
</p>
{end loop}

</div>

{form shoutbox/add}

http://www.example.com/index/shoutbox-display-action

However, it's not very useful on its own screen like that. The last step will be to add it to one of your sidebars.