TextAds v0.99.1
----------------------------------
TextAds are a simple, polite, and inexpensive alternative to banners and other online advertising. TextAds provide 
all of the benefits of other forms of online advertising without the annoying downsides. There has been a considerable 
amount of backlash by users as many online advertisers have resorted to more and more desperate attempts to capture 
user's attention. Pop-up ads, Pop-under ads, full-page ads. These are just a few examples of advertising that many 
users find to be intrusive. So much so that several companies have begun distributing software that lets users block 
all traditional forms of advertising. TextAds, by comparison, are small, effective, and most importantly, respectful 
of users. They cannot be blocked by ad filtering software and have proven to be quite successful. 


Requirements:
------------------------------------
Linux (any version greater than 2.0)
MySQL version 3.23.XX or higher
Apache version 1.3.X or higher
PHP version 4.X.X
Lynx (any version)


Installing TextAds:
------------------------------------
Copy file to the root directory of your website.

Example: cp textads_X_XX.tgz /web/mywebsite/html/
  
Untar the file:

Example:  tar -xzvf textads_X_XX.tgz

This will create a directory called textads and the files needed for TextAds will be in that directory.  Technically, 
you can rename the directory anything you want and it will work fine but just note the changes in the rest of the 
documentation and replace the textads directory with the directory of your choice.

Enter the TextAds directory.

Example:  cd textads/

Create your database.  It's recommended that you use a naming schema like textads_yourwebsite 
in case you want to run more than one copy of TextAds.  

Example:  mysqladmin create textads_yourwebsite

It's recommended that you don't run TextAds as database user root, nor should you run any database user accounts without a 
password (especially root).  Since general database security is beyond the scope of this document, you are referred to the 
following MySQL documentation pages for more information on database security issues.

http://www.mysql.com/doc/P/r/Privilege_system.html

Create the tables in your database by giving the following command:

mysql -u[the user you set up] -p[the password you set up for this user] -D[the name of your database] < ads.sql

If you get any errors like "ERROR 1045: Access denied for user: 'root@localhost' (Using password: YES)" you need to 
check the permissions you just set up on this database.  The user should have the ability to SELECT, UPDATE, DELETE, 
and the ability to CREATE tables.  

Open config.php in the editor of your choice and edit the configuration options to match your particular confirguration.  
Right now, the only ones you really need to change (unless you changed the directory to something other than textads) are the 
following (I'll explain the rest of the options later in this document):

$ads_dbhost:		This will most likely be localhost unless your database is on another machine)

$ads_dbuname:		Set this to the user name for the database.

$ads_dbpass:		The password for the database.

$ads_dbname:		Name of the database you just set up.		 

$defurl:		The URL of your website (without the trailing slash) such as http://www.windowsix.com

$shash:			This is a random set of characters that is used to create a hash by the program.  
			Change this to any random value you would like though it should probably be between
			7 and 32 characters long for security and practical purposes.

$ashash:		This is similar to $shash except that it's Admin specific.  Change it to a value as described above
			but make sure that it is different from $shash.

$adminpass:		This is the Admin password and needs to be encrypted.  Point your browser to 
			http://yourwebsite/textads/crypt.php and use this tool to get the encrypted value
			of your password.

$adminemail:		The is the email of the site Admin.

$page_title:		Title that is inserted in all of the TextAds pages.

$ta_sitename:		This is the name of your website.

$dumpfile:		Each evening TextAds does a datadump of your TextAds database so you can back this information 
			up in the event of some sort of crash.  This is the location and prefix of the file TextAds will 
			output the contents of your TextAds database.  Leave this blank if you would rather TextAds not 
			make evening backups of your data.

$cms_nuke               If you are using a CMS system like PostNuke or PHPNuke or phpWebSite, or any other system which
			controls the database connections, set this to 1, otherwise set it to 0.  If you get errors 
			when testing out TextAds that say something like "Unable to connect to database" or "Unable
			to select database" this setting is probably wrong.  


$default_ad_text:	If TextAds can't find an ad to display it will display the defualt ad you specify in config.php 
			which is defaulted to your own site.  This would be the text description you would like the ad
			to use.

$update_sender:		Change this to the email address you would like your emails to users confirming their purchase to
			come from.

