ICE @ Georgia Tech: AP Practice Exam

Software Design Specification

Version 3.0 Final26 July 2005

CS3911 Team II

RevisionsVersion Primary

Author(s)Description of Version Date

CompletedDraft 1 Lisa Jordan

Daniel OsieckiChad HansenChase Peeler

First draft of Design Document 22 June 2005

Draft 2 Lisa JordanDaniel OsieckiChad HansenChase Peeler

Revision of Design after mockup review anddata design revision.

12 July 2005

Final 3 Lisa JordanDaniel Osiecki

Final revision after draft grading and sponsor re-view.

26 July 2005

Page i

Contents

REVISIONS......................................................................................................................... I

CONTENTS........................................................................................................................ II

1 INTRODUCTION...............................................................................................................11.1SYSTEM OVERVIEW....................................................................................................... 11.2DESIGN MAP................................................................................................................ 11.3SUPPORTING MATERIALS................................................................................................ 11.4DEFINITIONS AND ACRONYMS..........................................................................................1

2 DESIGN CONSIDERATIONS............................................................................................... 22.1ASSUMPTIONS............................................................................................................... 22.2CONSTRAINTS............................................................................................................... 22.3SYSTEM ENVIRONMENT.................................................................................................. 22.4DESIGN METHODOLOGY................................................................................................. 22.5RISKS AND VOLATILE AREAS.......................................................................................... 2

3 HIGH LEVEL ARCHITECTURE..........................................................................................33.1OVERVIEW....................................................................................................................33.2RATIONALE...................................................................................................................33.3INTERACTION.................................................................................................................3

4 LOW LEVEL DESIGN...................................................................................................... 44.1 STATIC HTML........................................................................................................... 44.2 DYNAMIC SCRIPTS........................................................................................................4

4.2.1 Data Object Representations..................................................................................... 44.2.2Session Management................................................................................................... 54.2.3 HTTP Request Handlers.............................................................................................54.2.4 Utility Scripts..............................................................................................................64.2.5 Database Interface..................................................................................................... 84.2.6 Dynamic HTML Scripts..............................................................................................8

4.3 DATABASE...................................................................................................................9

5 USER INTERFACE DESIGN............................................................................................. 105.1COMMON PAGE ELEMENTS........................................................................................... 105.2PAGE FLOW................................................................................................................10

5.2.1Anonymous Users...................................................................................................... 105.2.2Students..................................................................................................................... 115.2.3Teachers.................................................................................................................... 115.2.4Administrators...........................................................................................................12

5.3COMMON PAGE ELEMENTS & MENUS............................................................................125.3.1Administrator Header............................................................................................... 125.3.2Administrator Menu.................................................................................................. 12

Page ii

5.3.3Teacher Header.........................................................................................................135.3.4Teacher Menu............................................................................................................135.3.5Student Header.......................................................................................................... 145.3.6Student Menu.............................................................................................................145.3.7Footer........................................................................................................................ 14

5.4PAGE MOCKUPS..........................................................................................................155.4.1Administrator Login.................................................................................................. 155.4.2Teacher Login............................................................................................................165.4.3Student Login.............................................................................................................175.4.4Forgotten Password.................................................................................................. 185.4.5Edit Account Information..........................................................................................195.4.6Edit Account Information..........................................................................................205.4.7Edit Account Information..........................................................................................215.4.8Create Class.............................................................................................................. 225.4.9Add Students.............................................................................................................. 235.4.10Edit Class................................................................................................................ 245.4.11Add Teacher............................................................................................................ 265.4.12Add Administrator................................................................................................... 275.4.13Exam Settings.......................................................................................................... 285.4.14Practice Exam......................................................................................................... 295.4.15Practice Exam......................................................................................................... 305.4.16Exam Summary........................................................................................................315.4.17Review Practice Exam.............................................................................................325.4.18Practice Exam Review.............................................................................................335.4.19Performance Summary............................................................................................ 345.4.20Class Exam History.................................................................................................355.4.21Class Performance Summary.................................................................................. 365.4.22Browse Questions....................................................................................................375.4.23Question Approval...................................................................................................385.4.24Add Question........................................................................................................... 395.4.25Edit Question...........................................................................................................41

6IMPLEMENTATION NOTES...............................................................................................436.1TESTING.....................................................................................................................436.2DOCUMENTATION........................................................................................................ 436.3CODE CONVENTIONS....................................................................................................43

7APPENDIX A - USE CASES ............................................................................................ 44

Page iii

1 Introduction

This document specifies a software system that satisfies the requirements set forth in theSoftware Requirements Specification for the ICE @ Georgia Tech AP Practice Exam. Thissystem intends to satisfy all A-level requirements while following best coding practices.

1.1System OverviewThe AP Practice Exam Database is an existing online system that allows students and teach-ers to answer practice questions for the AP Computer Science (A/AB) Exam. The purposeand objective of this project is to extend and improve upon the existing practice system,adding new functionality to help students and teachers receive greater benefits from using thesystem. New functionality will include processes such as the ability to log in, save exam re-sults and track student statistics.

1.2Design MapThis document contains a detailed specification for the design of the new features of the APPractice Exam Database system. Attached are UML diagrams including use cases and mockups as well as an Entity-Relationship diagram for the database.

