
***************************************************************************
                         JMK Advertisement Rotator
                            -------------------
   begin                : Somewhere in time
   copyright            : (C) 2001 by Dimitris Batis
   email                : bat_geor@mail.hol.gr
***************************************************************************

	TABLE OF CONTENTS:

	1. What is JMK Advertisement Rotator?
	2. Features
	3. Availability
	4. System Requirements
	5. Installing and using
		5.1 The Administration
		5.2 Rotating banners
		5.3 Client statistics
	6. License
	7. Credits
	8. Authors & Contact information

===========================================================================

1. What is JMK Advertisement Rotator?
-------------------------------------
JMK Advertisement Rotator is as much as the title suggests. It is a script
that can manage and display advertising banners, sort them into groups and
automaticly expire them after a date, a number of displays or clicks has
passed.

2. Features
-----------
 - Easy installation
 - Rotates banners in order, not randomly
 - Clients can view their banner statistics
 - Automatic banner expiration
 - Rotates images or any other code
 - Groups images --> can have many different rotations within the web site
 - Does not need SSI
 - It is GPLd, so you can re-distribute it and modify it in any way

3. Availability
---------------
You can find information and download JMK Advertisement Rotator from the
following Web site:

http://www.ravencrypt.com/scripts/

4. System Requirements
----------------------
First of all, your web server must support PHP version 4.0 or greater. It
will probably work with PHP 3.0 as well, if you predefine the functions used.

A MySQL database is a must, version 3.22 or greater (the latest release is
highly suggested, as many features are under construction).

The pages from which the script can be called must also be of PHP mime-type
(e.g. .php). If called from .php3, you must alter the JMK Ads code so that
all functions are predefined.

If you want to call it from plain html files, you must change their mime-type
to application/x-httpd-php (in Apache, add an AddHander in a .htacccess file).

5. Installing and using
-----------------------
The installation is done by ad_installer.php. Open the file in your web browser
and read the instructions. All you have to do is change a few variables in
ad_config.php.

If the script is called from many different directories (which can mess up
the require() statements), it is suggested that you put the full path in
the require() statements at the start of each file, and especially in ad.php
and ad_click.php.

After the installation, you can go to ad_admin.php, login and start working.

5.1. The Administration
-----------------------
The contents page explains its usage, so we will just add a few additional info here.

Clients:
Clients consist of a name, e-mail, login username, password and an info box. The
username and password are the login info they need to enter ad_client.php. All the rest
have no real importance, but can help you remember info about the clients, like
their contact e-mail adress. In the info box, you can store any other information you
may find neccessary (e.g. their snail mail adress).

Since at least one client is required, if you don't really want clients & stuff, simply
create one client and assign him all the banners.

Banners:
The name of the banner isn't displayed on the user, it is just for you to remember
which banner is what. If you fill the Text box, the code there will be used instead
of the image you set.

Groups can be very helpful in case you want 3 or 4 different rotations. For example, let's
say a page has a 468x60 banner on top and a 120x30 banner on the bottom left. You could
assign the group 'large' for the top banners and the group 'small' for the second group
of banners which will appear on the bottom left.

If width and height are filled, they are used instead of the banner's real dimensions.

If you want a banner never to expire, simply leave all Expiration date, displays & clicks
to blank or assign zero values (for expiration date, the zero value is '0000-00-00').

5.2. Rotating banners
---------------------
To add banner rotation to a page, you must do the following:
 - The page is PHP (mime-type: application/x-httpd-php). See system requirements
   for more info.
 - Add the following line (PHP code):
     require "ad.php";

The command to rotate banners is:
  echo show_ad([group], [width], [height]);

All its arguments are optional. What you must notice is that show_ad returns
a STRING and doesn't display it by itself. You must use an ECHO command, like above.
This helps if the same banner should appear twice in the page, like in the
following example:

  require "ad.php";
  $advertisement = show_ad();

  // page shows something here
  echo $advertisement // the banner appears

  ....... // more code here
  echo $advertisement // the SAME banner re-appears

If you place a group as argument, then only the banners in that group will
appear. Width and height, if set, alter the image's dimension (this only applies
if alternative text is NOT used).

If you want a specific banner to appear, use the command:
  echo show_specific_ad(id, [count=0,1], [width], [height]);

This shows a specific banner which has the id you set.

The count argument: (default value 0)
If 0, then it doesn't count its statistics (or expirations)
If 1, the banner statistics are counted (and may expire according to the banner
      settings).

5.3. Client statistics
----------------------
Clients can view their banner statistics from ad_client.php, where they
must enter their username and password to log in.

If you don't want them to be able to view their stats, simply delete
the file ad_client.php.

6. License
----------
Look at LICENSE. If you use JMK Advertisement Rotator, you are bound by the GPL
license agreement. If you do not accept the agreement or you're not following it,
you are not allowed to use JMK Advertisement Rotator.

7. Credits
----------
To friends and family. Extra thanks to my brother Kostas, for providing the need
to build this script :-pp

8. Authors & Contact Information
--------------------------------

Dimitris Batis is behind the whole thing so far. You are welcome to send me
your patches, bugfixes or ideas for the program and your name will appear
here as well.

You can contact me at:
45 Thoukididou St.,
163 43 Ilioupolis,
Athens,
GREECE

E-mail: bat_geor@mail.hol.gr
WWW: http://www.ravencrypt.com/
