##############################################################################
# Oneliner v1.1 (2000-07-19)                                                 #
# Copyright (c) Stefan Pettersson, stefpet@algonet.se                        #
# More information at http://www.stefan-pettersson.nu/scripts/               #
# Disclaimer: No guarantees are made, use this script at your own risk       #
##############################################################################

Oneliner is a kind of tiny message/chatboard. People may leave small messages
on your site which then can be seen by others. The 10 (your choice) last
entries are always displayed.

This package should include the following files:
    1. readme.txt             - Installation instructions, Copyright,
                                and more (this file)
    2. oneliner.pl            - Configure the top of this file
    3. index.html             - Example page for the oneliner
    4. archive.html           - Example page for the archive

##############################################################################

Oneliner is free to use as long as you provide a link back to the Oneliner
page somewhere near the oneliner on your site. See the index.html file in
this package for an example. Thanks! This is all I ask in return for you to
use this script for free...

##############################################################################

Features
========

    - Multiple content files
    - Archiving
    - Censoring
    - Spam protection
    - Very customizable look

Requirements
============

To be able to use Oneliner you must be able to install and run CGI-scripts
made with Perl on your webserver. You must also be able to use SSI (Server
Side Includes) in your html (or shtml) pages.

If you are unsure of any of this, ask your ISP/webhost or system
administrator.


Setting up Oneliner
===================

The first thing you must make sure, is that the first line in oneliner.pl
is pointing to Perl on your webserver. By default it is:

    #!/usr/bin/perl

This is usually correct, but if you get a strange error you know that this
might be the problem. Another common path is #!/usr/local/bin/perl, or,
just #!/bin/perl, however, your system administrator know about this.

Place the oneliner.pl file in the cgi-bin directory on your server (or where
CGI-scripts may be executed). If you're transfering the files via FTP, be
sure to use ASCII because otherwise the linefeeds will be wrong. Set the
file permissions of oneliner.pl:

    chmod 755 oneliner.pl

You may do this from the system prompt if you've got telnet access to the
server, otherwise you usually can do this thru your FTP-client.

In some cases it's also required that you use chmod 777 on the directory
where you choose to put the oneliner_incl.html file (which is written to by
Oneliner).

Now to the important part, how to get the oneliners on your webpage. The
scripts generates a file which consist of rows in a table (ie <TR>..</TR>).
This table part should then be included in a complete table head and foot
on a HTML page together with a form.

Because it's only the rows that is written to the file, it's very easy to
completely change to look of the output. You just change the HTML as usual.
Here is an example of how a oneliner may look like:

-- HTML START ----------------------------------------------------------------

<table cellpadding=1 cellspacing=0 border=0 bgcolor="#303030"><tr><td>
<table cellpadding=2 cellspacing=0 border=0 bgcolor="#000000">
<form action="/cgi-bin/oneliner.pl" method=POST>
<input type="hidden" name="file" value="default">
<tr bgcolor="#1a1a1a">
    <td colspan=3 align=center>
    <font face="tahoma, verdana, arial, geneva" size=1>
    <b>Oneliners</b>
    </font>
    </td>
</tr>
<!--#include virtual="oneliners_incl.html"-->
<tr bgcolor="#1a1a1a">
    <td colspan=3 valign="middle">
    <font face="tahoma, verdana, arial, geneva" size=1>
    msg: <input type="text" name="msg" maxlength=70 size=24
          style="font-family:tahoma,verdana;font-size:10px">
    who: <input type="text" name="who" maxlength=10 size=7
          style="font-family:tahoma,verdana;font-size:10px">
    <input type="submit" value="leave msg"
     style="font-family:tahoma,verdana;font-size:10px">
    </font>
    </td>
</tr>
</form>
</table>
</td></tr></table>
<p>

-- HTML END ------------------------------------------------------------------

The important part is the SSI statement:

     <!--#include virtual="oneliners_incl.html"-->

This line include the file with the messages. If you've specified any path
or changed filename (see below) you must make sure that this SSI includes
the correct file. If you've specified different files to save the messages
in, this line should be modified to include the file of your choice.

Note that some servers may be configured to only allow SSI in files ending
with the extension .shtml (instead of .html). In that case, simply rename
the .html file.

This example is the one in the index.html file which included in this
distribution. My suggestion is that you start making it work with that file,
and then begin to customize.

The HTML file for the archive is similar, except that the form itself where
a message is entered is removed.

Configuring Oneliner
====================

