*************************************************************
*    INCLUDED IN THIS README...
*************************************************************

     I.) ABOUT THE APPLICATION
    II.) CUSTOMIZING LOCAL COPYRIGHT INFORMATION
   III.) ADDING A PAGE FROM THE APPLICATION
    IV.) EDITING A PAGE IN THE APPLICATION
     V.) REMOVING A PAGE FROM THE APPLICATION
    VI.) APPLICATION STYLE GUIDE
   VII.) ADVANCED CUSTOMIZATION



*************************************************************
*    I.) ABOUT THE APPLICATION
*************************************************************
For information about the content within the application,
please contact Michael Brewer at brewerm@u.library.arizona.edu.

All code, unless otherwise stated, was developed by
100 Pianos Web Development for the American Library
Association. For more information about the technical
details of the application, please contact Justin Spargur
at justin@100pianos.com.

All XHTML, CSS, JavaScript, and PHP was developed with
consideration for W3C standards, accessibility, and 
accepted web development best practices. HTML code was
validated as XHTML Strict. CSS was validated using the
W3C CSS validation tool. Accessibility was validated
using the HiSoftware Cynthia Says(TM) Web Content 
Accessibility Report.

The application does use JavaScript to enhance the
functionality. However, all use of JavaScript is
limited to non-functional use and the application
will still function properly with JavaScript
disabled.

The application has been tested on the following
web browsers:
   - Internet Explorer 6.x and above (Windows only)
   - Firefox 2.x and above (Windows, Mac, and Linux)
   - Safari 3.x (Windows and Mac)
   - Opera 9.x (Windows, Mac, and Linux)

All images have been optimized for use on the web by using
the smallest file size and format available for each one.
This ensures quick loading times for the application,
regardless of the user's browser and bandwidth limitations.

To provide PNG transparency support for IE 5.5 - IE 6, 
we used the IE PNG Fix v1.0 developed by Angus Turnbull
licensed under the CC-GNU LGPL, version 2.1 or later.
Full source code for this fix as well as an online
demo can be found at http://www.twinhelix.com/css/iepngfix/.

PDF creation is done using the FPDF class, released under
a permissive license without any restrictions. More
information about FPDF can be found at http://www.fpdf.org/.



*************************************************************
*    II.) CUSTOMIZING LOCAL COPYRIGHT INFORMATION
*************************************************************
To add customized local copyright information, you will
need to edit the file named, "localcopyrightinfo.php".
For more information about editing files, please see
section IV, "Editing a Page in the Application".



*************************************************************
*    III.) ADDING A PAGE FROM THE APPLICATION
*************************************************************
The simplest way to add a new page to the application is
as follows:

   - Start by copying an existing file that most closely
     mirrors the page that you want to create.

   - Rename the new file using a filename that is
     representative of the content within that page.
     IT IS IMPORTANT THAT THE FILE HAS A ".php"
     EXTENSION (WITHOUT THE QUOTES) AND THAT THE
     FILE IS NAMED USING ALL LOWERCASE LETTERS.
     
        E.g., a page about music copyright could
              be named "music.php".

   - Next, edit the new file so that it includes the
     content that you want to include in the application.
     To edit a .php file, you can use any text editor,
     a web page editor such as DreamWeaver or Front Page,
     or any number of other web page editors. More
     information about how to incorporate specific
     styles and formats in the application can be found
     in the style guide below.
     
        WARNING: IT IS RECOMMENDED THAT YOU NOT EDIT
                 ANY OF THE PHP CODE AS FOUND BETWEEN
                 THE "<?php" and "?>" LINES UNLESS
                 YOU ARE FAMILIAR WITH PROGRAMMING
                 AND THE PHP PROGRAMMING LANGUAGE.

   - Next, you will add the newly created file to
     the workflow. To do this, start by opening the
     file named "properties.php".
     
   - Next, find one of two sections that you would like
     the new page to exist in, either the "Evaluation
     Tool" pages or the "Educational" set of pages. In
     the original code, these can be found at lines 50
     and lines 64 respectively.
     
   - Finally, you will add your newly created file to
     the set of pages by copying an existing line,
     pasting it into the position that you want, and
     then replacing the name of the copied file with
     the name of your new file. For example, to add
     a new page named "music.php" as the fourth
     page in the Educational portion, we would add
     it to the set as follows:
     
        $educationalPages[] = "guidelines.php";
        $educationalPages[] = "music.php";
        $educationalPages[] = "fairusefactors.php";

If you would like to do more customization than is described
in the steps above, please see the "Advanced Customization"
section below.


NOTE: The progress bar found in the upper right-hand corner
      of the application will automatically adjust for any
      new (or removed) pages.



