Produktdokumentasjon
Forord Denne delen av dokumentasjonen fokuserer på funksjonaliteten til programmet og hvordan vi har utviklet produktet. Produktdokumentasjonen er ment primært som et hjelpeverktøy for fremtidige utviklere som har behov for å vedlikeholde, utvikle og forstå programmet. Dokumentasjonen gir innsyn i hvordan vi har valgt å arbeide, hvilke løsninger, samt metoder vi har brukt for å løse problemer. Dokumentasjonen gir også innsyn i hvordan programmet fungerer, både for administrator og bruker. Det er ikke vår intensjon at denne dokumentasjonen skal forklare i detalj hvordan spillet konfigureres. For dette har vi laget en brukermanual. Målet med dokumentasjonen er å forklare de underliggende mekanismene i programmet, hvilke endringer vi har gjort og hva dette har å si for vår oppdragsgiver. 30
Innholdsfortegnelse Forord... 30 Innholdsfortegnelse... 31 Innledning... 33 Teknisk informasjon... 35 1. Systemkrav... 35 2. Struktur... 35 3. Databasen... 37 4. Serveren... 44 Konfigurasjon... 45 1. XML-konfigurasjonsfila... 45 1.1 Funksjoner... 45 1.2 Hvorfor XML?... 45 1.3 DTD... 45 1.4 XML parser... 47 1.5 XML Document Object Model... 47 1.6 Hva er DOM?... 47 1.7 Hvorfor DOM?... 48 2. Web-grensesnittet... 48 2.1 Direkte editering av XML-fila... 48 2.2 Bruk av web-grensesnittet... 48 3. Versjon 1 versus versjon 3... 49 3.1 Deklarasjon av variable i php... 49 3.2 Gruppene... 50 3.3 Rundene: Training Treatment - Test... 52 JAVA-applikasjonen... 56 1. Funksjoner:... 56 2. Klassene... 56 2.1 Public class FigurGame extends JApplet... 56 2.2 Public class DatabaseCom... 56 2.3 Public class Gamewindow extends JPanel... 57 2.4 Public class parser... 57 2.5 Public class round... 57 2.6 Private class phase... 57 31
2.7 Public class Terrain extends JPanel... 57 2.8 Public class Engine... 58 2.9 Private class KeyHappening... 58 2.10 Private class ButtonListener... 58 3. Database kommunikasjonen:... 58 Prosessen i programmet:... 59 32
Innledning FigureGame 3.0 består i hovedsak av 3 deler. Den ene delen er en webside/konfigurasjonsside hvor administrator bestemmer alle innstillinger for spillet. Den andre delen er webapplikasjonen som er det brukere av spillet ser i sin nettleser når et eksperiment utføres. Den siste delen en Debian-server. Serveren håndterer alle endringer administrator måtte utføre på konfigurasjonssiden, og sørger for at dette blir lastet opp i webapplikasjonen. Alle de 3 delene kommuniserer via serveren. Konfigurasjonssiden er basert på en XML-fil med bruk at PHP og Ajax teknologi. Administrator har her muligheten til å bestemme og konfigurere alle innstillinger i webapplikasjonen og hvordan den skal oppleves. Dette gjør at brukere kan ha forskjellig opplevelse av spillet. Når oppdateringer eller endringer er gjort på konfigurasjonsfila vil en ny konfigurasjonsfil genereres og lagres på serveren. Dette gjør det mulig å kunne gå tilbake til gamle innstillinger, samt å ta vare på flere sett med innstillinger. Endringer må lagres og spillet må startes på nytt før disse endringene inntreffer i spillet. Webapplikasjonen er det grensesnittet brukere av programmet vil se. De har ikke mulighet til å endre noen innstillinger eller bestemme gjennomføringen av spillet. Testpersoner av spillet er nødt til å følge instruksene på skjermen til en hver tid og vil få testet sin reaksjonsevne. Valg de foretar i løpet av en sekvens vil bli lagret og det er disse valgene som er grunnlaget for å foreta en analyse av beslutningsevnen. Serveren er der primært for å samle alle registrerte data og sende disse til MySQL-databasen. Data fra webapplikasjonen sendes etter hver gjennomført runde i spillet. Serveren lagrer også XML-konfigurasjonsfila. Konfigurasjonsfila er skrevet i PHP med en kombinasjon av XML. PHP-siden bruker en innebygd funksjon for å lese og skrive til XML-fila slik at administrator ikke trenger å ha noen XML-kunnskaper for å konfigurere spillet. PHP-koden er skrevet i PHP 5 med bruk av objektorientert programmering. Serveren er en standard Debian Linux 2.6.8 med Apache2 webserver og MySQL versjon 5.1.46 33
FigureGame 3.0 har blitt utviklet ved Høgskolen i Oslo av Olaf Nikolai Hansen, Inger Lill Nystad og Robin Juliussen. Denne versjonen er en videreutvikling av 2 tidligere spillversjoner. Vår versjon har blitt designet med tanke på å forbedre og forenkle konfigurasjonen av programmet, samtidig som vi har utvidet mulighetene slik at det kan forskes på en større gruppe testobjekter. Vi har endt opp med en fullstendig versjon som fungerer slik den skal, samtidig som den er et godt utgangspunkt for fremtidige utviklere. 34
Teknisk informasjon 1. Systemkrav Brukersiden: Det eneste en bruker av programmet trenger for å kjøre FigureGame 3.0 er en installasjon av Java fra www.java.com. Anbefalt programvare for fremtidige utviklere: PHP version 5 Eclipse Project SDK (Open source plattformuavhengig Java-utviklingsverktøy som har mulighet for å kjøre applet viewer). 2. Struktur Figur 4: Use Case Diagram 35
Figuren over (figur 1) er et Use Case Diagram. Det forklarer dataflyten gjennom hele prosjektet: Administrator: Administrator har to muligheter: Konfigurere programmet Hente data fra databasen Konfigurasjon av programmet gir administrator mulighet til å definere hvordan en spillgjennomføring skal foregå. Eksempler på dette er: Tidsrammer Tilbakemeldinger Poeng Figurplasseringer Antall runder i spillet Pauser Osv osv Ved å endre på disse variablene vil to sett med innstillinger gi en totalt forskjellig opplevelse av spillet, noe som igjen vil påvirke hvordan en bruker vil foreta sine valg underveis i spillet. Brukeren: Brukeren er kun i stand til å starte applikasjonen. Når denne er satt i gang hentes konfigurasjonsfila som administrator har laget fra serveren. Applikasjonen laster Java Virtual Machine og spillet begynner. For hvert steg brukeren gjør i programmet, registreres det hvor fort dette ble gjort og om det var riktig valg. Programmet registrerer også hvilket mål brukeren har valgt når dette er et mulig valg. Når brukeren er ferdig med spillgjennomføringen blir resultatene sendt til databasen og en poengsum vil komme opp på skjermen. 36
3. Databasen Figur 5: Databasen I dette prosjektet var det allerede en eksisterende MySQL-database. Vi har valgt å gå videre med MySQL som databasesystem, så har ikke gjort endringer på relasjonene mellom tabellene i databasen. Vi har derimot opprettet en ny og tom database som er tilpasset de endringene som vi ellers har jobbet med i prosjektet. Vår database består av i alt 11 tabeller. Disse kan deles inn i tre grupper: De som har med brukere å gjøre De som registrerer hva brukeren gjør underveis i et spill De som inneholder informasjon om konfigureringen av spillet. User: Her får brukeren får sin ID. I denne tabellen lagres også informasjon som brukeren svarer på før spillet starter: 37
age er en tallverdi som er større enn 10 og mindre enn 90. Dette er alderen på brukeren. sex er en tekstvariabel som beskriver kjønnet til brukeren. Alternativene male og female blir senere gjort om til 1 for male og 0 for female. eyesight er en tekstvariabel som beskriver om brukeren har normalt syn eller ikke. Hvis brukeren har briller eller linser regnes dette som normalt syn. Notasjonen i databasen er 1 for yes og 0 for no. colour er en tekstvariabel som beskriver om brukeren har normalt fargesyn eller ikke. Valgmulighetene er Yes og No som i database er 1 for Yes og 0 for No. hearing er en tekstvariabel som beskriver om brukeren har normal hørsel eller ikke. Valgmulighetene er Yes og No som i database er 1 for Yes og 0 for No. date er en datetime-variabel og er datoen og klokkeslettet brukeren registrerte seg. pass er en smallint-variabel som kan ha verdiene 1 eller 0. 1 betyr at brukeren anvendte et passord for å få tilgang til spillet, 0 betyr at brukeren ikke hadde noe passord. Answers: Denne tabellen inneholder informasjon om spørreskjemaet som brukeren svarer på etter spillet er avsluttet. answer er en fremmednøkkel og er primærnøkkel for tabellen options. refid er en fremmednøkkel og er primærnøkkel for tabellen questions. refuser er en fremmednøkkel og er primærnøkkelen fra tabellen user. JAVAphase: Tabellen inneholder informasjonen om hver runde som spilles. Her ligger det referanser til xmlphase-tabellen. I denne tabellen lagres også hvilke poeng du har fått i hver runde og hvor mange ganger det har blitt gjort feil i hver runde. refuser er en fremmednøkkel og primærnøkkel i tabellen user. error er en fremmednøkkel og primærnøkkel i tabellen error. xmlphase er en fremmednøkkel og primærnøkkel I tabellen xmlphase. chosengoal er en tallverdi og beskriver hvilket mål brukeren valgte eller har valgt på forhånd. Kolonnen har verdiene 1 til 3. 38
reward er en smallint -tallvariabel. Dette tallet beskriver poengsummen brukeren fikk på en runde. Hvis error har en verdi høyere enn 1 betyr det at runden ikke ble fullført og reward vil få verdien 0. touches er en smallint tallvariabel og beskriver hvor mange ganger brukeren har trykket på tastene fra runden starter til og med runden er fullført eller en feil ble gjort. length er en smallint tallvariabel som beskriver hvilken lengde runden hadde. 0 betyr short, 1 betyr medium og 2 betyr long runde. JAVAstep: denne tabellen inneholder informasjon om hvor lang tid som ble brukt før spilleren trykket på en piltast, om belønningen skal synes, hvilken lengde hver runde har og om det er lagt inn noen forstyrrelser. Her er det også lagt inn en referanse til hvilken bruker som spiller og hvilken JAVAphase det spilles på. refuser er en fremmednøkkel og primærnøkkelen til tabellen user. refphase er en fremmednøkkel og primærnøkkel i tabellen JAVAphase. Den viser hvilken fase tastetrykkene kommer fra. time er en tallverdi og beskriver hvor mange millisekunder det tok brukeren å trykke på en tast. Når brukeren må velge et mål og tasten ikke blir trykket på i tide vil time får verdien -1. clicks er en smallint -tallvariabel som får verdien 1 hvis et tastetrykk ble registrert og 0 hvis det ikke ble registrert noe innen tiden var ute. showreward er en smallint -tallverdi som kan ha verdiene -1, 0 eller 1. showlength er en smallint -tallverdi som kan ha verdiene -1, 0 eller 1. showtouch er en smallint -tallverdi som kan ha verdiene -1, 0 eller 1. disturbance er en tallverdi som viser hvorvidt det skjer en endring i figurposisjonene eller ikke. Verdien -1 betyr at posisjonene er den samme som tidligere. Et firesifret tall brukes for å beskrive om det var en endring. Det første tallet står for hvilket step endringen skjer og de 3 siste beskriver det nye figuroppsettet. 39
Configfiles: Tabellen holder oversikten over de gamle configuration.xml-filene som ligger tilgjengelig slik at det er mulig å hente inn gamle konfigurasjoner. Den inneholder også et datostempel til hver fil. date er av typen datetime og er datoen og klokkeslettet på når konfigurasjonen ble lagret. Question: I denne tabellen ligger de spørsmålene som brukes i spørreskjemaet etter at spillet er avsluttet. question er en tekstvariabel og inneholder teksten til et spørsmål. date er en datetime variable og beskriver datoen og klokkeslettet spørsmålet ble lagt til i databasen. status er en variable av typen smallint. 0 betyr at spørsmålet er i bruk, 1 betyr at spørsmålet ikke er med i spørreskjemaet brukeren skal fylle ut etter at spillet er gjennomført. Options: Her ligger svaralternativene til spørsmålene i question-tabellen. relid er en fremmednøkkel og primærnøkkelen til tabellen questions. Den viser hvilket spørsmål svaralternativet tilhører. o er en tekstvariabel og inneholder teksten for svaralternativene. System: I denne tabellen ligger det en hash av passordet som er satt av administrator. Dette passordet må spilleren bruke til innloggingen av spillet. onoff er av typen smallint og bestemmer om bruken av password er aktiv eller ikke. password er en tekstvariabel og inneholder det krypterte passordet. xmlfile: Hver rad I denne tabellen inneholder informasjon som bestemmer hvordan en runde ser u tog hvordan den skal gjennomføres. refuser er en fremmednøkkel og primærnøkkel i tabellen user. date er av typen dato og viser datoen for gjennomføringen av runden. fontsize er en smallint -tallvariabel og viser størrelsen på teksten som brukeren ser i en runde. timestep er en tallverdi og bestemmer hvor mange millisekunder brukeren har til rådighet for å trykke på tasten når pilen i spillet skal flyttes. 40
shorttrack er av typen smallint og beskriver hvor mange steg det er i en kort runde. mediumtrack er av typen smallint og beskriver hvor mange steg det er i en medium runde. longtrack er av typen smallint og beskriver hvor mange steg det er i en lang runde. traininggroupx er en tallverdi hvor X står for et tall fra 1 til 3. Verdiene i traininggroupx henviser til de forhåndskonfigurerte rundene som har en verdi 1-9 og rekkefølgen som rundene skal gjennomføres blir lagret i databasen. Hvis verdien er 41 betyr dette at den første runde vil være nr 4 og den andre vil være nr 1. treatmentgroupx er en tallverdi og har same beskrivelse som TrainingGroupX. testgroupxx er en tallverdi og har same beskrivelse som TrainingGroupX. pause1 er en tallverdi i millisekunder som viser hvor lang pausen etter startbeskjeden er gitt. pause2 er en tallverdi i millisekunder som viser hvor lang tid beskjeden om at målet er forhåndsbestemt blir vist. pause3 er en tallverdi i millisekunder som viser hvor lang pausen er etter at brukeren har nådd et mål. pause4 er en tallverdi som forteller hvor lang pauser er etter at en bruker har gjort en feil. pause5 er en tallverdi som viser hvor lang pausen er etter at brukeren har fått tilbakemeldinger. pause6 er en tallverdi som forteller hvor lang tid brukeren har på å velge mål når dette er mulig. pause7 er en tallverdi i millisekunder som forteller hvor lang tid det tar før poengsummen for en runde vises på skjermen. pause8 er en tallverdi i millisekunder som forteller hvor lenge poengsummen for en runde skal vises. pause9 er en tallverdi i millisekunder som bestemmer hvor lang pausen er etter en runde er fullført og før neste runde begynner. 41
fig1 fig9 er alle av typen smallint og refererer til hvilke 9 figurer administrator har valgt til en konfigurasjon. feedbacktextcolor er en tekstvariabel. Det er 6 mulige fargevalg. feedbackduration er en tallverdi i millisekunder som forteller hvor lenge tilbakemeldingen skal vises på skjermen. reactionthreshold er av typen smallint og er en Verdi i prosent fra 0 til 100. Det er den maksimale tiden en bruker har for å oppnå denne tilbakemeldingen i forhold til hva som er satt i timestep. Teksten er ment som en tilbakemelding hvis for eksempel en bruker er ekstra rask, eller hvis brukeren så vidt nådde målet i tide. Hvis prosentandelen av tiden ikke er overskredet vil brukeren få en tilbakemelding beskrevet i kolonnen reactiontime. goalattained er en tekstvariabel. Den inneholder teksten for beskjeden brukeren får etter at et mål er nådd. goalattainedon er av typen smallint og kan ha verdiene 1 elelr 0. Den bestemmer om tilbakemeldingen goalattained skal vises eller ikke hvor 1 er på og 0 er av. reactiontime er en tekstvariabel. Den inneholder teksten til tilbakemeldingen som vises om brukeren fullfører en runde raskere enn prosentandelen som er gitt i reactionthreshold. reactiontimeon er av typen smallint og bestemmer om tilbakemelding fra reactiontime skal være av eller på. 0 er av og 1 er på. XmlPhase: Denne tabellen inneholder informasjon om hver runde. refxml er en fremmednøkkel og er primærnøkkelen i tabellen xmlfile. session er en tekstvariabel og forteller om runden er en training, treatment eller test. roundnr er en tallverdi og forteller hvilken runde det gjelder i training, treatment eller test. phasenr er en tallverdi. Hver runde i training, treatment og test har 2 faser som spilleren må gjennom og phasenr forteller hvilken fase innstillingene gjelder. 42
timeline er av typen smallint og kan ha verdiene 1 og 0. Den bestemmer om tiden som er til rådighet for en runde skal vises eller ikke. timefirst er av typen mediumint og bestemmer hvor mange millisekunder brukeren har på seg til å gjøre første bevegelse når målet må velges. showrewards er en tekstvariabel som forteller i hvilke steg av en runde poengsummen for runden skal vises. showlength er en tekstvariabel som bestemmer om brukeren skal kunne se hvor mange steg runden har. touchrequirement er en tekstvariabel som bestemmer om antallet tastetrykk skal være mindre enn, lik eller flere enn det som er gitt i touches1, touches2 og touches3. showtouches er en tekstvariabel som bestemmer hvor i runden brukeren får beskjed om hvor mange tastetrykk som er nødvendig for at pilen i spillet skal flytte seg ett skritt frem. figureorder er av typen mediumint og er rekkefølgen for figurene på starten av en runde. disturbance er en tekstvariabel og bestemmer hvor i runden endringer i figurposisjon skal forkomme. definegoal er en tallverdi som bestemmer om brukeren skal kunne velge sitt mål eller om det blir forhåndsvalgt. reward1 er av typen mediumint og er poengsummen brukeren vil få hvis dette er det valgte målet brukeren kommer i mål. reward2 er av typen mediumint og er poengsummen brukeren vil få hvis dette er det valgte målet brukeren kommer i mål. reward3 er av typen mediumint og er poengsummen brukeren vil få hvis dette er det valgte målet brukeren kommer i mål. length1 er av typen smallint og er lengden på en runde hvis goal 1 er valgt. length2 is er av typen smallint og er lengden på en runde hvis goal 2 er valgt. length3 er av typen smallint og er lengden på en runde hvis goal 3 er valgt. touches1 er av typen mediumint og er antallet tastetrykk som må til for å nå goal 1. 43
touches2 er av typen mediumint og er antallet tastetrykk som må til for å nå goal 2. touches3 er av typen mediumint og er antallet tastetrykk som må til for å nå goal 3. Når en spiller er aktiv lagres det informasjon om spillerens aktivitet etter hver runde han/hun har gjennomført. Det lagres mye informasjon om hva spilleren gjør underveis, noe som fører til at enkelte tabeller øker raskt i størrelse. Det er særlig JAVAsteps og JAVAphase som er utsatt her. 4. Serveren Server informasjon: Vi ble tildelt en virtuell Linux-maskin til dette prosjektet. Denne har følgende: Web-server: Apache2 PHP: Versjon 5 Kernel: 2.6.8 Minne: 1GB 44
Konfigurasjon 1. XML-konfigurasjonsfila 1.1 Funksjoner Hele opplevelsen av applikasjonen er konfigurert i en XML-fil. Nesten hvert eneste aspekt i programmet er mulig å konfigurere og kan lett endres. På denne måten har administrator full kontroll over hvordan spillet skal oppleves. 1.2 Hvorfor XML? I hovedsak valgte vi å fortsette å bruke XML siden dette allerede var implementert fra første versjon av spillet. 1.3 DTD DTD- Document Type Definition definerer de lovlige blokkene i et XMLdokument. DTD bestemmer strukturen på dokumentet med en liste over lovlige elementer. Dette gir applikasjonen en mer sikker og riktig måte å håndtere XML-konfigurasjonsfila. I praksis betyr det også at applikasjonen kun kan kjøre med en riktig skrevet konfigurasjonsfil. Vår DTD ser slik ut: <!-- level 1 --> <!ELEMENT root ( trail, pauses, goals, feedback )> <!-- level 2 --> <!ELEMENT trail ( steptime, shorttrack, mediumtrack, longtrack, treatmentgroup*, testgroup*, training*, treatment*, test*)> <!ELEMENT pauses ( afterstart, aftergoalselected, aftergoalattained, afterfailure, afterfeedback, choice, afterchoice, beforereward, afterreward, endoftrail )> <!ELEMENT goals ( figure* )> <!ELEMENT feedback ( confirmation, reaction, goalattained )> <!ATTLIST feedback color CDATA #REQUIRED> <!-- level 3 - trail --> <!ELEMENT steptime ( #PCDATA )> <!ELEMENT shorttrack ( #PCDATA )> <!ELEMENT mediumtrack ( #PCDATA )> 45
<!ELEMENT longtrack ( #PCDATA )> <!ELEMENT treatmentgroup ( #PCDATA )> <!ELEMENT testgroup ( #PCDATA )> <!ELEMENT training ( trailpath, phase* )> <!ELEMENT treatment ( trailpath, phase* )> <!ELEMENT test ( trailpath, phase* )> <!-- level 4 - rounds --> <!ELEMENT trailpath ( #PCDATA )> <!ELEMENT phase ( figureorder, disturbance, goal, reward1, reward2, reward3 )> <!-- level 5 - phase --> <!ELEMENT figureorder ( #PCDATA )> <!ELEMENT disturbance ( #PCDATA )> <!ELEMENT goal ( #PCDATA )> <!ELEMENT reward1 ( #PCDATA )> <!ELEMENT reward2 ( #PCDATA )> <!ELEMENT reward3 ( #PCDATA )> <!-- level 3 - pauses --> <!ELEMENT afterstart ( #PCDATA )> <!ELEMENT aftergoalselected ( #PCDATA )> <!ELEMENT aftergoalattained ( #PCDATA )> <!ELEMENT afterfailure ( #PCDATA )> <!ELEMENT afterfeedback ( #PCDATA )> <!ELEMENT choice ( #PCDATA )> <!ELEMENT afterchoice ( #PCDATA )> <!ELEMENT beforereward ( #PCDATA )> <!ELEMENT afterreward ( #PCDATA )> <!ELEMENT endoftrail ( #PCDATA )> <!-- level 3 - goals --> <!ELEMENT figure ( #PCDATA )> <!-- level 3 - feedback --> <!ELEMENT confirmation ( #PCDATA )> <!ATTLIST confirmation color CDATA #REQUIRED> <!ELEMENT reaction ( #PCDATA )> <!ATTLIST reaction mode CDATA #REQUIRED> <!ELEMENT goalattained ( #PCDATA )> <!ATTLIST goalattained mode CDATA #REQUIRED> 46
1.4 XML parser Applikasjonen er bygget fullstendig rundt XML-konfigurasjonsfila. Websiden på en side, java-applikasjonen på den andre. Websiden leser fila og gjør administrator i stand å modifisere dokumentet hvor java-applikasjonen kun leser dokumentet for å få riktige innstillinger. Dette gjør lesing/skriving/modifisering av konfigurasjonsfila av stor viktighet for prosjektet. Ved bruk av DOM parser er det mulig å lese og skrive til konfigurasjonsfila, noe som passer perfekt til dette formålet. Figur 6: Konfigurasjonsfila blokk diagram 1.5 XML Document Object Model XML Document Object Model ( XML DOM) definerer en standard for aksess og modifikasjon av XML-dokumenter. DOM ser på et XML-dokumentet som en trestruktur, et nodetre, med elementer, attributter og tekst definert som noder. 1.6 Hva er DOM? W3C Document Object Model (DOM) er et plattform- og språkuavhengig grensesnitt som tillater programmer og script å dynamisk oppdatere innhold, struktur og utseende til et dokument. W3C DOM gir et standard sett av objekter for HTML- og XML-dokumenter, og et standard grensesnitt for aksess og modifikasjon av dem. 47
1.7 Hvorfor DOM? Da vi tok over programmet var DOM og XML allerede implementert. Vi valgte å fortsette å jobbe med disse da dette var gode valg og vi så at vi kunne bruke dette når vi skulle implementere våre utvidelser i programmet. 2. Web-grensesnittet Websiden for administrering av XML-konfigurasjonsfila er et kraftig verktøy på flere måter. Primært gir det administrator en rask og enkel tilgang til alle innstillinger. Nye ønskede verdier skrives inn, trykk på edit configuration og endringene trer i kraft. Administrator må ha full forståelse for hvordan programmet fungerer slik at alle verdier får en godkjent verdi. Administrator kan også til enhver tid editere XML-fila manuelt uten å bruke webgrensesnittet. Viktige faktorer som må tas til etterretning er da: 2.1 Direkte editering av XML-fila Skulle administrator velge å endre XML-fila direkte må han være uhyre presis og forsiktig. Skulle det ved en feiltagelse endres en tag kan det hindre programmet i å starte opp og ingen feilmelding vil komme opp og fortelle deg hvor feilen er. Administrator må også vite nøyaktig hvilke verdier det er lovlig å nytte og disse må skrives inn på riktig måte, ellers vil det føre til feil i programmet. Dette er ikke den anbefalte måten å editere XML-fila på. 2.2 Bruk av web-grensesnittet Ved bruk av denne metoden vil hvert element du taster inn bli sjekket for feil. Metodene for kontroll av elementene er skrevet med tanke på skrivefeil og det vil ikke være mulig å lagre et sett med innstillinger som inneholder feil. Det er også tatt hensyn til variabler som avhenger av hverandre, slik at de blir sjekket opp mot hverandre. Videre står det et plusstegn (+) eller et minustegn(-) ved siden av hvert felt som indikerer om det er en korrekt eller feil verdi som er skrevet inn. Dette er et kraftig verktøy da det gir bedre kontroll og full oversikt over editeringsprosessen. Ajax står for denne funksjonaliteten og den inntreffer øyeblikkelig etter at verdien er skrevet inn. 48
Figures 7: Konfigurasjonafila webgrensesnittet 3. Versjon 1 versus versjon 3 3.1 Deklarasjon av variable i php Webgrensesnittet er bygget på PHP versjon 5 som inneholder alle metodene for server-scripting. PHP 5 har også full support for DOM-analyse, noe som er absolutt nødvendig for å få programmet til å fungere. En av de største utfordringene når det kom til å bygge videre på PHP-delen til den forrige gruppen var at koden hadde gått ut på dato. Med dette mener vi at måten alle variablene var deklarert på i den gamle koden ikke lenger fungerte. Det var kommet nye regler og metoder for hvordan variable må deklareres når de skal sendes i et skjema fra PHP til XML. Ny deklarasjon: $fontsize = $_POST['fontSize']; $steptime = $_POST['stepTime']; $afterstart = $_POST['afterStart']; $aftergoalselected = $_POST['afterGoalSelected']; $aftergoalattained = $_POST['afterGoalSelected']; ${$roundabout.$i."_phase".$j."_timefirst"} = $_POST[$roundabout.$i.'_phase'.$j.'_timeFirst']; ${$roundabout.$i."_phase".$j."_timeline"} = $_POST[$roundabout.$i.'_phase'.$j.'_timeline']; 49
Gammel deklarasjon: ${$roundabout}[$i]->phase[$j]->timefirst = ${$roundabout.$i."_phase".$j."_timefirst"}; ${$roundabout}[$i]->phase[$j]->timeline = ${$roundabout.$i."_phase".$j."_timeline"}; Forskjellen ligger i at tidligere måtte ikke variablene deklareres i det hele tatt før de ble tatt i bruk i koden. Dette ble et problem når XML-konfigurasjonsfila skulle hente ut verdiene fra PHP-siden, verdiene var da tomme. Ved å deklarere alle variable løste vi dette problemet. Det å endre konfigurasjonene var vår hovedoppgave. Oppdragsgiver ønsker flere utvidelser samt et enklere oppsett for hvordan XML-konfigurasjonssiden ser ut. Fra den første versjonen av spillet har konfigurasjonssiden gjennomgått flere endringer og for å få frem disse vil vi beskrive begge versjonene. Vi vil referere til den første versjonen av spillet som versjon 1 og vårt produkt som versjon 3. Versjon 2 kom aldri i mål med en fungerende spillversjon, så vi har valgt å ikke ta med den da vi ikke har benyttet oss av noe fra versjon 2. 3.2 Gruppene Versjon 1: Versjon 1 har konfigurasjon for 1 x 2 x 2 (4) forskjellige grupper. Figur 8: Gruppekonfigurasjon - versjon 1 50
Versjon 3: Versjon 3 har konfigurasjon for 1 x 3 x 3 x 3 (27) forskjellige grupper. Figur 9: Gruppekonfigurasjon - versjon 3 51
3.3 Rundene: Training Treatment - Test Versjon 1: I versjon 1 er konfigurasjonene for hver runde plassert nedover. Hvis det skal konfigureres må det scrolles mye nedover siden og det er vanskelig å holde oversikt over hvor en er til enhver tid. 52
Figur 10: Rundekonfigurasjon - versjon 1 53
Versjon 3: Vi har endret oppsettet slik at konfigurasjonen for hvert trinn, training, treatment og trial har konfigurasjonene ved siden av hverandre. Dette gjør det lettere for administrator å holde oversikt over alle rundene. I tillegg har vi lagt inn en funksjon hvor du kan minimere oppsettene for rundene(se figur 12). Dette gjør hele konfigurasjonssiden mer ryddig. Ta for eksempel et sett med konfigurasjoner som inneholder 3 runder i training, 4 i treatment og 2 i test. I versjon 1 var det nødvendig å scrolle seg ned 9 sider med konfigurasjoner og samtidig holde oversikt over disse. I versjon 3 er det ikke behov for å scrolle i det hele tatt. Dette var et av de viktigste ønskene til oppdragsgiver. Brukermanualen gir en detaljert beskrivelse av hvert felt på konfigurasjonssiden. Figur 11: Minimeringsfunksjon - versjon 3 54
Figur 12: Rundekonfigurasjon - versjon 3 55
JAVA-applikasjonen 1. Funksjoner: Testpersoner kjører en JAVA-applikasjon som er lagret på serveren. Applikasjonen inkluderer flere JAVA-kompilerte klasser, samt databasetilkoblingen og XMLoverføringen. Selve spillet var programmert i Java da vi tok over koden, og vi valgte å holde fast ved dette da vi alle er godt kjent med dette som programmeringsspråk. Spillet er bygd som en applet. En applet er et program skrevet i Java som kan inkluderes på en HTML-side, på samme måte som et bilde er en del av en bokside. Når du bruker en nettleser for å kjøre Java-teknologi vil koden til appletet bli overført til ditt system og kjøres av nettleseren sin Java Virtual Machine (JVM). Spillet består av ti.class-filer. De fleste av filene er klasser som kjører programmet. Det er også klasser som leser XML-konfigurasjonsfila og kommuniserer med databasen. Appletet kobler seg til en database på serveren etter hver fase i spillet og lagrer alle detaljer fra spillet. Dette fører til at en stor mengde lagres etter hver runde. 2. Klassene Her kommer en forklaring til noen spesifikke klasser: 2.1 Public class FigurGame extends JApplet Klassen FigurGame arver et JApplet-objekt og er klassen som er implementert i HTML-koden for å starte spillet. Den lager et parser-objekt som leser XMLkonfigurasjonsfila (configuration.xml). Den leser også bildene spillet skal ha fra en URL. JApplet sin start()-metode lager et Engine-objekt som har kontroll over all data som går inn og ut under spillets gang. 2.2 Public class DatabaseCom Klassen DatabaseCom oppretter forbindelsen mellom appletet og MySQLdatabasen. Den mottar data fra klassen Engine og bygger så stringer med SQL spørringer som inneholder dataene og sender disse til databasen når en forbindelse er etablert. 56
2.3 Public class Gamewindow extends JPanel Klassen Gamewindow arver et JPanel-objekt. Den setter opp det grafiske brukergrensesnittet (GUI). I midten er et panel med området hvor brukeren flytter pilen under spillets gang og figurene som pilen beveger seg mot. På bunnen er et panel med to knapper, en som starter spillet og en som skal vise en demonstrasjon av spillet. Disse knappene forsvinner når spillet startes og kommer tilbake når spilleren har fullført spillet. 2.4 Public class parser Denne klassen leser konfigurasjonene fra XML-fila, legger de inn i et DOMdokument og sjekker at hver variabel har en riktig verdi. Deretter kan verdiene leses av Engine-klassen. Alle verdiene er generert som beskyttede typer (protected). 2.5 Public class round Denne klassen brukes til å lagre training-, treatment- og test-rundene. Disse tre rundene har to faser hver, og hver fase er en subklasse av klassen round. Den setter opp fasene slik at de inneholder riktig data. 2.6 Private class phase Denne brukes av round-klassen for å bygge rundene med to faser. Phase inneholder informasjonen om figurposisjon, når figurene skal bytte posisjon, om det er et mål og om dette målet er valgfritt eller forhåndsvalgt, samt hva poengsummen for fasen er om spilleren skulle komme i mål. 2.7 Public class Terrain extends JPanel Klassen Terrain arver et Jpanel-objekt. Konstruktøren til denne klassen setter opp figurene for hver runde. Dette betyr at den mottar seks bilde-objekter fra Engine-klassen, tre for den første fasen og tre for den andre fasen i hver runde. Den mottar også et bilde av pilen som brukeren flytter i hver fase. Terrainklassen setter også størrelsen på spillpanelet. 57
Klassen inneholder forskjellige metoder for meldinger som skal gis til brukeren underveis i spillet, plassering av figurene og pilen. Disse avhenger av koordinater klassen mottar fra parser-klassen. 2.8 Public class Engine Klassen Engine er apletets kontroller. Det er den største og viktigste klassen i programmet. Den har kontroll over alle elementer som for eksempel hvilke meldinger som skal vises til skjermen under spillopplevelsen, lagrer reaksjonstiden til brukerne, endringer i figurposisjon og kommunikasjon med databasen. Det er Engine som kjører programmet. Konstruktøren oppretter objekter av nesten alle de andre klassene og initialiserer alle variable med riktig data fra parser-klassen som igjen henter dem fra XML-konfigurasjonsfila. 2.9 Private class KeyHappening Denne klassen lytter til tastaturet og initialiserer variablene med riktig verdi. 2.10 Private class ButtonListener Denne klassen lytter til to knapper, den som starter spillet og den som skal vise en demo av spillet. 3. Database kommunikasjonen: Java-appletet bruker en JConnector for å koble seg til MySQL-databasen. Ved å sette opp et JDBC-grensesnitt får appletet kommunisert med databasen. Når Java-appletet settes i gang får hver bruker av programmet en unik ID. Denne ID en genereres ved registrering og sendes som en parameter til Java-appletet. Fra Engine-klassen blir nye runder og steg skrevet med nødvendige verdier samt referansen til brukeren. Med tanke på problemer rundt serveren når det skrives til databasen blir dette bare gjort etter at hver runde er fullført. Det er viktig for brukeren at det ikke er unødvendig ventetid da dette kan påvirke hvordan de utfører sine valg underveis i spillet. Det eneste andre tidspunktet det blir skrevet til databasen er hvis brukeren gjør noe feil i spillet som for eksempel velger feil tastetrykk eller bruker for lang tid. 58
Prosessen i programmet: Når denne rapporten skrives kan spillet nås ved å gå til: http://reidar2010.vlab.iu.hio.no/hoved Dette skjer når du åpner linken i en nettleser: Linken vil ta deg til registreringsside hvor du blir bedt om å skrive inn informasjon om deg selv. All denne informasjonen er anonym og ingen personlig informasjon som kan brukes for å spore personer blir lagret. Informasjonen blir lagret i en database og brukere blitt gitt en unik ID. Figure 13: Experiment program start side Trykk på Register me! for å registrere deg som bruker og du vil bli bedt om å bekrefte informasjonen. Etter at du har bekreftet informasjonen blir du sendt til en veiledning for spillet. Her får du en beskrivelse av spillet samt hvilke regler som gjelder for at du skal kunne gjennomføre det. Nederst står en link som tar deg til spillet. Når du trykket på denne vil en Java virtual machine (JVM) lastes. JVM leser alle.class filene i programmet. Brukeren får nå to valg: Watch demo eller Start Figure Game. Demoen er på dette tidspunkt ikke implementert. 59
Figur 14: Figur Game start Figur 15: Figur Game Alle brukere av spillet må gjennom 3 etapper i spillet. Den første er en training -etappe. Her blir brukeren kjent med spillet og resultatene lagres. Figur 16: Mål er nådd Figur 17: Tilbakemelding 60
Alle brukere blir fordelt i forskjellige grupper og dette skjer i henhold til hvilken ID de fikk da de registrerte seg. Den første brukeren av spillet får ID 1, og dette øker med én for hver nye bruker. Det er 39 forskjellige undergrupper, 3 traininggrupper, 9 treatmentgrupper og 27 testgrupper. Fordelingen skjer i en if-løkke hvor det gjøres modulus-tester på 27, som er antallet forskjellige testgrupper. Når det tas modulus 27 på ID vil det være en rest, og det er resten som bestemmer hvilke grupper brukeren kommer i. For eksempel modulus 27 på ID 213 gir en rest på 24 og den brukeren kommer i Traininggroup3, Treatmentgroup8 og Testgroup24. Fordelingen ser slik ut: Traininggroup1: ID/rest 1-9 Traininggroup2: ID/rest 10-18 Traininggroup3: ID/rest 19-27 Treatmentgroup1: ID/rest 1-3 Treatmentgroup2: ID/rest 4-6 Treatmentgroup3: ID/rest 7-9 Treatmentgroup4: ID/rest 10-12 Treatmentgroup5: ID/rest 13-15 Treatmentgroup6: ID/rest 16-18 Treatmentgroup7: ID/rest 19-21 Treatmentgroup8: ID/rest 22-24 Treatmentgroup9: ID/rest 25-27 Testgroup1-27: ID/rest 1-27 Dette kan også tegnes som en trestruktur slik: 61
Figur 18: Trestruktur av gruppefordelingsalgoritmen. Se brukerveiledningen (side 85) for flere detaljer om hvordan disse gruppene kan konfigureres hver for seg. Målet med å ha alle disse gruppene er at administrator kan konfigurere det slik at hver gruppe får et forskjellig oppsett av spillet. Dette gir mange flere muligheter når det kommer til å teste ut hvordan forsøkspersoner foretar sine valg. Forsøkspersoner vet ikke hvilken gruppe de er i. Felles for alle som spiller er at de må gjennom to faser av hver runde. Den første fasen er en forced round, hvor målet er valgt for dem. En gruppe kan ha kort vei til målet, en gruppe kan ha medium vei til målet og andre grupper kan ha lang vei til målet. Administrator bestemmer dette ved å konfigurere XML-konfigurasjonsfila. I den andre fasen må spilleren selv velge sitt mål. 62
Figur 19: Forced choice Figur 20: Free choice Hver eneste parameter i spillet leses fra XML-konfigurasjonsfila. Fila er kun tilgjengelig for en registrert administrator. Denne fila gjør det mulig å konfigurere nesten alle aspekter i spillet, fra hvor lange pausene er etter hvert klikk til hvor mange runder det skal være i hver fase av spillet. Etter hver runde blir informasjonen registrert i databasen. Skulle brukeren gjøre noe feil i spillet, trykke for mange ganger eller i feil retning blir dette også registrert, runden blir markert som ikke fullført, og runden må tas på nytt, helt til den er fullført. Tiden spilleren bruker på hvert skritt i en runde blir også registrert. Med all denne informasjonen tilgjengelig er det mulig for administrator å analysere og lage statistikk. Det kan testes på hvor lang tid brukere tar å gjennomføre spillet helt ned til detaljer om hvor lang tid det brukes for hvert tastetrykk. Det kan for eksempel gjøres et eksperiment på hvorvidt en bruker med høyere poengsum har gjort mindre feil enn gjennomsnittet. Med alle dataene som samles er målet at vår oppdragsgiver har mulighet til å teste ut hvorfor brukere gjør de feil de gjør og hva som gjør at de tar de valg de tar. 63
Alle brukere blir også spurt om de har normalt syn/fargesyn og hørsel da dette kan ha påvirkning på resultatet av testen. Etter at spillet er gjennomført følger et spørreskjema hvor administrator kan legge inn spørsmål om hva forsøkspersonene synes om spillopplevelsen eller andre spørsmål som måtte være av verdi. Svarene på disse spørsmålene blir også lagret i databasen og er tilgjengelig for administrator. 64