IT350 - Web and Internet Programming

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 poll/quiz system. Your goal is to produce an attractive, functional, maintainable, and innovative system. The best system may 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.

Definitions

• Survey – A form that poses questions to a student, collects the response to each question, and stores the responses for later. For our purposes, a survey is always EITHER a quiz or a poll.
• Poll – a “survey” where none of the questions have a correct answer, so no grade is given
• Quiz –a “survey” where at least one question has a correct answer, so a grade is computed
• NOTE: either a quiz or a poll may be anonymous (described in more detail later). This is NOT a factor that distinguishes a quiz from a poll.

Overall Requirements

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

· survey.pl – Generates a poll/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 poll/quiz responses. This should summarize:

o Which students (and how many) have taken the poll/quiz. 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 one particular student. It’s up to you how to present this information. One nice approach might be to re-display the poll/quiz form and somehow indicate the answers given by that student. Note that detail.pl must still be able to 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 (plain text, not HTML), one student per line.

Other requirements:

• The server side functionality shall be implemented with Perl.
• The poll/quiz 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 poll/quiz. 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: (not required for three person groups) By default, all polls/quizzes should ask for an alpha code and a last name and insist that they be provided, unless the quiz/poll is explicitly set to be anonymous via this option.
• minutesLimit: (not required for three person groups) 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). Displaying the timer with JavaScript is a very nice touch, but not required.
• Multiple submissions (not required for three person groups): unless the survey is anonymous, a student should only be allowed to take the survey once. Check this when the survey is submitted – if the alpha matches an alpha that you already have stored for this survey, then refuse to store the results and show an error. This must be the default behavior, but a nice extra touch would be to add a new survey option (defined in the quiz definition file) that instead allows multiple submissions if the instructor so allows it.
• 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 (esp. to describe what each function does).
• You should define functions and share code appropriately. Don’t have essentially the same code in multiple files!
• The site must be able to handle multiple distinct quizzes/polls simultaneously – e.g. two IT350 quizzes that are both open for submissions at the same time.
• 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 (this should not be hard, talk to the instructor if you are confused).
• 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 poll containing both multiple choice and free response questions.
• Links to the summary pages (summary.pl) for each quiz/poll.
• For quizzes, grading should work as follows:
• In the input file for a quiz, each question may or may not have a correct answer specified. If not, that question is not graded. 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 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.

NOTE: you can download all of these files here (unzip to the TOP of your W: drive). You can also individually save these files but if so you’ll have to rename each Perl file from a .txt extension to a .pl extension.

• Sample input files: an example quiz: quiz1.txt and an example poll poll1.txt: These files defines some options, then defines the questions to be asked (and their correct answer, for the quiz). You must use this general syntax, but you may make additions or changes if helpful.
• 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 a poll and a quiz (using some functions defined in helpers.pl), an associated “response” object, 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 poll or a quiz as a survey object. This file defines functions to create and manipulate a survey. A survey is just a collection of “question” objects, 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 “question” object. 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. You’ll probably want to create an array to hold many such responses.
• 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 – Required Startup Tasks

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. You must do this individually, but get help from your team as needed:

1. Download all of the starter code and unzip it into your root W:\ directory (not in a subdirectory).
2. Did I mention NOT to use a subdirectory like “Lab09” or “project”. You want all this in your top-level W:\ directory.
3. 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.
4. helpers_test.pl has comments describing 3 warm-up tasks. Do each one. Demonstrate to the instructor when finished. Team leaders should help ensure everyone completes this.
5. 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.
6. You now know the basics. Proceed with your assigned part of the project. Be sure to keep an eye on 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:

• 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 a parameter that is 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 (in HTML) 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 an appropriate format for the results files (in this case, quiz1-results.txt). And, if your team changes the format for files like quiz1.txt and poll1.txt, you need to be very clear about what the format is (write this down!). Suggestion: for the results file, you probably want to have just one line per student, with the responses to different questions separated by some special character.
• Multiple Perl scripts all need to parse and deal with these text files. To simplify this, you must write read_survey.pl and read_results.pl. Each of these files should read in a file and return a handle to a Perl object (or an array) that other code can use without knowing the details of the file format (e.g., using the survey object provided in survey_struct.pl). You don’t directly invoke these files from the browser – 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 poll –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 led 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 milestones, 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.
• Interface Manager – (for three person groups, this person is actually the Quality Control 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”. Why is this so important? Because scripts that read quiz1-results.txt must agree with scripts that write quiz1-results.txt 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.

Tips

• Don’t sit around waiting for others before you work on your part. By using the sample code provided, you should be able to mostly work even without your teammates being finished. Review the “General Approach” above.
• But don’t wait till the last minute before you try and get things working together. 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!
• Start early! This is a big project and you can expect to experience some unexpected delays or problems that may require changes.
• 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. Your teammates will not be happy if you accidentally clobber their code on the T: drive!
• You will be writing a lot of Perl code to generate HTML. Make use of the HTML helper functions like h1(), th(), etc. to simplify this. WARNING: tr() does not create a table row – use Tr() instead (capital T) – this is one exception to how these functions are named.
• If your code is not working, first run perl –w –c from the command line (like you did in Lab08) 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/poll generator – e.g. a tool to help produce text files like quiz1.txt. This script should allow the instructor to dynamically create a quiz/poll by adding one question at a time. It should also support modifying existing questions and should be able to load existing quizzes/polls for modification.
2. Add the ability for a quiz to refer to another file, say “it350-4001-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 require students to login with some password before they can take a quiz.
4. 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.
5. 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 be the grades for all students, all quizzes). Be sure to handle missing quizzes appropriately.
6. Add support for showing separate results/grades based on which section a student is in.

Grading

Your individual grade be calculated from:

• 20% -- a group grade based on the timeliness and quality of interim project milestones (see below)
• 50% -- a group grade based on the following portions of your final submission:

1. Functionality and correctness – The site should operate as advertised without error.

2. Visual Appearance & Consistency – including good use of CSS.

3. Maintenance – Ensure the site is well organized, requires minimal maintenance, and can be expanded by someone else who doesn’t know your code.

4. Documentation – Ensure all pages are documented. General documentation covering the system’s layout and design is also required.

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

• 30% -- an individual grade based on anonymous feedback from 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.

Milestones/Deliverables

For interim milestones, the milestone is late if not delivered promptly by the deadline (COB – by midnight, or promptly at the start of lab). The penalty for a late milestone is 25% per day.

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

• Mon Nov 3 by COB. 1-2 page report on your overall system plan and interfaces due. Note: this is a formal, graded activity that you should take seriously. This report should include a description and examples of text files like (quiz1.txt and quiz1-results.txt) that you will use, as well as information about interfaces between different modules (e.g. function prototypes and description, parameter names). Think of it this way: in order for someone in your group to do their part of the project, what specifics do they need to know about decisions that have been made about how other parts of the project work? Anything one file needs to know about how some other file in your project works, it should be in this report. You don’t need to repeat requirements from this document, but describe the key decisions and interfaces between the different parts of your project.
• Thurs Nov 6 by START OF LAB. 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).
• Thurs Nov 13 by START OF LAB. 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.
• Wed Nov 19 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 (accurate description of such missing features is worth some credit). 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 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 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: All members of your group should be involved in demonstrating 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)

• You must “use strict” in every Perl file. This will save you pain, so do it right away, from the beginning!
• 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. Bottom line: just always use the ampersand, and you will be happier.
• 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 its 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).
• How to connect to your shared T: drive – map to \\cs-websrvr.cs.usna.edu\www.it350teamX.cs.usna.edu$ (substitute your team number for the X).