$password_sender:	Change this to the email address you would like your emails sending updated passwords to come from.

$email_on_purchase: 	If you would like to be notified via email when someone makes an ad purchase set this to
			1 otherwise set it to 0.

$purchase_email:	If you set $email_on_purchase to 1, this is the email address you would like the notices sent to.

$gmtoffset:		If your webserver is set to GMT and you would like to set an offset amount change this value 
			to the appropriate number of seconds you need to offset.

$ttcolor:		This is the color of title bars in TextAds.

$tlcolor:		This is the color of the border around the text ads.

$tbcolor:		This is the color of the background of the text ads.

If you haven't already created a PayPal account, you must do so now.  Make sure to use the options to create a merchant type account 
where you can accept payment from other PayPal users.  Also, register for the affiliates program so you can get paid when a user opens 
a PayPal account from a link on your site.  You will need the following info from your PayPal account

$pp_email:		This is going to be the email address you use to register with PayPal.

$pp_ref:		This is the affiliates URL from PayPal.

Almost done.  Now you need to go in and create some ads.  It's a good idea to do at least one ad advertising the TextAds on your site.  
It's also a good idea to do at least one ad for the PayPal affiliates program you just signed up for.  Another good source of "advertisers" 
is BeFree (http://www.befree.com) and Commission Junction (http://www.cj.com).  They will allow you to sign up for various affiliate programs 
and then you can add them into your advertising rotation.  

The best way to create ads is as a normal user.  Just go to http://yoursite/textads/ and sign up to create an ad.  This will also give you a 
good feel for what your users are seeing so it's a nice little quality assurance thing too.  Don't worry, you won't have to pay for your ads.  
The way PayPal works, you never know if the user completes the same transaction you sent them to PayPal with.  They can change the dollar amount 
or just fail to complete the transaction alltogether.  Because of this, TextAds only marks the ad as pending in the database and you must approve 
it before it goes into rotation.  So, just complete the TextAds forms as if you were purchasing the ads and when it sends you to PayPal.  
Just return to the main signup page (either by hitting the back button several times or going to http://yoursite/textads/ and then log in and 
create more ads.  You have to go back to the signup page because TextAds only allows one email address per account and just filling out the form 
again would look like you were trying to create two accounts with the same email address.  When you log in from the main sign up page, you can simply 
hit the back button to return to the account summary page and create the next ad without logging in again.  

Once you've entered your ads, go ahead and approve them.  You do that as the Admin.  Go to http://yoursite/textads/radmin.php and log in with the Admin 
email address and password that you selected in the config.php file.  Remember, use the unencrypted password you created with crypt.php, not the 
encrypted one.  You will see a summary page when you log in.  Click on the Pending link and change the status of your ads to Active.  

Now, time to test everything out.  Create a file called test.php and put it in your webserver root directory.  In test.php insert the following code:

<?php
include('./newads/textad.php');
?>

Now open test.php in your browser (this should be by going to http://yoursite/test.php).  Ta-da.  Don't worry about the size of the ad, you can control 
that by putting table tags around where you insert the ad.  Test to make sure that when you click on the link it goes to the correct location, etc.  

Now you're ready to put the ads into your webpages.  Assuming you're using a PHP based Content Management System (CMS) like PHPNuke or PostNukr or 
phpWebSite (if not, you may have to tweak some things on your own), simply identify in your themes where you would like the text ads to appear 
and insert the following code:

include('./newads/textad.php');

Remember that you can't insert that line in the middle of an echo or print statement so you may need to stop the echo statement, insert the TextAd 
code and then start a new echo statement.  So for example if I had the following:

       echo "</TR>\n"
        ."<TR>\n"
        ."<TD WIDTH=\"15%\" BGCOLOR=\"$bgcolor3\" ALIGN=\"center\" VALIGN=\"top\"></TD>\n"
        ."<TD WIDTH=\"5\"><IMG SRC=\"/themes/Rini/images/pix-t.gif\" WIDTH=\"5\" HEIGHT=\"1\" ALT=\"\" BORDER=\"0\"></TD>\n"
        ."<TD ALIGN=\"center\" VALIGN=\"top\" BGCOLOR=\"$bgcolor3\">\n";


I would need to change it to this:

       echo "</TR>\n"
        ."<TR>\n"
        ."<TD WIDTH=\"15%\" BGCOLOR=\"$bgcolor3\" ALIGN=\"center\" VALIGN=\"top\">\n";

        include('./ads/textad.php');

        echo "</TD>\n"
        ."<TD WIDTH=\"5\"><IMG SRC=\"/themes/Rini/images/pix-t.gif\" WIDTH=\"5\" HEIGHT=\"1\" ALT=\"\" BORDER=\"0\"></TD>\n"
        ."<TD ALIGN=\"center\" VALIGN=\"top\" BGCOLOR=\"$bgcolor3\">\n";

TextAds will also work with Perl based CMS's like Slashcode (assuming PHP is running on your system obviously) but you'll need to make some modifications 
that are beyond the scope of this document.  I will just say this though, I had it working with Slashcode and the major modifications are:

1.  Write a Perl program or insert a function that gets called during page generation that generates your ads similar to how they are generated in textad.php. 

2.  Update the views in the database each time the program/function is called.  

At the moment, doing that part is up to the user since TextAds is currently only supported using PHP parsed pages.  

And for the final setup piece, put statsupdate.php into a cron job.  statsupdate.php updates all of your daily summary data, does some clean up changing user's 
status if the number of impressions ordered is served, and dumps out the daily database backup.  

Type the following:

If you're running RedHat you can put a file with the command "lynx -dump http://yoursite/textads/statsupdate.php" in /etc/cron.daily and that should do 
the trick.  If you want to associate the cron job with a user on your system (if this is how you prefer to manage your cron jobs) make sure that user 
has permissions to execute the program "lynx" or you will get "permission denied" errors when it's supposed to run.  Also, depending on which version
of lynx you're running, you may get an error such as the one below when running this command from a cronjob (it will process fine via the command
line or the browser and only fails when set up in cron):

Your terminal lacks the ability to clear the screen or position the cursor.

If this happens, change your crontab settings to fake a terminal by changing the command to:

TERM=vt100 lynx -dump http://textads.sourceforge.net/textads/statsupdate.php

Some joker could come and hit that program with a web browser but if it's already updated the summary data for the day it will just spit out a message 
saying that it's already been updated.  No harm done. 

Now, sometimes, for whatever reason, bad things do happen and sometimes cron doesn't run or your database is down or your webserver is down or ??????.  
If that happens and statsupdate.php doesn't run you can run it from the command line and feed it some options or you can do the same thing from the 
web browser.  

From the command line:

lynx -dump http://yoursite/textads/statsupdate.php?offset=2

From the browser:

http://yoursite/textads/statsupdate.php?offset=2

The offset is the number of days you would like it to go back.  It already goes back 1 day so it's grabbing yesterday's data so all of the following do the 
same thing (we grab the 0 and turn it into 1 so you can't do a partial day):

http://yoursite/textads/statsupdate.php
http://yoursite/textads/statsupdate.php?offset=0
http://yoursite/textads/statsupdate.php?offset=1 

If you want to clean things up a bit, you can delete ads.sql, crypt.php, and README if you want to.  At a minimum you should move them outside of your 
web directories so people don't mess with them.   


Files in this distribution:
------------------------------------
COPYING:			GPL agreement.
CHANGELOG:			List of changes.
README:				This file.
TODO:				Stuff on the to-do list.
ads.sql:  			Contains the SQL Code to generate the necessary tables.
alert-icon.gif:  		Image used in user reports to alert users.
clickcatch.php: 		Handles redirects when someone clicks on an ad link.
config.php:  			The config file.
crypt.php:  			A tool for you to encrypt the admin password.
faq.php:  			The FAQs
footer.php: 			The footer at the bottom of each page.
functions.php: 			Contains many common functions.
header.php: 			The header at the top of each page.
index.php: 			The main page users go to when they want to buy ads or log into reports.
logo_sm.gif:  			Small Window Six logo that goes into the page footer.
radmin.php:  			The admin section.
reports.php:  			The user reports section.
statsupdate.php: 		A small program run as a nightly cron job to update summary tables in the database.
textad.php:  			The code that generates the text ads seen by users.
textads.gif:  			Image that appears on index.php that shows what the reports section looks like.

