Homework System

August 3, 1998
The WWW based homework system is now available to anyone interested, in two forms. The first appraoch is to download all of the scripts, gifs and web materials from my server and install them locally. If you can do that, I would strongly recommend that approach. The second method ,and the simplest, is to utilize the materials on my server. I will be happy to provide an account and disk space for those interested in doing so. Regardless of which method you choose (or to be safe you can do both), please read all of the following material before proceeding. I know that everyone always says that and I know that most of you, like I do, generally ignore such admonitions. In this case, given what you must do in terms of configurations, etc, it really is important to understand what's involved. Getting these materials to run properly on your server requires a number of related operations be done exactly as needed. It is also very strongly recommended tthat interested individuals "play" with the materials available here to see whether they are appropriate for your programs. In addition, you should print this document, since it contains details on installation and configuration. Installing the materials is not difficult, but it's also not automatic and does require some knowledge of how Unix/Linux works as well as total system access.

Structure of the Homework System

The system is designed to provide individualized problem sets across a very broad range of topics. It is not a tutorial system. My basic philosophy is that a quality textbook should be the core instructional material. The pages utilize a combination of HTML and Javascript to generate individualized questions. There are no "question banks". In general, the questions are generated on the fly and will not repeat. Further , input is normally numeric, not multiple choice. Fully installed, this system has four major parts. Given that individuals who want to use the materials may not want to use the entire setup and, also, to ease installation, I have packaged the four pieces separately. They are:

The Lecture Help Pages-this set is easily installed simply by untarring or unzipping the files. In addition, these pages do not require a webserver, so they can be run as a standalone on any computer using only the browser. If you choose, feel free to redistribute these materials to your students. As of today, the revised "Lecture Help" pages are undergoing final debugging and should be available by the end of the week.

Homework Pages-identical to the Lecture Help materials with the added capability of submitting results to the instructor. These pages require the cgi scripts noted below, a Perl interpreter and specific permissions and directory structures on the server.

CGI scripts. Since HTML and Javascript are not capable of writing to the server disk, in order to run the homework pages with full interactivity, you need to install a few Perl scripts, again provided below, on your server. You also need to set up permissions and directory structures. In other words, you need system administrator support. Before you go to the trouble to download the homework pages and the scripts, make sure you're going to be able to install things properly by talking with your system administrator. Details on the installation/configuration needs are given in a later section.

Graphics files. If you wish to be able to run the pages which involve structures, symmetry, etc, you ned to download and install the struture data base. This consists of about 1000 gif and jpg files. Without them, you will not be able to run the following pages: Rand S, Hybridization, Naming Organic Fragments, Direct or Inverse, and Symmetry.

Execution

The following is brief description of the the operation of a homework page and should provide some insight into the systems structure. As noted above, you are strongly encouraged to test our system here so that you will know it is designed to operate. A typical homework session, from start to finish is as follows:

The user selects a web page from the listing.
The page then generates and scores a set of problems. If needed, graphics are chosen, at random, from one of the supporting graphics library.
Through the completion of the last problem, only HTML and Javascript are been involved.
When the student submits the results, the Perl based cgi-scripts are called. The first script, "hw_turnin.cgi" acts as a preliminary point wherein the student's name is entered and the instructor selected. This is a very important script as it is the one which must be modified, as noted below, to display your instructor list. If you are able to structure your installation as directed below, this is the only modification you will have to make.
After the student selects the name and instructor, the main data processing script, "homework_processor.cgi" is called. This script writes the results to the database of the selected instructor and sends a verification form back to the student. This script is supported by homework.setup.cgi

Directory structures

