IT350 - Web and Internet Programming
Fall 2005

Final Project

Introduction

In this final project you will work as a team, employing all the HTML, CSS, JavaScript, and CGI skills you have learned this semester, to design and build an online survey/quiz system. Your goal is to produce an attractive, functional, maintainable, and innovative system. The best system will be deployed for use in IT350 next year (and likely many other courses).

Overall Requirements

When finished your system will need to have at least five publicly viewable scripts:

· survey.pl – Generates a survey/quiz HTML form that is filled out by the student.

· submit.pl – This script is called when the student hits “Submit”. It records the student’s responses in a file for later use, along with a timestamp. For a quiz, it may also grade the quiz and inform the student of his/her score and/or correct answers, depending upon the quiz settings.

· summary.pl – A password-protected script (intended for instructor use only) that displays a summary of the survey/quiz responses. This should summarize:

o Which students (and how many) have taken the quiz/survey. For each student, there should be a link to the detail page for that student’s response (see detail.pl below).

o For multiple choice questions, the percentage of students choosing each response.

o For free text questions, a list of all the responses that were provided.

o There should be an appropriate link to grades.pl (see below).

· detail.pl – A password-protected script that displays the responses of an individual student. It’s up to you how to present this information. One nice approach might be to re-display the survey/quiz form and somehow indicate the answers given by that student. Note that still must work even for an anonymous survey.

· grades.pl – A password-protected script that displays a list of all students, one per line, sorted by alpha number. Each line should contain the student's alpha, lastname, then their grade for the quiz. This should be output as a plain text file, one student per line.

Other requirements:

• The server side functionality shall be implemented with Perl.
• The quiz/survey that is presented to the user must be dynamically generated based on reading in a text file (e.g., quiz1.txt) that specifies what questions to ask, correct answers (if any), and any options for the quiz/survey. You are encouraged to define your own options, but options that you must support are:
• dueDate: Enforcing a “due date” – submissions not accepted after this time.
• anon: By default, all quizzes/survey should ask for an alpha code and a last name and insist that they be provided, unless the quiz/survey is explicitly set to be anonymous.
• Your site must be well-documented! You will be required to provide a brief overall writeup of how your site works. In addition, each file should have a brief comment at top on what it does, and comments within the code.
• You should define functions and share code appropriately. Don’t have the same code in multiple files!
• The site must be able to handle multiple distinct quizzes/surveys simultaneously – e.g. an IT350 quiz and survey that are both open for submissions at the same time.
• You must use file-locking to ensure that the results file cannot be corrupted by two students submitting responses to the same quiz simultaneously.
• Password protection – where required, this can be implemented in multiple ways. It must be possible for the instructor to view the results without typing a password every time. You could do this with cookies, or with having the password specified as part of the URL.
• You should make use of CSS to make your pages attractive and consistent looking.
• You should use JavaScript to provide useful checking of forms before they are submitted to the server. For instance, the JavaScript should not allow a survey to be submitted if the alpha number is missing, and should warn the user if they did not answer a question.
• When complete, your site must have a webpage, index.html, that demonstrates your capabilities. At a minimum, this page should have:
• A link to a quiz that will be automatically graded after being submitted.
• A link to an anonymous survey containing multiple choice and free response questions.
• Links to the summary pages (summary.pl) for each quiz/survey.
• Grading should work as follows:
• In the input file, each question may or may not have a correct answer specified. If not, that question is not graded. Note that a quiz may have some graded and some ungraded questions. Questions with a correct answer are also expected to have a number of points associated with them.
• “Correct” answers may be given either for multiple choice or “free text” questions. For multiple choice, the correct answer will be given as an index, starting at 0. For free response, the correct answer is a string. In this case a response is correct if it exactly matches the correct answer, ignoring whitespace and capitalization.
• You must add at least one innovative feature to your system that was not specifically required.
• A final report and presentation will be required. More details to be provided later.
• All HTML web pages must be constructed using Notepad or a similar text-only editor. The use of programs such as Microsoft Word, Microsoft Frontpage, DreamWeaver, ColdFusion, Mozilla Composer, etc. will be considered an honor offense.

What You Start With

We are giving you a few things to help you get started.

