The Read It Forward Project Version 2.0 By Vince Long November 2008 ----------------------- Overview ----------------------- Sometime in 2003, TerraBeth Jochems, the reading support specialist at Billings Senior High in Billings, Montana was looking for a way to encourage more students to read more books. Her idea was to start a Read It Forward Project based on a concept from the movie, "Pay It Forward," where receivers of a good deed did the same for someone else. Initially the idea was for readers to pass a good book on to someone else with a recommendation. The problem was that no one knew who was taking part in the process. The Read It Forward web site serves as a centralized location for the community of readers at Senior High to share book recommendations with others. Seeing this as a straightforward database project, I worked with TerraBeth to determine what fields would be recorded and how the site would function. At first I thought I might use a smut filter of some kind to eliminate the problem of users who might post inappropriate content. After investigating the pros and cons of this approach I decided on a moderated system and enlisted TerraBeth, our librarians, and a few English teachers to periodically review the content and approve, disapprove, or delete postings. Using PERL to operate the site was an easy decision as, at the time, it was the only language I knew that could do this. In January 2008, I rewrote the site in PHP. I am now releasing the PHP version licensed under the terms of the GNU Lesser General Public License: http://www.opensource.org/licenses/lgpl-license.php Also with this PHP release I am including the FCKEditor, an open source online editor. http://www.fckeditor.net/ The application currently uses flat files to store the data. Yes, this does present some scalability issues, but the current goal is to ease the installation and use. A future version might use MySQL but I have found that performance of this current version is fine. The test file contained 320 records and was 430 megabytes in size. The test server was a Pentium 4, dual core, with 2 GB RAM, running XP Pro and Sambar web server. ----------------------- System Requirements ----------------------- To use this software you will need the following: - Access to a web server (I am using a Windows-based system but a Linux or Macintosh system will work similarly) - Support for PHP on the server - text editor to make configuration changes ------------------------------ Installation and Configuration ------------------------------ Assuming that you will use an ftp client to send the application to your web server, extract the zip file into a temporary folder on your hard drive. Some of the files for the application be in the root of the temporary folder and others will be in three folders in the temporary folder: FCKeditor folder This contains the FCKeditor application. You shouldn't have to make any changes in here. fonts folder This contains font images used in my homebrew "captcha" to reduce the spam that can get into the database. images folder Contains images used on the site: clubname00.jpg sample image with your organization's name clubname01.jpg another sample image with your organization's name project_name00.jpg sample image with the project's name project_name01.jpg another sample image with the project's name fader.gif image add a shadow between the navbar and main body logo.jpg the image that appears at the top of the navbar main files access_denied.php shows error when session not active admin.php main adminstrator page badpass.php shows error when passwords don't match bicon.gif the star image for ratings config.php configuration file create_entry.php add new entry to database create_new_year.php create a new year for the database currentyear.txt text file containing name of current year editrecord.php admin file for editing records index.htm forwards user to index.php index.php the main page of the site listreviews.php show the reviews for the current year login.php authentication page makechanges.php save data changes made with editrecord.php nopass.php shows error when passwords not entered readme.txt this file readreview.php show a single review (record) related.lks navbar links reviewlist2008.txt default list of reviews saveform.php saves a new entry to the database select_current_year.php saves the selected year to currentyear.txt sortauthor.php shows reviews sorted by author sortrating.php shows reviews sorted by rating sortrole.php shows reviews sorted by role sortsubmittedby.php shows reviews sorted by who submitted them sorttitle.php shows reviews sorted by title style.css the style sheet for the site year_not_entered.php shows error when year to change is incorrect Configuration Now you will need to make changes in the config.php file for the application to work properly. Using a text editor, such as Notepad (Windows), open the config.php file. You will see lines of text. The items on the left of the equals signs are variables. DO NOT CHANGE THEM. The data in single quotes to the right of the equal signs is data you can change. The data after the double slashes tells you what each line does. Let's go through each item. If you make changes, only change what is between the single quotes. $sitetitle1 = 'My Reading Club'; This is the name of your organization. $sitetitle2 = 'Read It Forward Project'; This is the site name. $images_path = 'images/'; This is the file path to images. You shouldn't have to change this. $titleimage1 = 'clubname00.jpg'; This is the image that shows the organization name. It was created at www.cooltext.com. The font used is Goodfish (in the Classic section), its font size is 45, its font color is black. Remaining settings were default. The background was texture number 6. If you create your own image, you can name it whatever you wish, but change this setting to match that name. If you leave the image name blank, that is, '', the name you asign in $sitetitle1, above, will apear instead of an image. $titleimage2 = 'project_name00.jpg'; This is the image that shows the project's name. It was created like the previous image. Leave it blank, that is, '', if you want to use the text in $sitetitle2 $contact = 'my_email@my_isp.com'; This is the contact email that appears on the main page. Put your email address here. $adminpass = 'bill'; This is your administrator password. $navbar_color = '#ffda8c'; This is the background color of the left side navigation bar. You can change the color by specifying its hex code or color name. For a list of codes, color names, and color samples, try: www.computerhope.com/htmcolor.htm $textblock1 = "The Read It Forward Project encourages everyone to read a good book and share your enthusiasm for it with others"; This is the text that appears on the main page under the main titles. Change it to suit your needs. The remaining lines read the current year into the program. DO NOT CHANGE THESE. // read the current year from the file $filepointer = fopen("currentyear.txt", 'r'); $currentyear = fgets($filepointer,999); fclose($filepointer); Make required changes and save the file. --------------------------------- Changing the navbar links --------------------------------- The links that show in the navbar on the left side of the page are stored in a text file named: related.lks To add or subtract links from this list, open the file in a text editor. The default file contains these entries: Codecooker.com Gutenberg Project Library of Congress To delete an item, delete it's line from the list and save the file. Then upload the file to the server with the other files as instructed below. To add a link, use this format: YYYYYYYYY where XXXXXXXXXX is the URL of the site and YYYYYYYYY is the text you want to appear in the navbar. --------------------------------- Setting Up Folders on the Server --------------------------------- You need to FTP to your webserver. If these will be the only pages on your site, you can transfer all the files into your root document directory. If you want the application to be in a subdirectory of your main site, create the directory and then open it. --------------------------------- Copying Folders to the Server --------------------------------- Copy all the files and directories/folders from the temprary folder on your computer to your webserver. Go to site and test the site. --------------------------------------------------- Creating a new year and making it the current year -------------------------------------------------- The software supports multiple years, that is, at the end of a year you can create a new one and the old year will still be accessible. All new additions will be added to the current year. To create a new year, log in as administrator from the main page using your administrator password you set in the config.php file above. Type in a new year in the box provided and submit the form. Go back to your administrator page and select that year from the list and submit the form. That's it. -------------------------------------------- Deleting a year -------------------------------------------- To delete a year of reviews you will need to FTP to the server. Each year is named as follows: reviewlistXXX.txt where XXXX is the year. Delete the file using the delete feature of your FTP client. ---------------------------------------------------------------------- Copyright (c) 2007,2008 Vince Long Licensed under the terms of the GNU Lesser General Public License: http://www.opensource.org/licenses/lgpl-license.php ---------------------------------------------------------------------- Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the owner nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.