Location: PHPKode > scripts > Orca Ringmaker > orca-ringmaker/orm3/docs/readme.txt
************************************************************************
* Orca Ringmaker v3.0                                                  *
*  A comprehensive webring creation and management script in PHP/MySQL *
* Copyright (C) 2006 GreyWyvern                                        *
*                                                                      *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or    *
* (at your option) any later version.                                  *
*                                                                      *
* This program is distributed in the hope that it will be useful,      *
* but WITHOUT ANY WARRANTY; without even the implied warranty of       *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
* GNU General Public License for more details.                         *
*                                                                      *
* You should have received a copy of the GNU General Public License    *
* along with this program; if not, write to the Free Software          *
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 *
* USA                                                                  *
************************************************************************


*** Changelog
  - See "changelog.txt" for this script's complete revision history


*** FAQ
  - See "faq.txt" for this script's FAQ


*** Contents
 1. Script Requirements
 2. Introduction
   i. Changes from 2.x
 3. Installation
   i. Ensure you have all files
   ii. Edit config.ini.php
   iii. Upload the files
   iv. Activate the Ring
 4. Ring Configuration
   i. Ring Settings
   ii. PHPMailer
   iii. Statistics
   iv. Change Site Order
 5. Navigation Bar
 6. Levels and Statuses
   i. Account Level
   ii. Site Status
 7. Emailing Members
 8. Optional Files
   i. help.html
   ii. browsers.txt
   iii. captcha.php + fonts/
   iv. Themes


************************************************************************
************************************************************************
1. Script Requirements

PHP 4.2.0+
MySQL 3.23+


************************************************************************
************************************************************************
2. Introduction

  Welcome to the Orca Ringmaker script.  This script will allow you to
host and manage a full-featured webring from your site.

The Ringmaker has evolved from a simple backend-only webring script into
a highly refined GUI management system which makes a great addition to
an active community.  While it was designed to host just one ring at a
time, more rings can be supported by using different MySQL table
prefixes for each.

Version 3.x of this script takes to heart the philosophy that if a
navigation or menu item needs to be explained in detail to the user,
then that item is likely needlessly complex.  Pains have been taken to
ensure that members you promote to administrators need not read this
readme file before jumping into their duties.

*****      Please report any bugs to:  hide@address.com       *****

  i. Changes from 2.x

  For those users familiar with the 2.x version of this script, here is
a list of major design changes which you should know about:

    a) Sites and User accounts are now separate.  One user login can be
       the "owner" of multiple sites in the ring.

    b) The Administrator/Ring Owner account can have sites in the ring.
       Previously, this account was forced to be "site-less".

    c) Members promoted to Moderators - the level between Member and
       Ring Owner - now have access to the Ring Setup page

    d) The Controls column is no longer a templated file.  This option
       proved to be too complex for most users of the last version.

    e) Emphasis is put on selecting the HTML navigation bar distribution
       method, which is now the default.  Owners of large 2.x version
       rings often reported serious MySQL strain because of remote
       navigation bar requests.

    f) Addition of a "themes" CSS + images styling capability, and a new
       visual style.

    g) Sites cannot be switched back to Inactive status, only to
       Suspended and Hibernating.  The Inactive status is now reserved
       exclusively for sites which have not yet been activated for the
       first time.


************************************************************************
************************************************************************
3. Installation

  i. Ensure you have all files

  The following Orca Ringmaker files are required for the script to
function properly:

body.php       - Display (X)HTML interface output
config.ini.php - User variables file
config.php     - Global configuration file
head.php       - Accepts and processes incoming information
lang.txt       - Language file for interface
phpmailer.php  - Class for sending email to members
statistics.php - Statistics processing file
themes/grey/*  - Default "grey" theme

The default language file is English.  To use a different language file,
if available, name the file "lang.txt" and overwrite the existing text
file.  You may need to adjust the Character Set option in the Ring Setup
area as per instructions in the language file you are now using.  The
script will always look for a file named "lang.txt" in the same
directory in which the head.php file resides.

The script also comes with a variety of optional files, which will be
explained in further detail later in this manual.

  ii. Edit config.ini.php

  Before uploading, open the "config.ini.php" file.  There is a short
list of variables you need to assign manually in order for the script to
work on your server.

First, there are five variables under the MySQL header.  These variables
allow the script to access the MySQL database system on your server to
manage script data and store search indices.  If you don't know these
variables offhand, ask your host.

The first four variables will be specific to your server and MySQL
installation.  However, the fifth variable will be used as a prefix for
creating a number of tables in your database.  You can give this
variable any name you want, as long as it is only letters and numbers
and does not begin with a number.

Next, a number of functions such as automatically locating included
files require you specify which directory you will be uploading the main
script files into, relative to the public HTTP root of your website.  In
plain english, it just means the path to your Ringmaker files.  This is
"orm3" by default.

Once everything is the way you like it, you can save and close the
"config.ini.php" file.

  iii. Upload the files

  Create a directory in your public HTTP area to contain the search
script files. The default is "orm3" but you can specify any directory
you want, provided you change the include statements in any ring page
you create, and in the "config.ini.php" file, to point to the new
directory.

 ******************************** NOTE ********************************
 * For the purpose of convenience, the remainder of this manual will  *
 * assume you are using the default "orm3" directory!                 *
 **********************************************************************

Upload the following files into the "orm3" directory:
body.php
config.ini.php
config.php
head.php
lang.txt
phpmailer.php
statistics.php
themes/grey/[theme files]

Then upload the following file into the parent directory of "orm3":
_ringmaker.php

After you have uploaded all the files, your directory structure should
look like this:

/_ringmaker.php
/orm3/body.php
/orm3/config.ini.php
/orm3/config.php
/orm3/head.php
/orm3/lang.txt
/orm3/phpmailer.php
/orm3/statistics.php
/orm3/themes/grey/...

  iv. Activate the Ring

  When the above files have been uploaded, visit "_ringmaker.php" via
HTTP with your web browser.


************************************************************************
************************************************************************
4. Ring Configuration

  Upon activation, the Ringmaker script will automatically create an
"Administrator" login with password "password".  Using the login form in
the Controls column, log into the Admin account.

The login form will change to a menu with a number of administration
options.  Let's head to the main setup area first, which can be reached
via the Ring Setup link.

  i. Ring Settings

  From this area, you can change the name of your ring, the announcement
which appears at the top of the Controls column, the number of sites
which show per page on the ring hub and many more configuration options.
The Announcement field can accept HTML tags.

The Character Set option affects the page and email output character
set.  Change this value to match the language file you are using; the
default English language file works in both UTF-8 and ISO-8859-1.

If you have installed additional themes in the orm3/themes/ directory,
you can easily switch between them here as well.

  ii. PHPMailer

  The Orca Ringmaker sends out email at various times during
registration, site approval, and status modification.  Ring admins can
also use a form to send email to various members.  The script uses the
very robust PHPMailer class to send these messages and can do so using
one of three methods.

The default "mail()" method will send email using the normal PHP mail()
function.  This method will work for most PHP installations.  In some
cases, the server administrator may have locked down this particular
function, however.

The "Sendmail" method uses the "sendmail" binary common on most *NIX
installations of PHP.  If "mail()" doesn't work, there is a good chance
that "Sendmail" will work instead.

Finally, if you wish to send mail using a specific SMTP server, you can
use the "SMTP" option.  When selecting this option, you must at least
specify a server name; use "localhost" to mean "the server on which my
website is stored".  If your SMTP server requires a username and
password, type them in the fields provided.

  iii. Statistics

  The Orca Ringmaker has quite possibly the most detailed statistics
reporting of any other ring script or system out there.  You can set a
few basic options here.

Ring statistics are calculated in two stages: first the script reads the
raw log data which it stores for every Ringmaker link clicked and
distributes this data by hour for every site in the ring.  Next, the
distributed data is parsed to create tables and graphs.

When statistics Caching is enabled, the results of the first stage are
stored at regular intervals so this processor intensive step need only
be performed at hourly or daily intervals.  The script will cache hourly
by default.  Statistics caching is highly recommended except for rings
with very low traffic (< 1000 hits / eight weeks).

To report hourly statistics, you must localize the ring to a particular
time zone.  You can enter a time zone abbreviation and GMT offset here.

On the Statistics page, a list of the top sites for hits and clicks will
be displayed.  You can control how many sites are displayed in this list
using the Top # Sites field.  If your ring contains less than this many
sites, all sites will be listed in the table.

Make sure to hit the "Submit" button to save your changes!

   iv. Change Site Order

  One item you won't be able to see yet on the Ring Setup page, is the
Change Site Order dialogue.  It will appear once there are two or more
active sites in the ring.  This feature is useful for keeping things
fair when certain sites in your ring generate a lot more hits than
others.  There are many different ordering options available.

  It's a good idea to randomize your site order every now and then so
that sites which generate a lot of hits aren't only benefitting the next
site down the chain.  Or, if this doesn't matter so much to you, you can
order the sites by Site Title to make things look nice and neat.

  It is important to note that these reordering functions are
instantaneous only.  If you reorder your ring by Site Title and then a
new site gets added, that new site will be added in the first available
open ring slot, *not* inserted in alphabetical order.  You will need to
hit the Site Order function again to move new sites to the correct
positions.


************************************************************************
************************************************************************
5. Navigation Bar

  When a new member signs up his or her site for inclusion in the ring,
they will be given a snippet of code to place on their pages to show the
ring Navigation Bar.  You can change the code which gets served to new
sites using the interface at the bottom of the Ring Setup page.

The Orca Ringmaker can serve its navigation bar in two formats.  Using
the default HTML method, each member will get the full HTML code of the
bar.  Using the Javascript method, each member will get a small script
tag to place on their pages which will dynamically request the
navigation bar right from your site, much like the way WebRing
navigation bars work.

There are pros and cons to each method.  The HTML method is MUCH less
stressful on your server; however once you give out the code, and you
decide to update the bar with a new image or layout, each member will
have to change their code manually.  The Javascript method allows you
to change the layout and appearance of the navigation bar on all member
sites immediately, but can quickly become a strain on your server if
your ring grows even moderately large.  Additionally, once you select
either method, it may be very hard to switch all your members to the
other method, so care must be taken in the decision early on.

Unless you are certain your ring will remain small, I HIGHLY RECOMMEND
sticking with the default HTML distribution method.  I could tell you
horror stories of 50+ site rings of the 2.x version, using Javascript
distribution, which pretty much crippled even dedicated servers.  The
Javascript method is a convenience included for ringmasters who know
their rings will never exceed 10 or 15 sites.  If you think your ring
will eventually grow beyond this, I beg you, use the HTML distribution
method.

You will thank me later, trust me ;)

When composing your ring navigation bar, I suggest building the bar in
a separate text/html file and loading it into your favorite browser to
see how it looks.  Once you are happy with the way the bar appears,
paste the code into the Navigation Bar text area.

This text area accepts three double-underscore-delimited codes, which
are automatically replaced when served to ring members:

__ringname__  The name of the ring
__hubURI__    The URI to the ring hub
__id__        The ID of the site where this code should be placed

If you are using the Javascript distribution method, you can include a
short message to display - if the user browsing a member site has
javascript disabled - in the Javascript <noscript> Fallback text area.
This text area accepts the same codes as the text area above.


************************************************************************
************************************************************************
6. Levels and Statuses

  i. Account Level

  Levels are assigned on a per-account basis, and indicate what
abilities an account has been given.  As the first Administrator, you
have been assigned the Level of Ring Owner, which is the highest level
there is.  Only one account can be the Ring Owner, although the title
can be moved from account to account if you wish.

When a user first registers an account in your ring, they will be given
the level of ring Member.  To help you manage the ring, you may further
promote ring Members to ring Moderators.  A Moderator gains access to
the Ring Setup area, the Email members area, and adds the ability to
edit and delete Member level accounts and sites.  A rogue Moderator can
seriously damage your ring, so don't just promote anyone! :)  Stick
with people you can trust.

 The four levels and their priviledges are as follows:

    a) User - a visitor browsing the ring
       - No priviledges

    b) Member - a registered account in the ring
       - Can edit their own account information except for username
         and account level
       - Can delete their own account
       - Can edit information for sites the account owns
       - Can delete sites the account owns
       - Can add new sites to this account

    c) Moderator - a ring administrator
       - All the priviledges of a Member plus:
       - Can edit the account information - except changing account
         level - of any Member level account
       - Can delete any Member level account or sites owned by Member
         level accounts
       - Can add new sites and assign ownership to any account
       - Access to the Ring Setup area
       - Access to the Email Members area

    d) Ring Owner - the main administrator
       - All the priviledges of a Moderator plus:
       - Full control over all accounts and sites
       - Can give the Level of Ring Owner to any other account; this
         demotes the current Ring Owner to Moderator
       - Emails sent by the script will use the Ring Owner's email
         address as the From: address

  ii. Site Status

  Each site added to your ring will receive a status.  The beginning
status for new sites is Inactive, which means they are waiting for
administrator approval.  There are four different site statuses, as
explained below:

    a) Inactive
       - A newly added site, waiting to be approved

    b) Active
       - An approved site, an active link in the ring

    c) Hibernating
       - An approved site which has been temporarily removed from the
         ring by its owner.  The site owner can switch this status back
         to active at any time

    d) Suspended
       - An approved site which had been temporarily removed from the
         ring by an administrator.  Only an administrator of sufficient
         level can switch this status back to active


************************************************************************
************************************************************************
7. Emailing Members

  To make organizing your ring members easy, the Orca Ringmaker includes
an email form where you can send your own custom emails.  Both the Ring
Owner and Moderators have access to the Send Email area.

  To select recipients of your email, use the menus labelled Recipients
and Accounts.  When using the "Selected" Recipient grouping, you can
select multiple entries from the Accounts menu by holding down Ctrl and
clicking each entry in turn.

  When a message is sent, it will be stored and displayed in a menu
beneath the Compose Email dialogue.  This lets both Moderators and the
Ring Owner review past sent emails, who sent them, and who they were
sent to.  To prevent Moderator abuse, only the Ring Owner may delete
sent messages from the saved message database.


************************************************************************
************************************************************************
8. Optional Files

  To simplify the enabling of certain Ringmaker features, the script
will search for the following files.  If the files exist, the feature
will be automatically enabled, no GUI settings required!

  i. help.html

  In the 2.x versions of the Orca Ringmaker, the "Help" text link was
only displayed in the Controls column if both the Ring Setup option was
enabled, and the help file existed.  In version 3.x the mere presence of
the help.html file will enable the Help link.  Simply upload it to your
"orm3" directory.

You can edit the help text/html which appears by editing the help.html
file.  This file is included as-is; no contained PHP will be executed.

  ii. browsers.txt

  On the Statistics page, the Orca Ringmaker has the ability to show
statistics based on browser and robot user agents which follow your ring
links.  To display this information, just upload the browsers.txt file
to your "orm3" directory.  If statistics caching is enabled, you may
have to wait until the next cache update for the browser list to appear.

Once you enable this table, an option will appear on the Ring Setup page
to "Collapse Robots".  Checking this option will replace all robot user
agent listings to be grouped together into one generic "Robots" listing.
You may want to use this option if your ring recieves a lot of robot
traffic.

  iii. captcha.php + fonts/

  It's a cold hard fact that the Join Ring form sends an email when
filled out and submitted properly.  While this form cannot be exploited
to send spam, it is possible for an attacker to use the form to send out
many bogus "confirmation" emails to many unsuspecting addresses.  There
is then the possibility that one of these recipients may mistakenly
report this ring email as spam.

To help prevent this activity, you can enable a CAPTCHA verification
image addition to the Join Ring form simply by uploading the captcha.php
file and the "fonts" directory to your "orm3" directory.  The script
will automatically detect the presence of this file and create the
necessary MySQL table to activate this feature.

You can open captcha.php to edit the font used and the general size of
the CAPTCHA image generated.  The default font included with the Orca
Ringmaker is Day Roman, a free font from Apostrophic Labs.  You can get
more free fonts to use with the CAPTCHA script from http://dafont.com
or your favorite font site.

  iv. Themes

  The Orca Ringmaker supports visual themes!  To install a theme, just
upload the theme's folder into the theme/ directory.  The standard
Ringmaker package comes with four themes: blue, green, grey and red.

Once you upload more theme folders, the themes will become selectable
on the Ring Setup page.  Just change the value of the drop down menu and
hit Submit to change your Ringmaker theme!

END
Return current item: Orca Ringmaker