IT350 - Web and Internet Programming
Fall 2006

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).

This course has taught you the basics of web programming and how to refer to documentation when necessary. Some features of the project will require you to access additional information to complete the requirements.

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 will also grade the quiz. The script may then 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.
• minutesLimit: The maximum number of minutes permitted to complete this quiz. If the time limit is exceeded, the quiz should be recorded but a late submission must be recorded somehow (along with the actual time taken). You must also use JavaScript to show a countdown of how much time is left (enforcing time limit required for everyone. Displaying the timer nice but not required for 4-person groups).
• requireLogin: (not required for 4-person groups) By default, all quizzes/surveys simply ask for the alpha/name on the same page as the quiz. If requireLogin is true, however, you must first direct students to a page where they provide their alpha and password, which is checked against a file. After successful login, they are directed to a page to complete the survey/quiz, and you must use a cookie or some other mechanism so that a) they don’t have to enter their name again and b.) you must have performed login before you can reach the survey/quiz.
• 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. two IT350 quizzes that are both open for submissions at the same time.
• (not required for 4-person groups) 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 (for the instructor, to protect the results and grades) – 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 must make use of CSS to make your pages attractive and consistent looking.
• You must 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 (see below). 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:
• helpers_test.pl – Start with this file. It demonstrates how to call some other sample code, which is all in helpers.pl. This file creates two surveys, some associated questions, and prints them out. You should understand well how this file works. You should use this file as a starting point for web-viewable files like survey,pl and submit.pl that you build.
• helpers.pl – This code is a “module” – it’s not intended to be run directly by itself, but to be used by other files (helpers_test.pl has a “require” statement at the top that references this file). This file has the actual code to create some questions, add them to a survey, etc. You should understand well how this file works. This file is both to help you understand how to use other starter code (below) AND to provide useful functions like createDummyQuiz() to help you with testing pieces of your code separately from the rest..
• You probably don’t need to understand the details of 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 (we’ll call it your T: drive), to store your team’s work on. The final deliverable should be all there.

Getting Started

Everyone on the team needs to understand how the basics of the code work. On your first actual in-lab day, do some team planning and then do the following. Doing this individually is recommended, but get help from your team as needed:

1. Above are 5 .pl files. Download all of them to your root W:\ directory (not in a subdirectory). Rename each one to have a .pl extension (e.g. change helpers.txt to helpers.pl)
2. From the command line run “perl –w helpers_test.pl”. Take a look at the output, then read carefully through helpers.pl and helpers_test.pl to see how it works.
3. helpers_test.pl has comments describing 3 warm-up tasks. Do each one. Report to your team leader when finished. Team leaders should help ensure everyone completes this, then report to the instructor when everyone has accomplished it.
4. Once all the above is working, make sure it still works when using the web-server. Fetch http://www.mXXXXXX.it350.cs.usna.edu/helpers_test.pl . You should see reasonable results in HTML.
5. You now know the basics. Proceed with your assigned part of the project. Be sure to keep an eye of the required deliverables/milestone dates.

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 (in the case where students do NOT need to login before taking the quiz):

• 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). You don’t directly call these files – instead other files “require” them and use their functions. Thus, they are modules. See helpers.pl for an example of making a module – especially read the comment at the very end of the file.
• 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 expect to experience some unexpected delays or problems that may require changes.
• You want to be able to work independently, but as soon as possible try to interface your code with others. You are very likely to encounter unexpected issues due to different assumptions about how that interface should work!
• Do not make a ‘project’ folder. Instead, you should keep all your Perl files in your top-level W: or T: directory. That way you can run from the webserver or from the command line without changing any paths.
• 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 team space (T: 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.The address for the team drives is \\cs-websrvr.cs.usna.edu\www.it350teamX.cs.usna.edu$
• 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 Lab09) 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 the code to do this. For instance, to add a new field “backgroundColor” to the survey object, you would need to do two 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 (perhaps combined with your password file). 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.

Deliverables

All items due at start of class unless otherwise noted.

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

• Mon Nov 13 by COB. 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 Nov 16. In lab, demo to your instructor that you have basic form generation working for the dummy quiz (shoot for parsing a real file like quiz1.txt, but not required).
• Mon Nov 20. In lab, demo to your instructor a complete end-to-end system: you can read a real quiz from an arbitrary file, generate a form from this, have a student submit it, save the responses with submit.pl, and then have detail.pl working so you can call up the response of any student that has completed the quiz. It doesn’t have to look good or have all features working, but you need to have all these parts working together.
• Thurs Nov 30 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 demo day, make certain to get this form to the instructor somehow by the end of the day or earlier.
   Grading details: TBA.

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 – TBA
• 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
• Using 2-D arrays in Perl. You don’t necessarily need this, but if you do here is an example.
• The provided code has a number of debug features that sanity-check the arguments that you provide. If you get an error about a “bad magic number”, this either means you are calling one of these functions wrong (e.g. forgot to provide the ‘question’ object) or you are passing an invalid object (e.g., the ‘question’ object you are passing was never initialized).