The Read It Forward Project By Vince Long June 2006 ----------------------- 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. If I were starting it up today, I would write it in PHP and seriously consider hooking it with a MySQL database server. In fact, I am planning a rewrite of the site to do this in the near future. ----------------------- 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) - Access to the server's CGI-BIN - Support for PERL on the server - text editor to make configuration changes ------------------------------ Installation and Configuration ------------------------------ Extract the zip file into a temporary folder on your hard drive. The files for this application are contained in two folders: cgi-bin folder config.pl Holds the pathpaths and current year crypt.pl Password generator editrecord.pl Opens a selected posting for moderation listreviews.pl Lists all the reviews in the selected year makechange.pl Saves moderated changes passcheck.pl Checks for moderator password and shows list of entries password.txt The current password readreview.pl Opens a selected review for viewing saveform.pl Saves a user review for moderation html folder bicon.gif Review icon crypt.htm Unlinked page for generating passwords using PERl crypt index.htm Main page reviewlist2004.txt Previous year review reviewlist2005.txt Current year review RIF-LOGO.gif Image for main page TITLE.gif Image for main page readme.txt This file Now you will need to configure the files to work with the filepaths you will use on your server. I am assuming that the html files will be placed in their own folder in your server's documents folder and you will name that folder "rif." With this configuration your Read It Forward site's URL would be: www.yoursite.com/rif/ Using a text editor, such as Notepad, open the config.pl file in the cgi-bin folder. You will see these lines: #! /usr/bin/perl # Read It Forward # Configuration File # May 2006 # Vince Long $htmlpath = "../../rif"; $reviewlist = "c:/pub_html/rif/reviewlist"; $currentyear = "2005"; 1; The first line points to the location of the PERL interpreter on your server. You might need to change this for the PERL scripts to execute properly. If you do not know the correct path, check with your webmaster. If you need to make a change, you will need to make this change in each of the files in the CGI-BIN folder that end with a .pl file extension. Notice the line that starts with $htmlpath and see the "rif" in that line. The "rif" is the name of the folder in which you will install the html files on your server. If your folder will have a different name, replace the "rif" with your folder name. If your folder will be inside another folder(s), you need to include that as well. For example, if your Read It Forward folder was going to be inside a folder called "projects," then the first line above would be: $htmlpath = "../../projects/rif"; The next line above is the full path to where the html files are stored, including the drive name. Make required changes. The next line is the current year. At this time you might just leave it set to 2005 file so that the sample files will work as you test your installation. Save the file(s) after making the changes. --------------------------------- Setting Up Folders on the Server --------------------------------- You need to log on to your server and create two new folders. Create a new folder in your web server's document directory. You can name it whatever you would like, however, the default name in the configuration file is "rif" and I would suggest using that to avoid potential errors. Next, create a folder in your server's cgi-bin folder. You may need webmaster assistance to gain access to this. I suggest that your name for this folder be "rif" as we did with the previous folder. If you name the new folder in cgi-bin something different, you will need to make changes to the code in the site's main page. See below for how to do that. --------------------------------- Copying Folders to the Server --------------------------------- Copy the files from the html folder on your computer to your new html folder in the server's document directory. Copy the files from cgi-bin on your computer to the new folder in the cgi-bin folder on the server. How you copy the files will depend on how you access your server but FTP is the most likely way. See your webmaster for FTP access if necessary. Go to the URL, as shown above and test the site. If problems occur they will most likely be one of the folowing two types: Filepath issues - If the paths in the config.pl do not match the paths of the server, the site will not work. PERL executable issues - The first line in each PERL script must point to the PERL interpreter. Also, you may need to have the proper permissions to execute PERL scripts on the server. ---------------------------- Making Changes to index.htm ---------------------------- If you have your PERL scripts installed in a different location that a folder name "rif" in the server's cgi-bin, you will need to reflect that in three places in the index.htm file, which is your main web page, found in the original html folder. Open that file in your text editor and scroll down to about line 98 and find this line:
Change the path to suit your installation. Two similar changes will also be required. One on line 142, which looks like this: 2005-2006
and one on line 157 which looks like this: Save the file and copy it to the server. ----------------------- Creating a New 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. First, we need to create a link to the new year on the main page. Open index.htm and scroll down to about line 142, which looks like this: 2005-2006
Copy that line and paste it above the current line and then make the necessary changes so it looks like this: 2006-2007
2005-2006
Save the file and copy it to the server. Now open the config.pl file and scroll down to about line 12: $currentyear = "2005"; Change the 2005 to 2006. Save the file and copy it to the server. That's it. -------------------------------------------- Changing the Database Maintenance Password -------------------------------------------- The password is contained in a file named password.txt in the cgi-bin folder. It is a plain text file. To change it, open it in your text editor and type in a new password. IMPORTANT: do NOT press enter or return at the end of the line that the password is on. If you do, you will not be able to log in. ---------------- Some Tech Notes ---------------- I am not a professional programmer. I only do what I need to do to get the job done, therefore, the code in my PERL scripts is likely to be ugly. Also, because PERL is stateless and I wanted to handle security on the site effectively, I pass a version of the password as a query string. This is not robust by any means and I have since learned to use PERL's crypt function. Feel free to implement it if you wish. There is a sample crypt page and script in the html and cgi-bin folders. -------------------------------- Copyright (c) 2006, Vince Long All rights reserved. -------------------------------- 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.