You must configure Oneliner before you can use it. All changes are made at
the top of the oneliner.pl file. Note that lines starting with a #-character
in the Perl file is comments which are there to help you. Here are the
following variables that you should change if they doesn't already fit your
system. A tip is to start out small with them minimum of changes and get that
to work first, and then do all the major tweaking you want.

    %files = (
        'another',  '../htdocs/scripts/oneliners_another_incl.html',
        'default',  '../htdocs/scripts/oneliners_incl.html'
    );
        This is the file(s) where the messages will be written to, these
        files are the ones that should be included into a table on the HTML
        page. It's important that you specify a valid path, the path is
        specific to your server and must be changed.

        The first string is the identifier, in this example "another" and
        "default", the second is the path. The reason you may specify more
        than one is because you may use the same script but have different
        content on different pages. Which content file that should be used is
        specified on the HTML page where the form is. Change the value of the
        following line to choose file:

            <input type="hidden" name="file" value="default">

        In this case you may change value to value="another" to use the other
        specified file. There is no limit how many files you may specify.

        If no file is specified in the form, or a path for it in the script.
        The default file will automatically be used.

        For those who wonders, it's for security reasons you may not directly
        specify the actual filename within the HTML form.


    Archiving
    ---------
    Archiving saves all entries in a file of it's own, this nice if you want
    to keep track of everything that have ever been said in the oneliner.
    Archiving works the same way as the normal content in the oneliner, except
    that nothing gets deleted. The archive may then be included on a separate
    page that may be linked from the main oneliner for reference, or simply be
    kept on a secret place if you don't want to make the archive public.

    $enable_archiving = 1;
        This is the line where you enable or disable the archiving feature.
        1 (one) enables it, and 0 (zero) disables.

    %archives = (
        'another',  '../htdocs/scripts/oneliners_another_archive_incl.html',
        'default',  '../htdocs/scripts/oneliners_archive_incl.html'
    );
        This is exactly like the %files part you specified (mentioned above)
        before. However, this is the location of the archive files. For each
        file in the %files section, a archive must also be specified.


    Censoring
    ---------
    With censoring enabled, a submitted entry will be checked to not contain
    any bad words (of your choice). If a bad word is found, it may either be
    scrambled and then accepted, or the user will be redirected to a new page,
    or simply nothing will happen (the entry is ignored).

    $enable_censor = 1;
        This is the line where you enable or disable the censoring feature.
        1 (one) enables it, and 0 (zero) disables.

    @badwords = (
        'shit',
        'piss off',
        'fuck'
    );
        This is where you specify the list of words considered "bad". I leave
        it to you to go crazy coming up with bad words to put in the list. :-)

    $enable_scrambling = 1;
        Enable (1) or disable (0) scrambling of bad words. Scrambling means
        that a bad word is replaced by a string of your choice, and then
        submitted to the oneliner. This way entries with bad words isn't
        rejected, instead just the bad word is replaced.

    $scramble_string = '<font color="#ff0000">&lt;censored&gt;</font>';
        The string that will replace and detected bad words. This may simply
        be a star '*' or something more extensive like the HTML in the
        example. The example replaces all bad words with the string
        '<censored>' in red.

    $enable_censor_redirection = 0;
        Enable (1) or disable (0) redirection to another page when a bad word
        is detected. When censor redirection is enabled, scrambling is ignored
        (because the entry is never saved).

    $censor_url = 'http://www.yourserver.com/bad_language.html';
        Here you specify which page the user should be redirected to when a
        bad word is found. This may preferable be a page telling the user
        about the use of bad language and that it's not accepted on your site.

    Note that if not scrambling or redirection is enabled (both are disabled)
    but censoring is enabled, then an entry with a bad word will simply return
    the user to the page with the oneliner and the entry will not be saved.


    Spam protection
    ---------------
    Spam protection is a feature to prevent the same user to post multiple
    entries in a row (i.e. spamming the oneliner). This is usually done by
    someone who want's to abuse the oneliner. Spam protection saves the
    user's IP-adress and the time the entry was made. If the user tries to
    submit another entry within a certain amount of time, without another
    user making an entry in between, it's considered spam.

    $enable_spamprotection = 1;
        Enable spam protection (1 = enabled, 0 = disabled).

    $spamcheck_filename = 'oneliner_spamcheck.txt';
        This is the filename where the IP-adress and time is saved. This
        filename usually doesn't need to be changed. By default it's saved
        in the same directory as the Perl script.

    $spam_timelimit = 3600;
        Timelimit for what is considered spamming. That means the time
        that must have passwed between two entries from the same IP-adress.
        The value is in seconds (example is 1 hour = 3600 seconds).

    $enable_spam_redirection = 1;
        Enable redirection to another URL if spam is detected. 1 = enabled,
        0 = disabled. If spam is detected, the user will be redirected to
        another page instead of going directly back to the oneliner.

    $spam_url = 'http://www.yourserver.com/you_spam_shame_on_you.html';
        Here you specify which page the user should be redirected to when spam
        is detected. This may preferable be a page telling the user about the
        policy of your site and explaining what spamming is and why the users
        entry is considered spamming.

    Note that a user is detected by it's IP-adress. That means that users
    behind a firewall will be considered as a single user because they all
    just have one public IP-adress visible from the Internet. If you will have
    users behind a firewall (for example if you're using the Oneliner on an
    Intranet) you probably want to disable spam protection.


    Customize look
    --------------
    This is the part where you may change how an entry in the oneliner will
    look like.

    $number_of_rows = 20;
        Number of messages that should be displayed at the same time. When
        the message count exceeds this value, the last one will be dropped
        when new messages are entered.

    $dateformat = '[monthname] [day] [year], [hour0]:[min0] [ampm]';
        You may change the look of the date and time when it's displayed
        in a news posting. You do this by using some special tags that
        will be replaced with a value. The following tags are available:

        [sec]            = seconds
        [sec0]           = seconds padded with a 0

        [min]            = minutes
        [min0]           = minutes padded with a 0

        [hour]           = hours (12h)
        [hour0]          = hours (22h) padded with a 0

        [hour24]         = hours (24h)
        [hour240]        = hours (24h) padded with a 0

        [ampm]           = display am or pm

        [day]            = day in month
        [day0]           = day in month padded with a 0

        [dayname]        = name of weekday
        [daynameshort]   = name of weekday short

        [month]          = month
        [month0]         = month padded with a 0
        [monthname]      = name of month
        [monthnameshort] = name of month short

        [year]           = year (4 digits)
        [shortyear]      = year (2 digits)

        Examples:
            Format: '[monthnameshort] [day], [hour0]:[min0] [ampm]'
            Result: Jan 26, 10:32 pm

            Format: 'Posted [hour240]:[min0]:[sec0] [year]-[month0]-[day0]'
            Result: Posted 22:32:28 2000-01-26

    @daynames = qw(Sunday Monday Tuesday Wednesday Thursday Friday
                   Saturday);
        The names that will be used for each weekday is specified here
        with a space between each name. You might want to exchange these
        with the names in your language for example.

    @monthnames = qw(January February March April May June July August
                     September October November December);
        The names that will be used for each month is specified here with
        a space between each name.

    $bgcolor   = '#000000';
        Background color of the entered messages, specified in hex as in HTML.
        Example: #FF0000 is red, #707070 is grey, #0000FF is blue.

    $font_date = '<font face="tahoma, verdana" size=1 color="#4FE59D">';
        Font tag that will be used for the date. This is a regular HTML <font>
        tag.

    $font_msg  = '<font face="tahoma, verdana" size=1 color="#EFEF80">';
        Same as above but for the actual message.

    $font_who  = '<font face="tahoma, verdana" size=1 color="#EF80EF">';
        Same as above but for the nickname.


Customization
=============

The look of the oneliner may be customized by you. The HTML page where the
oneliner_incl.html file is included may look anyway you want, as far as it's
a correct table that the file is included into.

It's recommended that you first use the default exampe, get it to work, and
then modify it as you please.


What To Do If You Can't Get It To Work
======================================

Unfortunately I'm not able to support you in any way. Simply read these
instructions again and check the Oneliner webpage for Frequently Asked
Questions which might help you, there is also a general tutorial for
installing CGI-script that might be of use if you have no or little
experience in installing CGI-scripts. You may also check out the forum to
see if your question is answered there. If not, you may post a message and
hopefully someone helpful will respond. Another option is to ask your ISP
or webhost and to check their support pages.

The reason why I can't help you is that I would probably get swamped by
mails and unfortunately I haven't got the time to answer them all. So
please DON'T mail me asking for help, instead enter your question in the
forum and either I or someone else will answer. Thanks for understanding.

Oneliner homepage:

    http://www.stefan-pettersson.nu/scripts/oneliner/


Version History
===============

v1.1  - 2000-07-19
    - Added archiving, censoring and spam protection

v1.0  - 2000-07-06
    - Added support for multiple files

v0.9  - 2000-01-26
    - Initial public beta version