1.3Supporting MaterialsNo supporting materials are included at this time.

1.4Definitions and AcronymsAP – Advanced PlacementCSS - Cascading Style Sheets, a language used for styling webpagesDBA – Database AdministratorHTML – Hypertext Markup Language, a language used for writing webpagesHTTP – Hypertext Transfer ProtocolMD5 – Message Digest v 5, a hashing algorithmRFC – Request For Comment (http://www.faqs.org/rfcs/ )SPMP – Software Project Management SpecificationSRS – Software Requirements SpecificationURL – Uniform Resource LocatorW3C – World Wide Web Consortium, a standards checking community

( http://www.w3.org/ )

Page 1

2 Design Considerations

2.1AssumptionsIt is assumed that all data currently contained in the AP Exam Database is intact, correct andcomplete. Any errors present in the data before system implementation will remain in thesystem unless specifically recognized during testing. We are also assuming that all currentfunctionality performs to the customer’s satisfaction, with the exception of the specially not-ed speed issues and login capabilities.

2.2ConstraintsThe system must perform at a rate of less than one second per page load in 99% of cases.Additionally, the system must accommodate 100 concurrent users. Both of these perfor-mance issues will be considered in the system design. As the project will be ongoing afterthe completion of the current set of requirements, the implementation must be completedwith excellent documentation and in a format that is extensible by others.

2.3System Environment

2.3.1 Hardware EnvironmentThe system must run efficiently and within the performance constraints on the samemachine that current functionality exists upon. The current server exists upon Mana-tee which runs Windows Server 2003 with a 448 MHz Pentium III Processor and 128MB of RAM. The client interface is a web application that must be viewable in allmajor web browsers, including Internet Explorer, Netscape, and Mozilla. Otherbrowsers, such as text-based systems, may be compatible, though not necessarilysupported.

2.3.2 Software EnvironmentThe approved software environment specifies an Apache web server using the PHPHypertext Processor to provide dynamic content and data, as managed by a MySQLdatabase.

2.4Design MethodologyDesigns for the system will be created by progressive analysis of mock-ups derived from usecases and client input. Code structure and function will be modeled in UML, while the sup-porting data design will be created using an Entity-Relationship methodology.

2.5Risks and Volatile AreasThe system will contain some personal information about users, including full name, pass-word and email address. This information will need to be transferred and stored in a securefashion. This risk area includes user login and account management.

Page 2

3 High Level Architecture

3.1OverviewThe AP Practice Exam System uses the Client-Server architecture model. Any standardscompliant web-browser will be able to connect to our web-server to use the application.The client’s role is to access, download, parse the html code that the server produces andsend user data and responses back to the server.

The server is where the majority of the application’s functionality lies. It authenticates userlogins, presents exams to the user, and determines if the response from the user is correct.The server will also allow teachers to track the progress of their students. Since the server iswritten in PHP, there will be no compatibility issues with the client browsers unlikeJavascript and other client-side languages.

3.2RationaleThe Client-Server architecture is the most rational approach for this application. The appli-cation has a database that needs to be accessed by a large number of people from many dif-ferent locations. The Client-Server approach is the simplest solution to this problem. Thereare four reasons for this choice:

1. Many people already have experience with similar web applications and therefore,the learning curve will be kept to a minimum.

2. The Client-Server architecture eliminates the need to consider user platforms. 3. The time to develop a web-server application is much shorter than writing a stan-

dalone application, allowing for greater focus on implementation of functionality.4. It will not be necessary for the user to install any software to use the system.

3.3InteractionThe following diagram shows the interaction between the highest-level system components.

Page 3

4 Low Level Design

This section outlines the internal low level design of the system. There are three basic mod-ules: the static portions of the HTML serviced to clients and interpreted on client system, thescripts that generate any dynamic portions of client HTML and transform client HTTP re-quests into database operations, and the database itself.

4.1 Static HTML

This module is the most simple. This includes the template to be filled with data by the dy-namic scripts described in section 4.2. This module will take the form of W3C standardHTML formatted with a W3C CSS stylesheet in compliance with all W3C recommendations.

There will be a single static page for each user interface page as described in section 5.2.These static pages will define all formatting of data and all accessory content that is static innature.

Other static content such as images will be stored centrally and reused in standard HTMLpractice from all pages.

4.2 Dynamic Scripts

This module constitutes the bulk of the system and is roughly divided into six parts whichare closely interdependent. All of this module will be implemented in PHP, thought thesescripts may generate HTML as an output function.

4.2.1 Data Object RepresentationsAll data collected from HTTP requests, sent to the database, received from the database, orused in the generation of dynamic portions of HTML will be represented as objects. See thefollowing UML class diagram for the layout of these classes.

Page 4

4.2.2Session ManagementThis module will utilize the built-in session module in PHP to track user access to the siteand provided the needed functionality for cross-request data persistence while using HTTP.

This module will also implement all user account functionality such as login tracking, privi-leged management, and security. The request handler described in section 4.2.3 will alwaysstore any data to be passed between successive requests in the session variables provided bythis module unless that data may be stored in the database.

4.2.3 HTTP Request HandlersAll information will be communicated to the system via HTTP requests. This module willanalyze these requests to verify the data contained in them, convert it to object form, and callthe appropriate responding page in the UI.

This module will determine what data is being sent to the system and verify that data usingthe utility scripts described in 5.2.4. If any data is not verified, it will re-present the UIscreen that originally requested it, commanding that screen to indicate an error.

The nature of the data returned to the system is determined by the post-values sent by eachUI page (see section 5.2). Each of these pages will mark the data sent back to the next pagein the page flow sequence via a data token.

Page 5

On receipt of valid data, this module will immediately save to the database any appropriatedata, after it has been converted into object form.

The final role of this module is to ensure that the correct response UI page is presented to theuser, and that that page is passed all data needed from the incoming request.

This module will implement all security features of the system, most importantly validatingall data in a request to prevent security breach.

4.2.4 Utility ScriptsThis module consists of scripts to:

• Validate incoming request data• Perform statistical analysis• Generate random sets of questions• Grade exams• Any other non-trivial operation

These utility functions will be performed by helper objects that will be the core subject of theunit tests implemented in the system. All data passed in and out of these utilities will be inobject form if representable as such and as simple parameter, otherwise.

The following functions have been defined as necessary for required functionality. Otherfunctions may be defined as required for proper modularity.

Validation

escapeQuotes(text)Takes the text from any text box and adds an escape character before any quotes.This methods will be a primary means of implementing security on the web inter-face, preventing malicious insertion of SQL into data fields.

escapeSelectedHTML(text)Takes a block of input HTML (for a question) and removes any HTML tags that arenot any of the following:

• B• I• TT• BRvalidateContents(textbox)Ensures that text has been entered for required fields. Returns true or false.

validateSelected(dropdown)Ensures that an item has been selected for required dropdown menus. Returns trueor false.

validateText(text)Ensures that text entered into a textbox is in correct, textual format. Returns true orfalse.

validateDate(text)

Page 6

Ensues that dates entered into a textbox are in the correct format. Returns true orfalse.

validateNumber(text)Ensures that text entered into number-only textboxes are in the correct format. Re-turns true or false.

validateEmail(email)Ensures that a valid email address is entered. Returns true or false.

verifyPassword(password1, password2)Ensures that when a new password is entered and re-entered, the two entries are thesame and meet password criteria for length and character classes. Returns true orfalse.

validateStudentLogin(email, password)Checks a student’s login. Returns true or false and an error message.

validateTeacherLogin(state, school, teacher, password)Checks a teacher’s login. Returns true or false and an error message.

validateAdministratorLogin(administrator, password)Checks an administrator’s login. Returns true or false and an error message.

Data Parsing

parseClassDataFromCSV(csvText, format)Attempts to parse class CSV data input by a user according to the ruleset specified.Returns an array of Student objects upon success or false and an error message uponparse failure.

Data Display

All of the following functions create the necessary HTML code to display a combobox "select" object for the corresponding data enumeration.

fillStates(dropdown)

fillCounties(state, dropdown)

fillSchools(state, dropdown)

fillClasses(state, dropdown)

fillTeachers(state, school, dropdown)

fillAdministrators(dropdown)

fillTitles(dropdown)

fillMonth(dropdown)

fillDay(dropdown)

fillYear(dropdown)

fillQuestionCatagories(dropdown)

Page 7

fillAuthors(dropdown)Functionality

generateQuestionSet()Called at the beginning of an exam to generate a random set of questions. Thesequestions shall be of the level and number that the user specifies. The questions se-lected shall be from a balanced set of categories, unless the user specifies otherwise,in which case the questions shall be from the user-specified categories. Additional-ly, for each question, generateAnswerSet() is called. Finally, this function stores thequestions and answer sets for access throughout the exam.

generateAnswerSet()Called at the beginning of an exam for each question in a question set, this functionset the order of the answers for the question, randomly assigning the letters “a”through “e” to one correct and four incorrect answers.

Statistics

calculateScore()Calculates and returns the number and percentage of correct and incorrect questionsfor a student. May be accessed at the end of an exam or when viewing old exam re-sults.

getClassStatistics(class)Returns the number of exams, total questions, questions per exam and percent cor-rect for a specified class.

getStateStatistics(state)Returns the number of exams, total questions, questions per exam and percent cor-rect for a specified state.

4.2.5 Database InterfaceThis module will be responsible for placing data in the database that originates in objectform and for collecting data from the database into object form. This module will manageconnections to the database, protect the database, and make use of the utility scripts de-scribed in section 4.2.4 for all operations other than transforming data from SQL query/resultinto object form.

4.2.6 Dynamic HTML ScriptsThis module will make available functions to create appropriate HTML to represent resultdata in a form that may be inserted into the static portions of the HTML pages that imple-ment the UI for the system. These functions will be called by the response handlers oncethey have determined the appropriate response and generated all required data in the form ofobjects.

Page 8

4.3 DatabaseAll data for the system that is to be stored persistently and securely will reside in thedatabase. The following diagram outlines this data:

This data will be stored using the following relational schema:

Page 9

Page 10

5 User Interface Design

5.1Common Page ElementsEach page shall have a heading depending upon which type of user they are. This headingshall appear at the top of every page with no exceptions. The heading will include the ICElogo, the Georgia Tech College of Computing logo and a representation of the most oftenused menu options.

5.2Page Flow

5.2.1Anonymous Users

Page 11

5.2.2Students

5.2.3Teachers

Page 12

5.2.4Administrators

5.3Common Page Elements & MenusThe following screen representations suggest a possible layout for each page, as reviewed bythe sponsor.

5.3.1Administrator HeaderThe following page division will appear at the top of all pages sent to a correctly logged-inadministrator:

5.3.2Administrator MenuFile Name: menuAdministrator.html

Page 13

5.3.3Teacher HeaderThe following page division will appear at the top of all pages sent to a correctly logged-inteacher:

5.3.4Teacher MenuFile Name: menuTeacher.html

Page 14

5.3.5Student HeaderThe following page division will appear at the top of all pages sent to a correctly logged-instudent:

5.3.6Student MenuFile Name: menuStudent.html

5.3.7FooterEvery page will also display the following footer:

Page 15

5.4Page Mockups

5.4.1Administrator LoginFile Name: loginAdministrator.html

Pre-values:

Name TypeadministratorList array(string)

Post-values:

Name Type ValidationadminName Select not nullpassword Password length > 0, [a-zA-Z0-9]+

Page 16

5.4.2Teacher LoginFile Name: loginTeacher.html

Pre-values:

Name TypestateList array(string)

countyList array(string)schoolList array(string)

teacherList array(string)Post-values:

Name Type ValidationteacherState Select not nullteacherCounty Select not null

teacherSchool Select not nullteacherName Select not null

password Password length > 0, [a-zA-Z0-9]+

Page 17

5.4.3Student LoginFile Name: loginStudent.html

Pre-values: none

Post-values:

Name Type ValidationstudentEmail Textbox [0-9a-zA-Z.]+@[0-9a-zA-

Z.]+.[a-zA-Z]+

password Password length > 0, [a-zA-Z0-9]+

Page 18

5.4.4Forgotten PasswordFile Name: forgotPassword.html

Pre-values: none

Post-values:

Name Type ValidationemailAddress Textbox [0-9a-zA-Z.]+@[0-9a-zA-

Z.]+.[a-zA-Z]+

Page 19

5.4.5Edit Account InformationFile Name: editTeacher.html

Pre-values:

Name TypetitleList array(string)

currentTitle stringfirstName string

lastName stringemailAddress string

Post-values:

Name Type Validationtitle Select Not null

firstName Textbox Not nulllastName Textbox Not null

emailAddress Textbox [0-9a-zA-Z.]+@[0-9a-zA-Z.]+.[a-zA-Z]+

newPassword Password length = 0 OR [a-zA-Z0-9]+

verifyPassword Password Equals newPassword

Page 20

5.4.6Edit Account InformationFile Name: editStudent.html

Pre-values:

Name TypefirstName string

lastName stringemailAddress string

Post-values:

Name Type ValidationfirstName Textbox Not null

lastName Textbox Not nullemailAddress Textbox [0-9a-zA-Z.]+@[0-9a-zA-

Z.]+.[a-zA-Z]+

newPassword Password length = 0 OR [a-zA-Z0-9]+verifyPassword Password Equals newPassword

Page 21

5.4.7Edit Account InformationFile Name: editAdministrator.html

Pre-values:

Name TypetitleList array(string)

currentTitle stringfirstName string

lastName stringemailAddress string

Post-values:

Name Type ValidationTitle Select Not null

firstName Textbox Not nulllastName Textbox Not null

emailAddress Textbox [0-9a-zA-Z.]+@[0-9a-zA-Z.]+.[a-zA-Z]+

newPassword Password length = 0 OR [a-zA-Z0-9]+

verifyPassword Password Equals newPassword

Page 22

5.4.8Create ClassFile Name: createClass.html

Pre-values:

Name TypetitleList array(string)

suggestedStartDate datesuggestedEndDate date

Post-values:

Name Type ValidationclassName Textbox Not null

startMonth Select Not nullstartDay Select Not null

startYear Select Not nullendMonth Select Not null

endDay Select Not nullendYear Select Not null

Page 23

5.4.9Add StudentsFile Name: addStudents.html

Pre-values:

Name TypeclassList array(string)

Post-values:

Name Type Validationclass Select Not null

students Textarea parseClassDataFromCSV()succeeds

nameFormat Radio Not null

Page 24

5.4.10Edit ClassFile Name: editClass.html

Pre-values:

Name TypeclassList array(string)

selectedClass Classstudents array(Student)

Post-values:

Name Type Validationclass Select Not nullclassName Textbox Not null

startMonth Select Not nullstartDay Select Not null

startYear Select Not nullendMonth Select Not null

endDay Select Not nullendYear Select Not null

selectedStudent Hidden Used when Edit Info or Re-move Student is pressed

Page 25

Page 26

5.4.11Add TeacherFile Name: addTeacher.html

Pre-values:

Name TypetitleList array(string)

stateList array(string)selectedState string

countyList array(string)selectedCounty string

schoolList array(string)Post-values:

Name Type ValidationTitle Select Not nullfirstName Textbox Not null

lastName Textbox Not nullemailAddress Textbox [0-9a-zA-Z.]+@[0-9a-zA-

Z.]+.[a-zA-Z]+

teacherState Select Not nullteacherCounty Select Not null

teacherSchool Select Not null

Page 27

5.4.12Add AdministratorFile Name: addAdministrator.html

Pre-values:

Name TypetitleList array(string)

Post-values:

Name Type ValidationTitle Select Not null

firstName Textbox Not nulllastName Textbox Not null

emailAddress Textbox [0-9a-zA-Z.]+@[0-9a-zA-Z.]+.[a-zA-Z]+

Page 28

5.4.13Exam SettingsFile Name: beginExam.html

Pre-values:

Name TypecategoryList array(string)

Post-values:

Name Type ValidationnumberQuestions Textbox isNumber

examLevel Radio ("A","AB")examType Radio ("balanced","custom")

categoryXWeight

('X' is a category ID)

Radio ("none","some","many")

Page 29

5.4.14Practice ExamFile Name: examQuestion.html

Pre-values:

Name TypequestionNumber int

totalQuestions intquestion Question

Post-values:

Name Type ValidationquestionID Hidden Valid question ID

selectedAnswer Radio ("A","B","C","D","E",null)

Page 30

5.4.15Practice ExamFile Name: answer.html

Pre-values:

Name TypequestionNumber int

totalQuestions intquestion Question

answerGiven AnswerPost-values:

none

Page 31

5.4.16Exam SummaryFile Name: examSummary.html

Pre-values:

Name TypecurrentExam GeneratedExam

Post-values: none

Page 32

5.4.17Review Practice ExamFile Name: reviewQuestionList.html

Pre-values:

Name TypecurrentExam GeneratedExam

Post-values: none

Page 33

5.4.18Practice Exam ReviewFile Name: reviewQuestion.html

Pre-values:

Name TypequestionNumber int

totalQuestions intquestion Question

answerGiven AnswerPost-values:

none

Page 34

5.4.19Performance SummaryFile Name: studentSummary.html

Pre-values:

Name Typeexams array(GeneratedExam)

classExams array(GeneratedExam)stateExams array(GeneratedExam)

numPastExams intPost-values:

Name Type ValidationnumPastExams Textfield isNumber()

Page 35

5.4.20Class Exam HistoryFile Name: classSummary.html

Pre-values:

Name Typeexams array2d(GeneratedExam) by studentnumPastExams int

Post-values:

Name Type ValidationnumPastExams Textfield isNumber()

Page 36

5.4.21Class Performance SummaryFile Name: stateSummary.html

Pre-values:

Name TypeexamsByClass array2d(GeneratedExam) by classexamsByLevel array2d(GeneratedExam) by levelnumPastExams int

Post-values:

Name Type ValidationnumPastExams Textfield isNumber()

Page 37

5.4.22Browse QuestionsFile Name: browseQuestion.html

Pre-values:

Name TypecategoryList array(Category)

authorList array(Teacher)questions array(Question)

Post-values:

Name Type Validationcategory Select Not null

author Select Not null

Page 38

5.4.23Question ApprovalFile Name: viewQuestion.html

Pre-values:

Name TypependingQuestion Question

Post-values:

Name Type ValidationquestionID Hidden valid Question ID

Page 39

5.4.24Add QuestionFile Name: addQuestion.html

Pre-values: none

Post-values:

Name Type ValidationexamType Radio ("A","AB","both")

shortDesc Textbox Not nullquestion Textarea Not null

correctAnswer Textarea Not nullcorrectAnswerExplanation Textarea Not null

incAnswerX (X:1-4) Textarea Not nullincAnswerX (X:1-4) Textarea Not null

categoryY (Y: valid cat. ID) Checkbox none

Page 40

Page 41

5.4.25Edit QuestionFile Name: editQuestion.html

Pre-values:

Name Typequestion Question

Post-values:

Name Type ValidationexamType Radio ("A","AB","both")

shortDesc Textbox Not nullquestion Textarea Not null

correctAnswer Textarea Not nullcorrectAnswerExplanation Textarea Not null

incAnswerX (X:1-4) Textarea Not nullincAnswerX (X:1-4) Textarea Not null

categoryY (Y: valid cat. ID) Checkbox none

Page 42

Page 43

6Implementation Notes

This section contains information about additional implementation and design constraintsthat apply to the project as a whole. These considerations are a result of the preceding choic-es in system architecture and environment or are required by the SRS that this document re-sponds to.

6.1Testing

The requirements for the system specify full unit testing of all system code. The system willbe designed in a modular nature such that concise, related unit tests can be created for eachfile of software code. This includes both the database module and the HTTP request handingmodule. Unit testing will be implemented using the PHPUnit API.

Of the low-level packages, dynamic scripts (see section 4.2) in particular must be modular-ized into functions of relative simplicity than may be atomically tested.

6.2DocumentationSystem code must be documented fully to ensure system maintainability and extensibility. Inparticular, the object and database API produced (see sections 4.1 and 4.2) must be fully doc-umented in a manner that can be published outside of source code context. This sort of doc-umentation will be produced using PHPDocumentor.

6.3Code Conventions

Variables, classes, and files will be named using "javaStyle" conventions in all cases, exceptwhere otherwise required by environmental constraints. Pages of HTML that form the userinterface will have the extension "html", all other script pages will have the extension "php".

All dynamic code (see section 4.2.6) that must appear inline with static presentation data (seesection 4.1) will be encapsulated into functions wherever possible. The appearance of PHPcode within actual HTML files will be minimized to the greatest extent possible.

Page 44

7Appendix A - Use Cases

The design of the new functionality for the AP Practice Exam System will be derived largelyfrom use case scenarios. These scenarios are delineated below, as requested by the sponsor.As the tasks are all simple and straightforward, it is the decision of this team that no furthermodeling is needed for front end design at this point.

Task: A teacher logs in.Preconditions: The teacher exists in the database and is associated with their correct state,county and school.User Actions: The teacher navigates to the first login page. The teacher selects their state,then their county, then their school. The teacher clicks “Continue”. On the next page, theteacher selects their name from the dropdown list and enters their password. The teacherclicks “Login”.

Return Logins: When the teacher visits the second login page, they may bookmark this page.When they return the next time, their choices for state, county and school will have beensaved, so that the teacher may only visit the second page, choose their name and enter theirpassword.

System Actions: On the first login page, the system fills the state dropdown list with theavailable state choices. Once a state is selected, the system redirects to a new page with thestate dropdown list and a county dropdown box filled with the counties for that state. Once acounty is selected, the system redirects to a page with the state and county dropdown list, aswell as a dropdown list of schools for that state and county. When the user clicks“Continue” the system redirects them to a new page with only a dropdown list of teachers atthe selected school. Once the teacher selects their name, the system checks the validity oftheir password. If the password is correct, the system directs the user to the teacher’s mainmenu. If the password is incorrect, the system returns the teacher to the login page (contain-ing the list of teachers and a password box) and displays a message that says "incorrect pass-word".Postconditions: The teacher is logged in.

Task: A student logs in.Preconditions: The student exists in the databaseUser Actions: The student navigates to the login page. The student enters their username andpassword and clicks submit.System Actions: The system checks that the student exists in the database and that the pass-word is correct. If so, the system directs the user to the student’s main menu. If not, then thesystem returns the student to the login page and display a message that says "incorrect user-name or password".Postconditions: The student is logged in.

Task: A teacher manages their accountPreconditions: The teacher is logged in.User Actions: The teacher chooses the Edit My Info option from their menu header. Theteacher may edit their title, first name, last name, email, or password. The teacher can editany combination of these items, or choose not to make any changes at all. The teacher thenchooses to save the changes.System Actions: The system retrieves and displays the teacher’s account information. The

Page 45

system updates the teacher’s account information if they choose to change it. If the systemdetects that the teacher entered an invalid email (a string not of the formatstring@string.string) it will return the teacher to the Edit Account Information page with amessage that states "Please enter a valid email of a form such as name@domain.com". If thesystem detects that the string entered in the "verify password" field does not match the one inthe "new password" field, the teacher will be returned to the Edit My Info page and show themessage "Passwords do not match, please try again" If the system detects that the first nameand/or last name fields are left blank, the teacher will be returned to the Edit My Info pagewith an error stating "Please Enter a First Name" and/or "Please Enter a Last Name" Postconditions: The user’s account information is updated if changes were made.

Task: A student manages their accountPreconditions: The student is logged in.User Actions: The student chooses the Edit My Info option. The student may edit their firstname, last name, email, or password. The student may edit any combination of these items,or choose not to make any changes at all. The student then chooses to save the changes.System Actions: The system retrieves and displays the student’s account information. Thesystem updates the student’s account information if they choose to change it. If the systemdetects that the student entered an invalid email (a string not of the formatstring@string.string) it will return the student to the Manage Account page with a messagethat states "Please enter a valid email of a form such as name@domain.com". If the systemdetects that the string entered in the "verify password" field does not match the one in the"new password" field, the student will be returned to the Edit My Info page and given themessage "Passwords do not match, please try again" If the system detects that the first nameand/or last name fields are left blank, the student will be returned to the Edit My Info pagewith an error stating "Please Enter a First Name" and/or "Please Enter a Last Name" Postconditions: The user’s account information is updated if changes were made.

Task: A administrator manages their accountPreconditions: The administrator is logged in.User Actions: The developer chooses the Edit My Info option. The administrator may edittheir title, first name, last name, email, or password. The administrator may edit any combi-nation of these items, or choose not to make any changes at all. The administrator thenchooses to save the changes.System Actions: The system retrieves and displays the administrator’s account information.The system updates the administrator’s account information if they choose to change it. If thesystem detects that the administrator entered an invalid email (a string not of the formatstring@string.string) it will return the administrator to the Edit My Info page with a messagethat states "Please enter a valid email of a form such as name@domain.com". If the systemdetects that the string entered in the "verify password" field does not match the one in the"new password" field, the administrator will be returned to the Edit My Info page and giventhe message "Passwords do not match, please try again" If the system detects that the firstname and/or last name fields are left blank, the administrator will be returned to the Manageaccount page with an error stating "Please Enter a First Name" and/or "Please Enter a LastName" Postconditions: The user’s account information is updated if changes were made.

Task: A student takes a 10-question, AB level examPreconditions: The student is logged inUser Actions: The student navigates to the “Take Exam” menu option. The student specifies

Page 46

the number of questions and level of the test. The student then chooses whether to take a bal-anced test or specify which categories of questions they would like along with the frequencyof each category. The student then clicks “Take Exam”. The student progresses through eachquestion and may choose an answer or leave the answer blank. The student finishes all ofthe questions and sees their results.System Actions:

Test Generation: The system generates a test with random questions of the specified lengthand level. If the student has chosen a balanced question set, an equal number of questionswill be chosen from each category. If the student has specified an advanced question set, thequestions shall be chosen based upon the selected categories and amounts the student select-ed. If the student enters a non-integer or integer less than one in the "number of questionsfield" they will be returned to the page and given an error message stating that only positiveintegers are valid inputs. If the student enters a number greater than the number of questionsin the test bank, the requested number will be changed to the number of questions in thedatabase and the test will proceed like normal. If the student fails to specify an exam type,they will be given questions from exam level "A" only. If the student fails to specify if theywant a balanced or custom question set, they will be given a balanced question set by default.If the student fails to select the amount of questions for a category after choosing customquestion set, the selection will default to "Some" for any unspecified categories.

Test Presentation: The system presents each question one at a time. On each page, the sys-tem shows a progress meter, saying how many questions out of the total have been answered.When an answer is submitted, the system shows the correct answer as well as incorrect an-swers, with an explanation of each. If the student continues without selecting an answer, thesystem will prompt the student to ensure that they wanted to leave the answer blank, and willallow the student to continue without an answer. The system stops presenting questions whenthe end of the exam is reached.

Test Completion: The system saves a record of questions presented and the student’s an-swers. The system will present a summary of the student’s exam, including number correctand incorrect. The system will also present the option of reviewing all answers or only in-correct answers.

Postconditions: A record of the test and the student’s answers is stored in the database. Thestudent may choose to review any exam s/he has completed.

Task: A teacher creates a questionPreconditions: The teacher is logged inUser Actions: The teachers chooses the Exams menu option. The teacher then chooses the“Add a Question” option. The teacher enters the question text, question summary, correct an-swer and explanation, incorrect answers and explanation (totaling 5 answers), question leveland question categories. The teacher submits the question.System Actions: The system presents the teacher with the create question interface. The sys-tem saves the question, answers, level and categories.

• If the teacher selected the text box and entered a new category, that category willalso be added to the list of categories in the database. The system marks the ques-tion as not approved.

Page 47

• If the teacher forgets to enter the question text, they will be returned to the enterquestion screen and given an error message that states "Please enter question text"

• If the teacher forgets to enter the correct answer text, they will be returned to theenter question screen and given an error message that states "Please enter the cor-rect answer text"

• If the teacher forgets to enter the correct answer explanation, they will be re-turned to the enter question screen and given an error message that states "Pleaseenter the correct answer explanation"

• If the teacher forgets to enter incorrect answer text for all four text boxes, theywill be returned to the enter question screen and given an error message thatstates "Please provide text for 4 incorrect answers."

• If the teacher forgets to enter incorrect answer explanation for all four text boxes,they will be returned to the enter question screen and given an error message thatstates "Please provide explanations for 4 incorrect answers."

• If the teacher forgets to select a question level, they will be returned to the enterquestion page and given an error message that states "Please select the level forthe question".

• If the teacher does not select any categories, then they will be returned to enterquestion screen and given an error message that states "Please select at least 1category for the question".

• If the teacher selects the checkbox for adding a new category, does not enter anytext, and does not select any other categories, they will be returned to the enterquestion screen and given an error message that states "please enter a name forthe new category".

• If the teacher selects the new category option and forgets to enter any text, but hasselected at least one other category, the add category option will be ignored andthe question added to the database like normal.

Postconditions: The question exists in the database, awaiting approval, but not appearing onexams.

Task: A teacher adds a new student Preconditions: The teacher is logged in.User Actions: The teacher chooses to add new students to a class. The teacher enters a list ofstudents’ information – first name, last name, username, email address in any order (1 entryper line, same order for each entry) and then selects the order in which the information wasentered and where commas should be included. The teacher submits the information.System Actions: The system presents the teacher with the add student interface. The systemmust parse each single line entry and add the first name, last name and email address to thedatabase. As each student is added, the student is emailed their account information alongwith a randomly generated password, and the teacher is sent the login information for their

Page 48

entire class. If the teacher does not enter anything in the add students area, they will be re-turned to the screen and given an error message that states "please enter at least one student".A sanity check will be performed to ensure that the order the teacher selects is the correct or-der by checking that the emails are of a valid syntax (string@string.string). If it is found thatthe column that is supposed to contain email addresses does not, the teacher will be returnedto the page and given an error message that states "please select the correct order for the stu-dent information and/or verify all information is entered in the same order" If the teacher for-gets to select which order they entered the information in, they will be returned to the screenand given an error message that states "please select the order in which information was en-tered". If the teacher enters the student information in a different order on different lines, itwill be treated in the same way as if the teacher selected the wrong order. If a student al-ready exists in the database, s/he shall not be re-added, and the teacher will receive a notifi-cation of any already-existing students after they submit.Postconditions: The student exists in the database.

Task: A student views an old testPreconditions: The student is logged in. User Actions: The student chooses to view an old exam. The student selects from the list ofold exams which one s/he would like the view. The student views the exam summary andthen chooses whether to view all questions or just incorrect questions. The student browsesthe list of displayed questions and chooses one to view, then views the entire question andanswers.System Actions: The system presents the student with a list of old exams. The system dis-plays the information from the exam the student chooses. The questions shall be in the sameorder, all correct and incorrect answer options will be displayed and the student’s answerchoice shall be marked for each question.Postconditions: None.

Task: An administrator approves a questionPreconditions: The administrator logs in. At least one non-approved question exists in thedatabase. User Actions: The administrator chooses the option to view pending questions. The adminis-trator chooses a question from the list. The administrator reads the question and its possibleanswers, then chooses to either approve, edit, delete, or not change the status of the question.System Actions: The system displays a list of pending questions. The system displays ques-tion details (full question text and all answers) for the question the administrator selects. Thesystem marks the question as approved if the teacher approves it, deletes the question if theteacher chooses to delete it, presents the edit question page if the administrator chooses toedit it, or leaves the question status unchanged if the administrators takes no action upon it.Postconditions: If the teacher approves the question, it exists in the database and may appearon exams. If the teacher does not approve the question, it exists in the database and may notappear on exams. If the teacher deletes the question, it will not exist in the database.

Task: An anonymous user takes a testPreconditions: NoneUser Actions: The user accesses the main test page and specifies the number of questionsand the level of the exam. The user answers each question.System Actions: The system generates a test of the specified length and level. The generated

Page 49

questions shall come from a variety of categories. The system presents each question one at atime. When an answer is submitted, the system shows the correct answer as well as incorrectanswers, with an explanation of each. The system stops presenting questions when the end ofthe exam is reached. If the user enters a non-integer or integer less than one in the "numberof questions field" they will be returned to the the page and given an error message statingthat only positive integers are valid inputs. If the user enters a number greater than the num-ber of questions in the test bank, the requested number will be changed to the number ofquestions in the database and the test will proceed like normal. While taking an exam, if auser does not select an answer, the system will treat the users response in the same way as ifan incorrect selection had been made.Postconditions: The user has completed the exam.

Task: A user browses questions by categoryPreconditions: NoneUser Actions: The user selects the category and/or author of questions they would like tobrowse. They view the list of questions in that category.System Actions: The system displays a list of approved questions from the category that theuser selects. If the user is sufficiently privileged, the system may also show not approvedquestions from this category.Postconditions: None

Task: An administrator edits a questionPreconditions: The administrator is logged in. User Actions: The administrator browses for the question they would like to edit. The ad-ministrator chooses the edit question option. The administrator edits the text of questions andanswers as s/he sees fit. The administrator submits the changes.System Actions: The system allows the teacher to browse for a question to edit. The systemdisplays the question and answers as editable text fields for the question the teacher selects.The system saves the changed fields.

• If the administrator selected the text box and entered a new category, that category willalso be added to the list of categories in the database.

• If the administrator deletes the question text, they will be returned to the edit questionscreen and given an error message that states "Please enter question text"

• If the administrator deletes the correct answer text, they will be returned to the edit ques-tion screen and given an error message that states "Please enter the correct answer text"

• If the administrator deletes the correct answer explanation, they will be returned to theedit question screen and given an error message that states "Please enter the correct an-swer explanation"

• If the administrator deletes at least one incorrect answer text they will be returned to theedit question screen and given an error message that states "Please provide text for 4 in-correct answers."

• If the administrator deletes at least one incorrect answer explanation they will be returnedto the edit question screen and given an error message that states "Please provide explana-tions for 4 incorrect answers."

Page 50

• If the administrator unselects all categories, then they will be returned to edit questionscreen and given an error message that states "Please select at least 1 category for thequestion".

• If the administrator selects the checkbox for adding a new category, does not enter anytext, and unselects all other categories, they will be returned to the edit question screenand given an error message that states "please enter a name for the new category".

• If the administrator selects the new category option and forgets to enter any text, but hasleft at least one other category still selected, the add category option will be ignored andthe question will be updated in the database like normal.

Postconditions: The question exists in the database in its revised format. The question mayappear on exams if it is approved, and may not appear on exams if it is not approved.

Task: A teacher views statistics for their state.Preconditions: The teacher is logged in, exams have been taken within their state.User Actions: The teacher chooses the “Statistics” menu option. The teacher then choosesthe “View State Summary” menu option. The teacher may choose to view all exams, or onlythe last certain number of exams.System Actions: The system shows state statistics for the teacher-entered number of exams.If no exams have been taken, the system will display an error of “No exams have been takenin this state.” The system will also produce a graph over time of the exam results.Postconditions: None

Page 51