COMP 145: Implementation Manual
Oral Text Learning Production Interface Project
May 3rd, 2001
Group 10 Software Engineering TeamTeam Member / Title / Approval Signature
Karen Parker / Producer /
Brianne Roth / Administrator /
Sean Rielly / Director /
Jason Howell / Librarian /
Preface: This is the Implementation Manual document for Group 10 (Oral Text Learning) of Comp 145. This document is intended as a hindsight version of our Design Specification document, which was used for internal purposes to help us throughout the design of our application. This document will state the final design decisions of the project, and provide a change of history to note the major changes in our design.
1. Introduction: In this project we redesigned an existing process, not an existing program. In order for the Oral Text Learning pages to be created, users must provide certain information to editors so that they can create the web pages (i.e. the lyrics or the song itself). Currently there is no convention to this process, which makes it somewhat difficult. Users submit their materials in many different forms, often in an inconvenient manner. From this project, we hoped to ease this process by providing a very understandable, conventional interface for users to submit their materials to the editors. There had been no prototypes created for this, so we created this program to ease the process for the editors. This interface did have some design constraints. The users are assumed to have limited computer knowledge. This means in order for our program to be successful, two things must be remembered:
1)The interface must be drop-dead easy. If what we created is too difficult for the average user to understand then he/she would not use it.
2)The program must work. If people lose faith in our application (which would be very easy to do if the program crashed) they will not use it. If this software is not used, then we will not have succeeded on easing the existing process.
2. High-Level Design Specification:
Diagram 2.1: Structural Model:
Diagram 2.1 shows an overall static architecture of all the pieces. This breaks down the system into several subsystems, which are semi-dependent of each other. The program needs to gather several pieces of information from the user and submit it in a conventional manner to the editors. Each subsystem is responsible for gathering a different piece of information, and saving it with a specific given name, to a specific file so the editors can easily make the web pages.
2.1.1 Introduction screen - This section directs the user to one of the four options: the administrative controls subsystem, create new lesson series, modify existing lesson, or quit. This section of the program does not manage data, it simply sends the user on the correct track.
2.1.2 Administrative screen - This subsystem manages some important data that the rest of the program depends and uses. This system interacts with the other subsystems by managing some important pieces of information. These pieces of data will be stored on the network, and this screen will be password protected.
2.1.3 User Info Input - This Subsystem gathers information from the user to be passed on to the editor. While the user is allowed to modify (from the time he/she starts to the time he/she clicks finished) this information will have to be stored in an accessible place, so that it can be accessed and modified. One important piece of information that the rest of the program will use is the lesson name given by the user. This is a unique name and determines the file names that all other user information are stored. It also is used in the naming convention for the rest of the program and later created files.
2.1.4 Graphic Selection - This subsystem obtains a graphic from the user if one is available. If a graphic is ready to be submitted the subsystem gets it from the user by allowing the user to browse the local drives, and saves it in the designated file with the name lessonname_graphic.filetype. This subsystem also allows the user the option to submit a URL containing a location of a graphic if they do not have one immediately available. This information is stored in a file that is accessible by the editor. The URL is stored with all of the other user information. The user also has the option to include a text description of the picture or any other special instructions, see Special Instructions - 2.1.8). This subsystem can be bypassed if the user doesn’t want to submit a graphic or a URL.
2.1.5 Lyric gathering - This subsystem obtains a transcription of the song lyrics from the user through an external Microsoft Word application instance. It copies a pre-made template document and open allows the user to type in the lyrics. This subsystem saves the newly created file using the lesson name on the network along with the other user files. This subsystem can be bypassed if the user doesn’t want to submit lyrics.
2.1.6 Song gathering - This subsystem obtains an audio file, and stores it in WAV format on the network. The song can either come from a CD (in which case, the subsystem uses digital audio extraction), or from the user’s disk/hard drive (if the file is already in WAV format). This subsystem can be bypassed if the user doesn’t want to submit a song.
2.1.7 Email - This subsystem sends an email to the editor alerting them that a lesson has been created. It sends mail using the email address of the user that is entered in the User Information Screen.
2.1.8 Special Instructions - Throughout the program, the user can enter special instructions in text fields that they want the editor to see when creating their lesson online. They are included on every major screen and are stored in a file when the user clicks next to enter the next subsystem. At the end (in the Finished subsystem), all the special instructions that were provided in will be concatenated into a single file for the editor.
2.1.9 Finished - Clicking on the finished button concatenates all the special instructions text files and removes the lesson name from the available queue of resumeable lesson.
2.1.10 Modify - The modify subsystem allows the user to go to a certain subsystem by choosing which lesson to modify. These are buttons that direct the user to the particular subsystem for modification. The user is then required to go through the remainder of the application, before he can finish the lesson and be completely done.
Diagram 2.2: Control Model:
From the control model, we can see how this is an event driven program. Subsystems respond to events, usually the user clicking on a button to bring him/her to the next subsystem. This program is somewhat sequential, but the user has the freedom of backing up, or using the progress screen to hop to any section of the program. The event handlers take the user to the requested screen, and also have to register somehow that the user has completed that subsystem. Event handler I will take the user to the administrative side if necessary, or to the basic program (either to the info screen, or the modify screen). The second event handler handles the changes made in the Administrative screen. The third event handler handles the events of the bulk of the program.
3. Detailed Design Specification
3.1 Object Model Diagram
A.1 Global Variables stored internally as a global class
A.1.D
/ Data Name / Type / DescriptionA.1.D.1 / WIPFolder / String / Designated drive folder to store the works in progress lessons in.
A.1.D.2 / DefaultLyricsFile / String / Template HTML file stored on NT network drive, used for MS Word lyric entry.
A.1.D.3 / CurrentProcess / String / {New, Modify} stores which process was selected in Welcome Screen.
A.1.D.4 / LessonName / String / Name of the current lesson
A.1.D.5 / AdminPath / String / Path were administrator variables are stored
A.1.D.6 / ArchivePath / String / Path were archived lessons are stored
A.1.F
/Function
/Description
A.1.F.1 / saveVar ( ) / Saves the current variable values to the [*.var] file for future use and modification purposes.A.1.F.2 / getStringVar ( ) / Loads the current variable value as a String from the [*.var] file for modification for the specified object type.
A.1.F.3 / getSingleVar ( ) / Loads the current variable value as a Single from the [*.var] file for modification for the specified object type.
A.1.F.4 / getIntegerVar ( ) / Loads the current variable value as an Integer from the [*.var] file for modification for the specified object type.
A.2 Admin Variable Module stored in external file on network
A.2.D
/Data Name
/ Type / DescriptionA.2.D.1 / Password / String / Password to protect this administrative options
A.2.D.2 / SMTP Host / String / Email host name
A.2.D.3 / TemplateName / String / Name of Word template document
A.2.D.4 / StoragePath / String / Path to store newly created lessons
A.2.D.5 / EditorEmail / String / Email address to alert concerning new lesson creation
B. Lesson Module data variables stored in [(LessonName).txt]
B.D
/Data Name
/Type
/Description
B.D.1 / UserName / String / Stores the name of the owner of the lesson.B.D.2 / CourseName / String / Stores the name of the class for which the lesson is being made.
B.D.3 / DateNeeded / String / Stores the description of the due date of the lesson.
B.D.4 / Language / String / Stores the description of the foreign language that the lesson is spoken in.
B.D.5 / EmailAddress / String / User’s email address
B.D.6 / [(LessonName).txt] / Text File / Stores the state of the lesson, remembering variable values for future usage.
B.D.7 / InfoDone / String / Flag to say that this information portion of the program has been completed.
B.F
/Function
/Description
B.F.1 / TestLessonName ( ) / Ensures that the lesson name is valid and unique from other names on the server.B.F.2 / TestEmailAddress ( ) / Test to ensure email address is in proper email format.
B.F.3 / ValidateForm ( ) / Ensure form is completely filled
C. Graphic Moduledata variables stored in [(LessonName).txt]
C.D
/Data Name
/Type
/Description
C.D.1 / IsGraphic / String / Flag that says that a graphic is being provided or not.C.D.2 / IsGraphicURL / String / Flag that says this graphic is being described as a URL.
C.D.3 / IsGraphicFile / String / Flag that says a graphic file is being provided.
C.D.4 / GraphicFile / String / Name to save the copy of the user’s graphic on the network drive.
C.D.5 / graphURL / String / Stores the URL of the user’s preferred web graphic (if option is chosen)
C.D.6 / Notes / TextBox / Text box for special instructions about the user’s graphic.
C.D.7 / [(LessonName)_ graphic_notes.txt] / Text File / Stores the special instructions for the Graphic screens.
C.D.8 / GraphicDone / String / Flag to say that this graphic portion of the program was completed satisfactory.
C.F
/Function
/Description
C.F.1 / BrowseFiles ( ) / Opens a file explorer window for picking graphics from the hard drive, with preview pane.C.F.2 / PreviewFile ( ) / Opens the selected graphic in a preview pane before saving on network drive.
C.F.3 / AddInstructions ( ) / Add special instructions to the current graphic notes file.
D. Lyrics Classdata variables stored in [(LessonName).txt]
D.D
/Data Name
/Type
/Description
D.D.1 / LyricsDocument / String / Name to save the copy of the user’s editable lyrics on the network drive.D.D.2 / ProvidedLyrics / String / Flag that says that a lyrics document was completed.
D.D.3 / Notes / TextBox / Text box for special instructions about the user’s lyrics.
D.D.4 / [(LessonName)_ lyrics_notes.txt] / Text File / Stores the special instructions for the Lyrics screens
D.D.5 / LyricsDone / String / Flag that says the Lyrics portion was completed satisfactory.
D.F
/Function
/Description
D.F.1 / RenameFiles ( ) / Makes a copy of the template at [DefaultLyricsFile] and saves as [(lessonname).html]D.F.2 / AddInstructions ( ) / Add special instructions to the current lyrics notes.
D.F.3 / PreviewFile ( ) / Opens the selected graphic in a preview pane before saving on network drive.
D.F.4 / OpenWord ( ) / Opens word document
E. Audio Module data variables stored in [(LessonName).txt]
E.D
/Data Name
/Type
/Description
E.D.1 / isCD / String / Flag that says audio is being provided through CD audio extraction.E.D.2 / isHD / String / Flag that says audio is being provided as a .wav file.
E.D.3 / noAudio / String / Flag that says no digital audio is being provided.
E.D.4 / AudioFile / String / Name to save the copy of the user’s audio on the network drive.
E.D.5 / SongTitle / String / Stores the user’s data for the Song title.
E.D.6 / ArtistName / String / Stores the user’s data for the Song Artist’s name.
E.D.7 / AlbumName / String / Stores the user’s data for the album which the song came from.
E.D.8 / CopyrightYear / String / Year of the audio’s copyright.
E.D.9 / Genre / String / Stores the user’s data for the song’s genre type.
E.D.10 / CopyrightInfo / String / Any additional audio copyright information.
E.D.11 / Notes / TextBox / Text box for special instructions about the user’s audio.
E.D.12 / [(LessonName)_ audio_notes.txt] / Text File / Stores the special instructions for the Graphic screens in .
E.D.13 / AudioDone / String / Flag saying that the Audio collection portion was completed satisfactory.
E.F
/Function
/Description
E.F.1 / BrowseFiles ( ) / Opens a file explorer window for picking wave from the hard drive, with audio preview play button.E.F.2 / AddInstructions ( ) / Add special instructions to the current audio notes.
E.F.3 / PreviewFile ( ) / Opens the selected audio in a preview pane with play/stop/rewind before saving on network drive.
E.F.4 / FindCD ( ) / Finds the CD drive on the computer with the audio CD in it, or alternatively, allows user to select which CD Drive to use.
E.F.5 / ExtractAudio ( ) / Digitally extracts audio from the selected CD drive and saves it with the name [(AudioName).wav]
E.F.6 / CopyAudio ( ) / Copies audio file from hard drive to StoragePath folder
F. Email Module data variables stored in [(LessonName_.txt]
F.D
/Data Name
/Type
/Description
F.D.1 / EmailMessage / TextBox / Text box for the email message content sent to [EditorEmail] about the creation of the user’s lesson.F.D.2 / SpecialInstructions / Text File / Text file created by concatenating all of the [Notes] files.
F.F
/Function
/Description
F.F.1 / FinishInstructions( ); / Concatenate all of the special instructions from the previous modules.F.F.2 / Email ( ); / Emails [EditorEmail] the basic information about the lesson, and notification that the lesson has been completely created.
F.F.3 / Finish ( ); / (LessonName) gets moved to finished lessons file on the server while reserving the (LessonName).
3.2 Low Level Data Flow
A. Main Menu
User chooses CurrentProcess [A.1.D.3]
? if ( CurrentProcess [A.1.D.3] == Administer)
goto section [B]
? if ( CurrentProcess [A.1.D.3] == New)
goto section [C]
? if ( CurrentProcess [A.1.D.3] == Modify)
goto section [D]
B. Administrator Data Entry (default values when installed)
user enters a password
? if (Password = =Password[A.2.D.1])
change EditorEmail [A.2.D.5]
change ArchivePath [A.1.D.6]
change WIPFolder [A.1.D.1]
change DefaultLyricsFile [A.1.D.2]
change Password [A.2.D.1]
restart at section [A];
? else
restart at section [B] (wrong password) or section [A] (Cancel)
C. Create New Lesson
enter LessonName [A.1.D.4];
TestLessonName (LessonName[A.1.D.4]) unique against all names on
server [B.F.1]
Goto section [E]
D. Modify Existing Lesson
Browse server WIPFolder [A.1.D.1] for LessonName [A.1.D.4]
User chooses LessonName [A.1.D.4]
goto section [E]
E. Progress Menu
User chooses working section
? if ( working section = = User Lesson Information)
goto section [F]
? if ( working section = = Graphic Selection)
goto section [G]
? if ( working section = = Lyrics Processing)
goto section [H]
? if ( working section = = Audio Extraction)
goto section [I]
? if ( working section = = resume later)
goto section [A]
? if (all working sections done = = Finish)
goto section [J]
F. User Lesson Information
RestoreState( (LessonName[A.1.D.4]).txt [B.D.7], Lesson Data)
enter UserName [B.D.1]
enter CourseName [B.D.2]
enter DateNeeded [B.D.3]
Enter Language [B.D.4]
enter EmailAddress [B.D.5]
TestEmailAddress (EmailAddress [B.D.5]) [B.F.2]
ValidateForm (section [F]) [B.F.3]
InfoDone [B.D.7] = true
SaveVar( (LessonName[A.1.D.4]).txt, Lesson Data ) [A.1.F.1]
Return to section [E]
G. User Graphic Information Gathering
User chooses GraphicChoice
? if ( isGraphic [C.D.1] = = false)
User enters Notes [C.D.6]
AddInstructions(Notes [C.D.6] ) [C.F.2] to file
(LessonName[A.1.D.4])_graphics_notes.txt [C.D.7]
GraphicDone [C.D.8] = true
SaveVar( (LessonName [A.1.D.4]).txt [B.D.6], Graphic Data ) [A.1.F.1]
Return to section [E]
? if ( isGraphicURL [C.D.2] = = true)
User enters graphURL [C.D.5]
User enters Notes [C.D.6]
AddInstructions(Notes [C.D.6] ) [C.F.3] to file
(LessonName[A.1.D.4])_graphic_notes.txt [C.D.7]
GraphicDone [C.D.8] = true
SaveVar( (LessonName [A.1.D.4]).txt [B.D.6] , Graphic Data ) [A.1.F.1]
Return to section [E]
? if ( isGraphicFile [C.D.3] = = true)
BrowseFiles( ) [C.F.1]
PreviewFile( ) [C.F.2]
Save file in location WIPFolder [A.1.D.1];
User enters Notes [C.D.6];
AddInstructions( Notes [C.D.6] ) [C.F.3] to file (LessonName[A.1.D.4])_graphic_notes.txt [C.D.7];
GraphicDone [C.D.8] = true
SaveVar( (LessonName [A.1.D.4]).txt [B.D.6] , Graphic Data ) [A.1.F.1]
Return to section [E]
H. Lyrics Gathering
User chooses LyricsChoice
? if ( ProvidedLyrics [D.D.2] = = true)
OpenWord(LessonName [A.1.D.4]).doc from WIPFolder [A.1.D.1] )
[D.F.4]
(User Saves file within Word)
PreviewFile(LessonName [A.1.D.4]).doc from WIPFolder [A.1.D.1] )
[D.F.3]
User enters Notes [D.D.3]
AddInstructions( Notes [D.D.3] ) [D.F.4] to file
(LessonName[A.1.D.4])_lyrics_notes.txt [D.D.4] in WIPFolder [A.1.D.1]
LyricsDone [D.D.5] = true
SaveVar( Lesson.txt [B.D.6] , lyrics) [A.F.1]
Return to section [E]
I. Audio Gathering
User chooses AudioChoice
user enters SongTitle [E.D.5]
user enters ArtistName [E.D.6]
user enters AlbumName [E.D.7]
user enters CopyrightYear [E.D.8]
user enters Genre [E.D.9]
user enters CopyrightInfo [E.D.10]
User enters Notes [E.D.11]
? if ( isCD [E.D.1] = = true)
FindCD( ) [E.F.4]
ExtractAudio( ) [E.F.5]
PreviewFile ( ) [E.F.3]
? if ( isHD [E.D.2] = = true)
BrowseFiles ( ) [E.F.1]
CopyFile ( ) [E.F.6]
AddInstructions( Notes [E.D.11] ) [E.F.2] to file
(LessonName[A.1.D.4])_audio_notes.txt [E.D.12] in WIPFolder [A.1.D.1]
saveVar( LessonName[A.1.D.1]).txt [B.D.6] , Audio Data) [A.1.F.1]
Return to section [E]
J. Email
User enters EmailMessage [F.D.1]
Finish ( ) [F.F.3]
Email (EditorEmail [A.2.D.5]) [F.F.2]
4. Requirements Traceability Correspondence
Corresponds to / Contract II Section Numbers5.1.1.1 / 5.1.1.2 / 5.1.1.3 / 5.1.1.3.1 / 5.1.1.4 / 5.1.1.5 / 5.1.1.5.1 / 5.1.1.5.2 / 5.1.1.6 / 5.1.1.6.1 / 5.1.1.6.2 / 5.1.1.6.3 / 5.1.1.7 / 5.1.1.7.1 / 5.1.1.8 / 5.1.1.9 / 5.1.1.9.1 / 5.1.1.9.2 / 5.1.1.10 / 5.1.1.10.1 / 5.1.1.11 / 5.1.1.12 / 5.1.1.13
3.1 Object Model Diagram / A.1.D.1 /
X
/ X / X /X
/ X / X / X / X /X
/ X / X / X / X / X / X / X / X / X / X / X / X / X / XA.1.D.2 /
X
/ X / X /X
/ X / X / X / X /X
/ X / X / X / X / X / X / X / X / X / X / X / X / X / XA.1.D.3 /
X
/ X / X /X
/ X / X / X / X /X
/ X / X / X / X / X / X / X / X / X / X / X / X / X / XA.1.D.4 /
X
/ X / X /X
/ X / X / X / X /X
/ X / X / X / X / X / X / X / X / X / X / X / X / X / XA.1.D.5 /
X
/ X / X /X