Installation will be fairly simple if your server has a directory structure identical to what is present here at CSUDH, as shown below. Beyond the diagram below, the Perl interpreter must be located in "user/bin/perl" which is the "normal" location. If your Perl interpreter is not in that directory, you will have to modify the cgi scripts to show the proper path to the Perl interpreter. The following assumes that you are running Unix (or Linux) and that you have a partition called /home used for the user installed applications. Further, you must either have system administrator privileges or coordinate this installation with the system administrator. If you are running a different operating system, you should be able to adapt this material.

   /home/httpd
		|
		 /html
		|   /homework(contains the homework web pages)
		|   /lecture_help(contains the lecture help web pages)
		|   /strucures(each of the following contains graphics files)
		|		/butyls
		|		/equations
		|		/hybrids
		|		/rands
		|		/symmetry
		|	
		 /cgi-bin
		|	/homework(contains the scripts)
		|
		 /savedata
			/ a directory for each of the faculty to receive student data
			  the directory must contain a file called homework.data

If your structure is not exactly as above, some modifications of the files will be needed. Regardless of your overall system directory structure, if you can configure your directory structures such that the path from the homework pages to the cgi-scripts can be written as a relative path "../cgi-bin/homework/", the installation should be easy.

Permissions

Having proper file permissions is key to getting the scripts to execute properly. If you're familiar with running this type of material, you're well aware of this fact. Otherwise, discuss the issue in advance with the system administrator. Make sure that you will be able to have the needed structure and permissions before attempting an installation. When you unzip the materials, as described below, they should install with the following ownership and permissions:

rwxrwxr_x nobody  george  file information

You may have to set up a group called "george" and make yourself a member of the group. The use of nobody is standard as the web server normally runs as nobody. When you set up the needed directories (above) you should have them with these same ownership and permissions. Once you've got the system running smoothly, you can modify the groups to suit your own situation.

The archive files

The files have been archived with tar and zipped with gzip. They should unpack properly with the "tar xzvf tarfile" command. To simplify the installation, the system sections have been placed in separate archives. There are three files (the fourth, with the lecture help files will be available shortly), which can be downloaded by using the link at the bottom of this page. You may either put them into a temporary directory on your server, or put them directly into the appropriate final destination. If you choose the second option, homework.tar.gz should go into "../html/homework/", scripts.tar.gz should go into "../cgi-bin/homework/" and graphics.tar.gz goes into "../html/structures/". Once the files have been placed in the appropriate final directory, unarchive them as noted above. The homework and script archives will simply install the files. The graphics archive will also set up the subdirectories sub to /strucutures/ needed for the various graphics libraries.

Final Configurations

There are a number of possibilities once the files are unarchived. First, quickly check the permissions and ownerships on the files and directories and make any needed changes. Then follow any of the steps below, appropriate to your actual situtation.

Perl interpreter not in "/usr/bin/perl/". In this case you need to modify the first line in hw_turnin.cgi and homework_processor.cgi to reflect the proper location of the Perl interpreter. One note about modifying the cgi scripts. Make certain that if you modify them on a local computer and then FTP them to the server that you use ASCII mode not binary for the transfer.
No Directory Differences
If your directory structure is exactly as shown above, you do not have to modify any of the files to test your installation. Thus, skip to the "Final Test" section, below.
Directory differences
There are several levels of potential differences with directory structures. None of these is will prevent the system from being used. However, a considerable amount of individual file editing may be needed if your local directory/file structures are very different from the preferred ones. Thus, you should make every effort to set up your directory structures as recommended before embarking on revising the files. If your dir structure is different, one or more of the following cases should apply. The directory names and relative paths are important because of the the interactions between the web pages, the scripts and the data files. For example, when the student submits the results the first script is called with the statement ACTION= ../cgi-bin/hw_turnin.cgi". This line occurs in every homework page and, thus, each page will have to be modified or execution is not possible. If you have to modify the web pages, it is strongly recommended that you modify only a single page and the accompanying scripts and verify the correctness of the changes by going to "Final Test".
- Relative Paths same as above, but directory names are different. If the relative paths are the same, then variation in directory names is not a problem, since the relative paths used by the system only contain names for directories you set up as part of the installation. The only real exception to this would be if your cgi-bin directory is not called cgi-bin. If so, that is the case, read the next section which summarizes all of the possiblly needed changes. Otherwise, proceed to Final Test.
- Relative paths different, but names the same. There are three points at which relative paths are used in the system:
  1. Each web page contains a single form tag which appears immediately after the instruction section in the html portion of the page. Within that form tag is the statement : ACTION = "../cgi-bin/homework/hw_turnin.cgi." This provides the path to the first cgi script to be executed. If your path is different from the one noted above, modify this statement.
  2.homework_processor.cgi contains the path from the cgi-scripts to the datafiles. Line 160 in homework_processor.cgi contains the relative path from the cgi-bin/homework/ directory to the datafiles:
  $location_of_database="../../savedata/".$form_data{'instructor'}."/homework.data"
  Change line 160 (actually, just the "../../savedata/" portion) to fit your actual path.
  3. homework.setup.cgi may need modifcation. In that file, line 151 contains the relative path from the cgi-bin/homework/ directory back to the homework main page. Currently it reads:
  "../../homework/hwintro.html">Back to Homework Pages If "../../homework/ is not the relative path from cgi-bin/homework/ your "/html/homework/" modify that line appropriately.