• A sample input file that defines a quiz. You do not have to use this format, but it is a suggestion as to how you might proceed. This file defines some options, then defines the questions to be asked (and their correct answer).
• Starter code: We’re providing a fair amount of starter code to help you with the basic data structures. This starter code will also let different team members get started on different parts of the project, using the pre-defined data structures as an interface between you. The starter code has the following files:
• OLD: survey_test.pl – demonstrates how to use the remaining starter code. This file creates two surveys, some associated questions, and prints them out. You should understand well how this file works.
  NEW: instead of survey_test.pl, you may find it easier to use helpers.pl and helpers_test.pl. These two files contain the same code, but I’ve modified the functions (like createDummyQuiz(), printSurvey() etc. so that they will work as a module. See helpers_test.pl for how to call these. The actual functions are in helpers.pl – to use them copy helpers.pl into your directory and add require “helpers.pl” to the top of your file where you are trying to use them.
• You probably don’t need to understand how the remaining starter code works – at least not initially. However, it is all commented and you should be comfortable scanning through it to discover what functions there are and what inputs/outputs they use.
• survey_struct.pl – In the code, we refer to either a quiz or a survey as a survey object. This file defines functions to create and manipulate a survey. A survey is just a collection of questions, and some options. You don’t really need to know how this is implemented, just how to use it. For instance,
  $survey = surveyCreateNew();
  surveySetDueDate ($survey, "15-Nov-2005 17:00");
• question_struct.pl – defines functions to create and manipulate an individual survey question. Example use:
  $q2 = questionCreateNew();
  questionSetType($q2, TYPE_MULTIPLE_CHOICE());
  questionSetPrompt($q2, "True/False: Java and JavaScript are very different languages");
• response_struct.pl – defines functions to create and manipulate the response of one student to a survey or quiz. You’ll probably want to create an array to hold many such responses.
• Sample input file: here is an example quiz1.txt file. You can use this if you like, or modify it to make it easier to parse or to add more options. Once your have that working, try survey1.txt.
• You will be provided with some new web space (will call it your T: drive), to store your team’s work on. The final deliverable should be all there.

General Approach

Getting the site to work will involve getting several perl files and some text files to work effectively together. Here is an example of how this should all work:

• The instructor creates a text file defining a quiz, say quiz1.txt.
• The instructor provides the students with a link to the quiz. This is a link to survey.pl, with the name of the quiz (quiz1.txt) as part of the URL.
• A student clicks on the URL, invoking survey.pl. This script uses read_survey.pl to read in and parse quiz1.txt (storing the result in a survey object). It then generates the quiz form and some JavaScript to perform basic validation before submission.
• When the student clicks submit, JavaScript validates the answer, then submits the result to submit.pl. submit.pl grades the quiz, possibly displays results, then appends the submitted response, with a time stamp, to quiz1-results.txt.
• Later, the instructor can view the results in a web page by accessing summary.pl, detail.pl, or grades.pl. Each of these scripts will first use read_survey.pl to read in quiz1.txt into a survey object and check that the provided password is valid. If so, it then uses read_results.pl to read quiz1-results.txt into an array of result objects and display appropriate results to the instructor.

Notice a few things about the above steps:

• You need to define a format for two text files (in this case, quiz1.txt and quiz1-results.txt), though an example is provided for files like quiz1.txt.
• Multiple Perl scripts all need to parse and deal with these files. To simplify this, you should write read_survey.pl and read_results.pl. Each of these files should read in a file and return a handle to an Perl object (or an array) that other code can use without knowing the details (e.g., using the survey object provided in survey_struct.pl).
• If you strictly follow this method, you can debug and test almost all of your project before you get read_survey.pl and read_results.pl working. For instance, survey_test.pl has functions that create a dummy quiz and a dummy survey –you can use these to test survey.pl and submit.pl, independent of read_survey.pl.

Project Roles

Each of you will have leadership responsibility for some part of the project. This doesn’t mean you must do all the work for that part; it just means you are responsible for making sure it is done right. Part of your individual grade will depend on how well you lead your team in this regard. The roles are:

• Team Lead – you are in charge of ensuring that work is distributed in a fair manner to each team member and that the work is getting done. You are the primary point of contact with the instructor (though anyone can ask for help) and should ensure that project reports and presentations are prepared as needed. The Team Lead should either be the one to apply changes to your shared web space, or else delegate this to someone else.
• Appearance Manager – you ensure that an appropriate stylesheet is created and used to create a consistent and attractive look across the whole site.
• Quality Control Manager – responsible for ensuring the system is functionally efficient, error free, and secure. The Quality Control Manager taxes the system to expose its weaknesses and then interfaces with other team members to devise a solution. Additionally quality controllers must ensure code is well commented and that similar tasks utilize the same code (unless there is a Reusability Manager, below).
• Interface Manager – ensures that different pieces of the site can work together via well-defined interfaces. There are two primary interfaces: 1.) the syntax of files like “quiz1.txt” and “quiz1-results.txt” (e.g. scripts that read and write quiz1-results.txt must agree on what this looks like). 2.) the interfaces to the Perl objects that are given to you – like survey and question. The latter interfaces are given to you but the Interface Manager is responsible for making sure they are used in a consistent way and in applying any changes that you need to these interfaces (e.g., if you need to add a new “multiple attempts permitted” option to the survey object.
• Reusability Manager (only for teams with 5 students) – ensure code is well commented and that similar tasks utilize the same code. Also responsible for the overall description of the site that will be part of some project reports.

Tips

• Start early! This is a big project and you can get expect to experience some unexpected delays or problems that may require changes.
• It will easiest if you keep all your Perl files in your top-level W: or T: directory (rather than inside a ‘project’ folder).
• Make regular backups of your files!!! Especially when you have something working, make a backup in case it breaks later and you don’t know why. Do this for both those files you specifically write and your site as a whole.
• Do most of your testing and development using your old W: drive. Then copy things to your project space (P: drive) that you are ready to share with others. But be sure to communicate and have a plan so you don’t overwrite things that someone else has done! The Team Lead should coordinate this.
• You will be writing a lot of Perl code to generate HTML. Make use of the HTML helper functions like h1(), th(), etc.
• If your code is not working, first run perl –w –c from the command line (like you did in in Lab10) to ensure there are no syntax errors. Then, add extra print() commands to see what parts of the program are executing and what the values being used are.
• At some point you may need to modify starter code like survey_struct.pl. You don’t need to fully understand this. For instance, to add a new field “backgroundColor” to the survey object, you would need to do three things:
• Define a new constant SURVEY_INDEX_BACKGROUNDCOLOR, like SURVEY_INDEX_DUEDATE, but assigning it the next available index.
• Create new function surveySetBackgroundColor() and surveyGetBackgroundColor(), mimicking the analogous functions surveySetDueDate() and surveyGetDueDate().

Extra Credit

Your project must meet the basic requirements. Then do any of the following for additional credit. You may also propose other ideas; talk to your instructor.

1. Create an online quiz/survey generator – e.g. a tool to help produce text files like quiz1.txt. This script should allow the instructor to dynamically create a quiz/survey by adding one question at a time. It should also support modifying existing questions and should be able to load existing quizzes/surveys for modification.
2. Add the ability for a quiz to refer to another file, say “it350-2001-students.txt” that lists the alphas and last names of all students in the course. Then modify the summary results to also show those that have not submitted, and modify the grade results to show an incomplete for students that have yet to submit something.
3. Add the ability to send mail to students with their grade after submitting a quiz. Email may be tough with our server; talk to your instructor if you are interested.
4. Make a new version of grades.pl to creates a summary text output, one line per student, but where each line contains the grades for a whole set of quizzes (e.g., so one page would the grades for all students, all quizzes). Be sure to handle missing quizzes appropriately.
5. Add support for showing separate results/grades based on which section a student is in.

Grading

50% of your individual grade will be a group grade based on the following

1. Meeting projecting milestone and status reports
2. Functionality and correctness – The site should operate as advertised without error.
3. Visual Appearance & Consistency – including good use of CSS.
4. Maintenance – Ensure the site is well organized, requires minimal maintenance, and can be expanded by someone else who doesn’t know your code.
5. Documentation – Ensure all pages are documented. General documentation covering the system’s layout and design is also required.
6. Creativity – The requirements above require at least one system innovation not specified in the project writeup. This and any other innovations will count towards your creativity grade.

The other 50% of your individual grade will be administered by your teammates.

1. Your assessment of your peers shall be based on effort, knowledge, team work, and professionalism.
2. You will assign two grades to each member of your group – one based on their overall contribution, one based on their leadership in their assigned role. Your instructor will later tell you details about what grades you may assign (e.g., don’t expect to give everyone an A).

Deliverables

All items due at start of class unless otherwise noted.

• Fri Nov 18 by COB. Email status report to instructor: team name, role of each student

• Wed Nov 23. One page description of overall system plan due. Also must include description and examples of text files like (quiz1.txt and quiz1-results.txt) that you will use.
• Thurs Dec 1. Email status report to instructor.
• Mon Dec 5. Thurs Dec 8 Complete Projects due, presentations in class.
1. Report: At this time you should submit a written project report, which includes
1. A cover sheet with your team names and project members. Describe your innovative feature, any extra credit, and any requirements that you did not meet. Note that your system must work (and will be tested) with quiz input files that your system has not seen before (though that have the same kind of syntax as your other input files).
2. A listing of the “role” that each person played (from the assigned set of 4 or 5 roles) AND a description of what each person did – who created each file, who tested?
3. Some brief documentation of how the overall system works. This should be no more than a few pages. How does the password authentication work? How does submit.pl know what quiz is being taken, and how does it enforce the due date? What is the format of the quiz results file? How do multiple Perl files all get information about the grades/correct answers of the students.
4. All of your files should also be documented, also described in the requirements above.
2. Presentation: One or some members of your group should be prepared to demonstrate your system to the class. This should involve using your T:/index.html file to show how a student takes the quiz and what the instructor sees. Be sure to mention your required innovative feature and any extra credit. You’re not expected to prepare Powerpoint slides but if you wish place them in your T: drive for easy access.
3. Feedback and Peer Grading: You will be provided with a form for giving feedback and grading the members of your team. You will turn this in individually – peer grades are anonymous. If you are absent for any reason on Thursday, make certain to get this form to the instructor somehow by the end of the day or earlier.
   Grading details: You will assign grades to each member of your team, both for their overall performance and for their performance in their designated leadership role. If your team has 3 other people, then you will have a total of 30 points to assign for the overall category, and 30 points for the “role” category. Your final grade for the project will then be calculated by scaling (up or down) your team grade (from the instructor) by your average peer grade. So if the instructor gives your team 85%, and if everyone in your group gives everyone else a 10, then everyone gets 85%. On the other hand, if your average peer grade is higher than a 10, your score would be greater than 85%. You will not grade yourself.

• Wed Dec 7. Project revisions due

Additional Hints/Clarifications (updated as the project progresses)

• By default, variables inside a function are global.  This is almost never what you want and will cause lots of bugs.  You should declare every variable in a function to be local by using 'my'.  I promise that this will spare you pain later!
• How to connect to your shared T: drive –
1. From a File Explorer, pick ToolsàMap Network Drive.
2. Select Drive T:
3. For Folder enter one of the following:
1. Prof. McDowell’s sections: use \\cs-websrvr.cs.usna.edu\www.it350sectXXXXteamX.it.cs.usna.edu
   (use 2001 or 6001 for section. Teams are 1, 2, 3, 4, or 5)
2. Cmdr. Logue’s section: use\\cs-websrvr.cs.usna.edu\www.it350teamX.it.cs.usna.edu
4. Click on “different user name”. Enter cs-websrvr\mXXXXXX for user name. Use the same password you use for your W: drive.
5. Click on OK, then Finish. You should be ready go. Your files are web accessibly using the www address given in step 3 above.
• Error: too many arguments for… Perl technically requires that you place an ampersand in front of calls to functions that you define, but normally lets you omit them. If however, you call a user-defined function from inside a file that you include with “require” you’ll usually need to include the ampersand (or else you get a “too many arguments for …” error. When in doubt, it doesn’t hurt to use the ampersand. Example:
  OLD: questionSetPoints($question, $points);
  NEW: &questionSetPoints($question, $points);
• Don’t use die() function. This makes it hard to debug because the error message won’t appear when you run through the webserver. Example:
  OLD: if ($error) { die “Error in parse routine”; }
  NEW: if ($error) { print “Error in parse routine”; exit (1); }
• Hints on parsing input: Once you’ve read in a line from, say, quiz1.txt, you will need to split it up into it’s different parts. A very useful function for this (and other parsing tasks) is split(). This function splits a given string into multiple parts whenever it sees a match from some pattern you give it. The results are stored in an array. Here are some example uses:
  @myArray = split (/:/, $aLine); (splits the line wherever there is a colon)
  @myArray = split (/\|/, $aLine); (splits the line wherever there is a vertical bar |. The vertical bar is a special character for patterns so we have to escape it like this \| )
  @myArray = split (/\s*\|\s*/, $aLine); (split the line wherever we see a vertical bar. Here the pattern also matches any whitespace (\s*) before or after the vertical bar, so that whitespace doesn’t show up in the resulting array. This can be very useful!)
• Don’t forget to escape special characters. A number of characters like * | \ etc. have special meaning inside a pattern match. If you want to test for them, you’ll need to escape them using a backslash as was done in the hint on parsing input above.
• Plan so you can debug using the command line perl. It’s much easier to debug if you can run your program through the command line. You definitely want to do this for checking syntax (perl –c –w) but where possible you also want to do this for actually executing the program (perl –w). For scripts that accept CGI parameter input, you can debug by explicitly passing in values on the command like this:
  perl –w survey_test.pl "filename=survey1.txt&password=catdog "
  (Placing quotes around the arguments is recommended – sometimes matters) For more info on this debugging technique, see http://search.cpan.org/dist/CGI.pm/CGI.pm#DEBUGGING
• Use helpers.pl instead of survey_test.pl – see the new files under “What You Start With” above.
• Bug in starter code function printResponses(). In helpers.pl (or survey_test.pl), the code originally had these two lines:
  sub printResponses {
  my ($responses) = @_;
  This is incorrect, because ‘responses’ is an array. For some reason this code usually works, but sometimes does not, so you should fix it. The correct code is (change a $ to @):
  sub printResponses {
  my (@responses) = @_;
  This bug is now fixed in the online starter code. If you copied printResponses() to some other file, don’t forget to fix this bug there also.
• Using 2-D arrays in Perl. You don’t necessarily need this, but I had some questions so here is an example.