SimpleNews 1.0.0

	Table of Contents
	1. Introduction 
	2. System Requirements
	3. Installation
	4. Usage
	5. Themes
	6. Getting Support 
	7. Project Help

=================================================
** Introduction**
=================================================
Thank you for downloading SimpleNews! This read-me file will walk you through getting SimpleNews up and running on your system.
SimpleNews was written 100% on open source software and is distributed under the GNU General Public License. A copy of the GPL is accompanied with this document and is also available online at http://www.gnu.org/licenses/licenses.html#GPL.

=================================================
** System Requirements** 
=================================================
To install SimpleNews you will need the following:
* A Web Server (Apache recommended)  http://www.apache.org
* PHP 4.x or Greater with Session support compiled in http://www.php.net
* MySQL 4.x or Greater http://www.mysql.com

SimpleNews should be OS independent.  It has been tested on several flavors of Linux and is reported to run just fine on Mac OSX Windows should be no different.

If you're not sure you meet these requirements, check with your ISP/Hosting Company/Systems Admin/Computer Guru/etc.

=================================================
** Installation** 
=================================================
First, you will need to download the latest version of SimpleNews -- if you're reading this, we can assume you've already done so. ;)
Extract the downloaded file to a temporary directory somewhere on your computer.  How you unpack the file will vary depending on your OS. Consult your OS's documentation if you're not sure how.

Note that all MySQL tables that are created will be prefixed with 'simplenews_*'. This should prevent any conflict with other applications that may share the same database.

*** New Installation ***
1. Upload the extracted simplenews directory to your web space.
2. Change the file permissions on simplenews/includes/dbconnect.php so that it is writable.
	In Windows: Right-click on the file and choose Properties >> Security. 
	In Linux/Unix: chmod +w /path/to/simplenews/includes/dbconnect.php
3. Open your Web Browser and point it to: http://your_webserver/simplenews/setup/index.php
	Follow the on-screen steps to create and configure the SimpleNews database. You will need the following information:
	 - MySQL Username and Password
	 - MySQL Host Name
4. When setup is complete, you should remove the simplenews/setup directory and also change the permissions of dbconnect.php so that it's read-only.

*** Upgrade an Existing Installation ***
To upgrade from 1.0.0 RC1 or RC2, use the following steps. Note that if you've made any changes to the code or modified the default theme, you should make a back-up copy before proceeding.
1. Back-up your existing simplenews/includes/dbconnect.php file -- we will need this later.
2. Upload the extracted simplenews directory to your web space overwriting any files.
3. Copy your original simplenews/includes/dbconnect.php file over the top of the new one that was created in the above step.
4. Open your Web Browser and point it to: http://your_webserver/simplenews/setup/index.php
5. Follow the on-screen steps to update the SimpleNews database.
6. When setup is complete, you should remove the simplenews/setup directory.
You can skip the next section when performing an upgrade installation.

=================================================
** Usage** 
=================================================
SimpleNews is installed but it still needs to be added to your existing web page before you will see any news posts. 
The first thing to do is rename the page you want the news to display on to a .php extension. For example, if on index.html you want to see the news output from SimpleNews, rename that page to index.php -- same if the page is called news.htm, rename it to news.php. This way, the web server knows that there's php code on the page to be translated.

Next, add this line where ever you want the news posts to be displayed: 

	<?php include("./simplenews/news.php"); ?>

You may need to change the path to news.php in the above code if you have SimpleNews installed in a directory other than the one the file you renamed in the first step is in.

You can also look at example.php, which is included with this file as an example of adding the above code. 

=================================================
** Themes** 
=================================================
The theme system in SimpleNews is pretty straight forward. There are several template files that get assembled dynamically when an article is viewed for each part of the page. From a design standpoint, there is no (not much) limitation to what you can do with the template files as long as the required variables are in place.
The below table shows what variables are available for each template object.

Template Name
Description
Variables

article.tpl
Design of the Article Snippet and Full Article container.
{PHP_SELF} {NEWS_ID} {POSTER} {TITLE} {TIMESTAMP} {SNIPPET}
{ARTICLE} {NUM_COMMENTS}
{THEME} {TOPIC_ICON} {FULL_ARTICLE_LINK}

no_articles.tpl
Notice that gets displayed when no articles exist.
{PHP_SELF} {THEME}

comments.tpl
Container for visitor comments.
{NEWS_ID} {GUEST} {COMMENT} {TIMESTAMP} {EMAIL} {THEME}

comments_form.tpl
Form used by visitors to enter article comments.
{PHP_SELF} {NEWS_ID} {COMMENT_SIZE} {THEME}

email_form.tpl
Form used by visitors to email a link to the article.
{PHP_SELF} {NEWS_ID} {THEME}

footer.tpl
Displays at the bottom of SimpleNews generated content.
{VERSION} {THEME}

header.tpl
Appears at the top of SimpleNews.
{PHP_SELF} {THEME}

print.tpl
Template for the printer-friendly article preview.
{TITLE} {POSTER} { TIMESTAMP } {SNIPPET} {ARTICLE} {THEME}

sticky.tpl
Template for the Sticky post.
{TITLE} {POSTER} { TIMESTAMP } {TOPIC_ICON} {SNIPPET} {THEME}

Variables are used in the template file to denote information such as, Article ID, Author, Date, etc. All variables are incased in { and } brackets and are in UPPERCASE. 

The table below gives a brief definition of each variable.

Variable Name - Description

{PHP_SELF} - The current page (Example: http://yoursite /script.php)
{NEWS_ID} - The ID number of the news article
{POSTER} - Author of the article
{TITLE} - Title of the news article
{DATE} - Date article was published (example)
{SNIPPET} - Shortened version of the news article
{ARTICLE} - Full version of the news article
{NUM_COMMENTS} - Total number of comments made for the article
{THEME} - Name of the theme in use, used in a path (Example: http://yoursite/simplenews/themes/{THEME}/yourfile.png)
{TOPIC_ICON} - Topic icon
{FULL_ARTICLE_LINK} - Link to the full article if applicable

=================================================
** Getting Support** 
=================================================
If you have any question related to SimpleNews:

	Support Forums	- http://forums.chaoscontrol.org
	E-Mail		- support@chaoscontrol.org
	
=================================================	
** Project Help** 
=================================================
SimpleNews was written on 100% open source software and is provided free of charge under the GNU Public License -- But free for you means expenses for us. :(
The success of an open source project is dependent on its community. If everyone contributes to the project, the community flourishes. The developers have donated their time and talents in building this project so if you find SimpleNews useful, why not donate a few bucks to help us with the web hosting and bandwidth expenses? -- and maybe even the occasional trip to the local pub to help keep our sanity ;)
You can donate using PayPal via the following link: 

	http://simplenews.chaoscontrol.org/index.php#donate

You can also donate to SimpleNews in many other non-monetary ways. You can help us track down bugs, submit patches and add-on modules, create themes, translate or create documentation and also by telling your friends about the project ;)

Thanks,
The SimpleNews Development Team