*************************************************************
*    IV.) EDITING A PAGE IN THE APPLICATION
*************************************************************
To edit an existing file, begin by opening the file
you want to modify. PHP files can be opened with any text
editor, a web page editor such as DreamWeaver or Front Page,
or any number of other web page editors. More information
about how to incorporate specific styles and formats in the
application can be found in the style guide below.

When you are finished making changes to the file, save and
close the file. Your changes will be immediately viewable
the next time you view the application in a web browser.

   WARNING: IT IS RECOMMENDED THAT YOU NOT EDIT
            ANY OF THE PHP CODE AS FOUND BETWEEN
            THE "<?php" and "?>" LINES UNLESS
            YOU ARE FAMILIAR WITH PROGRAMMING
            AND THE PHP PROGRAMMING LANGUAGE.



*************************************************************
*    V.) REMOVING A PAGE FROM THE APPLICATION
*************************************************************
The simplest way to remove a page from the application is
to "comment it out" in the properties.php file. This will
allow you to re-insert pages into the application if you
change your mind in the future. To comment out a line,
simply add two forward slashes at the front of the line.
This will keep the file from being included in the
application.

For example, to remove the page named "guidelines.php",
we would add it to the set as follows:
     
        //$educationalPages[] = "guidelines.php";
        $educationalPages[] = "fairusefactors.php";

NOTE: The progress bar found in the upper right-hand corner
      of the application will automatically adjust for any
      removed pages.



*************************************************************
*    VI.) APPLICATION STYLE GUIDE
*************************************************************
   
   PAGE HEADERS
   --------------------------
   Individual page headers used in the application should
   be enclosed inside of <h2> tags. These should not
   be enclosed inside of any column <div> tags as described
   below.
   
   Page headers have two sizes of fonts. The smaller
   font is the text that is contained within the
   <h2> tag alone. The larger font is text that is
   contained inside the <h2> tag but is also enclosed
   in a <span> tag.
   
      E.g., <h2>Smaller Text <span> and Larger Text</span></h2>

   
   COLUMN-BASED LAYOUT
   --------------------------
   The application will support two layouts, one with a
   single column that occupies approximately 80% of the
   screen, and one with two columns, each taking up
   approximately 38% of the screen.
   
   To create a single-column layout, simply include all
   subsequent HTML elements inside of a <div> tag with
   the class attribute, "singleCol".
   
      E.g., <div class="singleCol">Single column content</div>
   
   To create a two-column layout, the code is a bit more
   complex. There are three levels of <div> tags: a wrapper div,
   a box div, and two column divs. The wrapper div has
   a class attribute of "twoColumnBoxWrapper". The
   box div has a class attribute of "twoColumnBox".
   The individual column <div> tags have class attributes of
   "twoColumn col1" and twoColumn col2" respectively.
   The diagram below illustrates how the columns
   will be displayed on the page.

    ____________________________________________________
   |                                                    |
   |  <div class="twoColumnBoxWrapper">                 |
   |                                                    |
   |    ____________________________________________    |
   |   |                                            |   |
   |   |    <div class="twoColumnBox">              |   |
   |   |                                            |   |
   |   |    _______________      _______________    |   |
   |   |   |               |    |               |   |   |
   |   |   |               |    |               |   |   |
   |   |   | <div          |    | <div          |   |   |
   |   |   |   class="     |    |   class="     |   |   |
   |   |   |     twoColumn |    |     twoColumn |   |   |
   |   |   |     col1      |    |     col2      |   |   |
   |   |   |   ">          |    |   ">          |   |   |
   |   |   |_______________|    |_______________|   |   |
   |   |                                            |   |
   |   |____________________________________________|   |
   |                                                    |
   |____________________________________________________|


   Finally, it is important that you include an empty
   div after the second column with the class attribute
   of "clearBlock".
   
   Below is an example of what the code will look like
   within a given file.
   
      E.g.:

      <div class="twoColumnBoxWrapper">
         <div class="twoColumnBox">
            <div class="twoColumn col1">
               Content for column 1 goes here.
            </div>
            <div class="twoColumn col2">
               Content for column 2 goes here.
            </div>
            <div class="clearBlock"></div>
         </div>
      </div>
      

   HYPERLINKS LINKS
   --------------------------
   Hyperlinks within the application are one of two formats:
   small or normal sized. For a "normal" sized link, nothing
   needs to be added to the hyperlink. To create a "small"
   sized link (70% the font size of a normal link), simply
   add a class attribute to the hyperlink with the value
   "smallLink".
   
      E.g., <a href="optional.php" class="smallLink">Optional</a>
   
   It is also possible to "pop-up" content from pages within
   the application via hyperlinks. In order to use this
   functionality, simply include a class attribute in
   the link with the value "popUp". When the page is loaded,
   this link will automatically be converted into a pop-up
   window.For example, to create a pop-up link that will
   create a window with the content of "moreInfo.php",
   we would create the link as follows:
   
      E.g., <a href="moreInfo.php" class="popUp">More Information</a>
      
   This functionality only works if JavaScript is enabled in the
   user's browser. It is advised that you also include a GET
   parameter named backLink with the value of the page that
   the pop-up is called from. For example, to create a pop-up
   on a page named content.php, we would create the link as
   follows:

      E.g., <a href="moreInfo.php?backLink=content.php" class="popUp">More Information</a>
  
   

   BULLETED LISTS
   --------------------------
   Bullets within the application are automatically square and
   red in color. This is done using an image of a red square.
   To change this, you will need to replace the image "bullet.gif"
   which can be found in the 'images' directory.
   
   If you would like to use the format of bulleted lists but
   prefer not to have the red square next to the text, you can
   remove the bullet image by adding a class attribute to the
   list with a value of "noBullet".
   
      E.g., <ul class="noBullet">
               <li>Bullet 1</li>
               <li>Bullet 2</li>
               <li>Bullet 3</li>
            </ul>

   Bullets can also be bold and    

   Numbered lists default to decimal numbering. It is also
   possible to create a numbered list using lowercase Roman
   numerals. To do this, add a class attribute to the list
   with the value "roman".
   
      E.g., <ol class="roman">
               <li>Bullet 1</li>
               <li>Bullet 2</li>
               <li>Bullet 3</li>
            </ol>


   ADDITIONAL HTML ELEMENTS
   --------------------------
   All other HTML elements will be displayed in their default
   format as defined by the browser. Additional styles
   relating to to the layout and application display can
   be found in the cascading style sheet files found in
   the "css" directory.
   