- Neither paths nor names as preferred.
  Very strongly recommended that you work with your system administrator to get the relative paths between the homework files and the cgi-scripts the same. Otherwise, follow the basic procedure in the preceedinf section to make the necessary changes. Proceed to Final Test.

Final Test

To test your installation you must set up a test directory. When the scripts execute, the program looks for a directory sub to "../httpd/savedata/" with the same title as the instructor's name. The "hw_turnin.cgi" script you've downloaded has only one instructor possible, test. Add a directory called "test" below "../httpd/savedata/" on your server and put a file called homework.data in it. Make the permissions and ownerships of the directory and file per usual. One this is done, call any of the homework pages, hit the "New Problem" button a few times (answer the questions, if you wish). Then, press "Submit". Enter your name at the next screen and then press "Submit" again. If your installation is correct, you'll get a verification page. If that happens, you have a complete and proper installation. If you had to make a modification in the ACTION statement in a web page, you need to now modify all of the pages in the same fashion. When all of the needed modifications to the cgi-bin and web pages are complete, add your own instructors' list to hw_turnin.cgi, described below. If the system does not execute properly, there are many problem sources, but the most likely are permissions and directories. Feel free to contact me, if you can't resolve the problem on your own.

Adding Instructors

The instructor list is easily added with a basic editing of hw_turnin.cgi. Line 21 in that file reads :
@instructors = ("test");
Modify it to contain your actual list of instructors. For example at CUSDH, our line 21 is:
@instructors = ("Lyle", "Martinez", "Reilly", "Pappatheodorou", "Seely", "Sturm", "Wiger", "Wilk");
Then, sub to /savedata/, setup a directory for each of your instructors with a name identical to the name on the Line 21. Make sure that each of your instructors is a user on your system and that the ownerships/permissions are:

rwxrwxr-- nobody username file information etc

Then put an empty file called homework.data in each directory, again with the above permisions. You now should be able to fully test the system and should do so.

Final Notes

Copyright-All of the materials provided here are protected by copyright but are freely distributed with the following provisions. No fee may be charged for their use or for access to the files. Files may be modified without restriction. Use by any commercial or for profit entity without express written permssion of the author is prohibited.
Redistribution-users are welcomed to redistribute the materials in any form, including the source files and this document, provided any such redistribution follows the copyright notice, above.
Browsers-unfortunately, executable code is browser sensitive. These pages execute best with Netscape 3.x and 4.x.
Feedback-feedback is strongly encouraged. I only ask that is is done in the same spirit that the materials are provided. It is my hope that the WWW will eventually become the truly cooperative environment it should be. If you have a successful installation, please let me know, so I can set up a link to your site. A section on this server at News and Updates will be maintained for downloading corrections and new pages.
Adding to the system-the design of the system makes it fairly easy for others to write their own pages and add to the system. I hope that users will do just that. I will shortly be providing a guide on how that can be done.

Downloading the Files

If you've read this far, you're probably ready to download the files. Follow the link below to the download area and follow the instructions there.
I've read it all-Please let me have the files

Getting an account on this system

If you'd like an account on our system, simply use the email link below to request one and I will set it up and send you the needed info. In your email, provide your name, a username and a preferred password. Request an account