*************************************************************
*    VII.) ADVANCED CUSTOMIZATION
*************************************************************
NOTE: THE FOLLOWING SECTION ADDRESSES ISSUES OF A HIGHLY
      TECHNICAL NATURE. IT IS ASSUMED THAT THE READER HAS
      AN UNDERSTANDING OF WEB TECHNOLOGIES AND THE PHP
      PROGRAMING LANGUAGE.


   FILE INCLUDES
   --------------------------
   All files used in this application share a set of
   common files, found in the "includes" directory.
   This includes the following:
   
      browserCheck.php - Used to identify the
                         current browser.

      fairnessScale.php - Used for the fairness scale found
                          on a number of pages within the
                          "Evaluation Tool".

      footer.php - Used to maintain a consistent footer on
                   the bottom of every page in the application.

      header.php - Used to maintain a consistent header on
                   the top of every page in the application.
                   This file is also used to determine the
                   progress as displayed on the progress bar
                   and to create the "Back" and "Next" links.

      properties.php - Used to store the list of files included
                       in the application and the name of the
                       application (defaults to "Fair Use
                       Evaluator".

      sessionHandler.php - Used to begin the session and to process
                           all form submissions. It should be noted
                           that form submissions are stored in
                           the session to help maintain state
                           across the different pages within
                           the application.


   ADDING/MODIFYING FORM ELEMENTS
   ----------------------------------------------------
   The "Evaluation Tool" includes a number of forms, all
   of which are submitted when moving from one page
   to another.
   
   In order to add a new form element, you will
   need to create the form element on the desired
   page using standard XHTML.
   
   Below is an example of a form field enclosed in
   a table. Note that PHP code is incorporated
   to ensure that previously entered values
   are reprinted if the user returns to a previously
   viewed page.
   
   <tr>
      <th class="labelCell">
         <label for="newFormField">
            Your Job Title:
         </label>
      </th>
      <td>
         <input type="text" name="newFormField" id="newFormField" value="<?php if(isset($_SESSION["newFormField"])) echo deslashify($_SESSION["newFormField"]); ?>" />
      </td>
   </tr>
   
   After creating the form element, you will need to
   modify "sessionHandler.php" to ensure that the application
   processes your new form field appropriately.
   The code to process the previous example would be as follows:
   
   <?php
   
      if(isset($_POST["newFormField"]))
         $_SESSION["newFormField"] = $_POST["newFormField"];

   ?>



   ADDING/MODIFYING THE PDF CREATION SCRIPT
   ----------------------------------------------------
   PDF creation is done using the FPDF class, released under
   a permissive license without any restrictions. More
   information about FPDF, including class documentation
   and tutorials, can be found at http://www.fpdf.org/.


