References Hovedprosjekt ved Høgskolen i Oslo 2010 Produktrapport

PRODUKTRAPPORT

Forord Dette er produktrapporten til pluginen References. Rapporten redegjør for programmets virkemåte, funksjonalitet og den tekniske oppbygningen. Rapporten er myntet på sensor, veileder og Aptoma sine utviklere. Vi forutsetter at leseren har en god IT-forståelse og har kjennskap til programutvikling. Rapporten kan leses fra start til slutt, men er ment som et oppslagsverk for utviklere. For interesserte lesere følger det med en del vedlegg. Disse har til hensikt å gi en dypere forståelse av produktet 2 S ide

Innhold Forord... 2 Innhold... 3 1 Innledning... 5 1.1 Gruppen... 5 1.2 Bedriften... 5 1.3 Oppgaven... 5 2 Presentasjon av produktet... 7 2.1 Rask oversikt over produktet... 7 2.2 Hva programmet gjør?... 8 2.2.1 Filer... 8 2.2.2 Notater... 8 2.2.3 Lenker... 8 3 Systemkrav... 10 3.1 Aptoma Framework... 10 3.2 DrPublish... 10 3.3 Firefox... 10 3.4 Database... 10 4 Teknologier... 11 4.1 HTML... 11 4.2 PHP... 11 4.3 CSS... 11 4.4 JavaScript... 11 4.5 JQuery... 11 4.6 SWFUploader... 11 4.7 Adobe Shockwave Flash... 11 4.8 MySQL... 12 5 Kodestruktur... 13 5.1 MVC... 13 5.1.1 Kontrollerlaget (Controller)... 13 5.1.2 Modellaget (Model)... 15 5.1.3 Presentasjonslaget (View)... 15 5.2 Kodestandard... 16 5.2.1 Gylne regler... 16 5.2.2 Krav til testing... 16 5.2.3 Navnkonvensjoner... 17 3 S ide

6 Programmets hoveddeler... 22 6.1 Generelt... 22 6.1.1 Kort presentasjon av formål... 22 6.1.2 Funksjonalitet... 22 6.1.3 Særlige forhold... 22 6.2 Filer... 23 6.2.1 Kort presentasjon av formål... 23 6.2.2 Funksjonalitet... 24 6.2.3 Særlige forhold... 26 6.3 Notater... 26 6.3.1 Kort presentasjon av formål... 26 6.3.2 Funksjonalitet... 26 6.4 Lenker... 27 6.4.1 Kort presentasjon av formål... 27 6.4.2 Funksjonalitet... 27 7 Dataflyt... 29 8 Enhetstesting... 31 9 Brukergrensesnitt... 33 9.1 Farger... 33 9.2 Minimalisme... 34 9.3 Brukeropplevelse... 34 9.4 Sortering... 34 10 Database... 36 10.1 Konfigurasjon... 36 10.2 Oversikt... 36 11 Sikkerhet... 38 11.1 Validering... 38 11.2 Feilmeldinger... 38 12 Kravspesifikasjonen og det endelige produktet... 39 13 Videreutvikling... 40 13.1 Drag and drop -opplasting... 40 13.2 Filbeskrivelse... 40 13.3 Forhåndsvisning av lenke... 40 13.4 Fjerne knappen med legg til lenke... 40 4 S ide

1 Innledning 1.1 Gruppen Dette hovedprosjektet er gjennomført av hovedprosjektgruppe nummer 4 ved Høgskolen i Oslo, år 2010. Gruppen består av: Navn Klasse Studentnummer Øyvind Shahin Berntsen Kheradmandi 3ac S141430 Henning Sjørbotten 3ac S147800 Fredrick Strøm 3ac S147780 Erik Leirstrand Øvrum 3ac S140782 Alle på gruppen kjente hverandre godt fra før, da vi har jobbet sammen ved flere anledninger i løpet av tiden på Høgskolen. Vi kjente derfor hverandres sterke og svake sider, og var trygge på at gruppen kom til å fungere bra sammen. Forventningene vi hadde til hverandre var basert på solide erfaringer. Ambisjonsnivået vårt var likt, og kommunikasjonen og samarbeidsevnen mellom oss visste vi var god. 1.2 Bedriften Aptoma er et produkt- og programvareutviklingsselskap for mediebransjen, som blant annet leverer programmer til store nettsteder som VG Nett og Ekstra Bladet. Deres fremste produkt er DrFront, et program hvor man på en enkel måte kan sanntidsredigere nettavisers forsider. Bedriften har hovedkontor i Akersgata i Oslo, og et avdelingskontor i Göteborg. Aptoma fokuserer utelukkende på nye medier. Deres mål er å lage attraktive og nyskapende produkter, som skal være kjernen i deres kunders virksomhet. De mener selv at fokuset deres på å løse virkelige brukeres behov, kvalitet i programmene og kundenes lønnsomhet, er årsaken til suksessen. 1.3 Oppgaven Aptoma er i gang med utvikling av et produkt de kaller DrPublish. Dette er et program journalister kan bruke for artikkelredigering i sanntid. En funksjon de har fokusert på, er at 5 Side

sluttbrukere med kunnskaper om programmering, enkelt skal kunne utvikle egne tilleggsmoduler med egen funksjonalitet til programmet. Dette skal kunne gjøres ved hjelp fra DrPublish sin API, samt vanlig programmeringskunnskap. «Vi er snart i lanseringsfasen, og vi trenger å få utviklet spennende og fremtidsrettede plugin til systemet som benytter og setter våre API'er på prøve.» - Aptoma Oppgaven vår ble derfor å sette oss inn i dette programmet, og utvikle en plugin som skal være god nok til å følge med produktet DrPublish når dette lanseres. Pluginen vi har utviklet tar vare på kildereferanser, og vi har derfor valgt å kalle pluginen for References. 6 S ide

2 Presentasjon av produktet References er en plugin for håndtering av kildemateriale knyttet mot artikler. Pluginen skal gjøre hverdagen litt enklere for journalister som skriver artikler med mange kilder/referanser. 2.1 Rask oversikt over produktet References lar brukeren lagre nettsidelenker, filer og egne notater knyttet til en bestemt artikkel. Dette skal det gjøres på en så enkel, intuitiv og minimalistisk måte som mulig. Journalistene kan også gå inn og endre lagrede notater og slette alt opplastet materiale. Referansene vil man kunne få tak i uavhengig av hvilken maskin man sitter på, og hvor som helst i verden man befinner seg. Alle journalister som har tilgang til samme databaser, vil kunne se og redigere artikkelen med de korrekte referansene i DrPublish. Fokuset har ligget på å lage en så rask og brukervennlig plugin som mulig. Vi har løst det ved å ha et enkelt design, samt bruk av teknologi som gjør at brukeren slipper å oppdatere siden, hver gang noe skal utføres. FIGUR 2.1 - BILDET VISER DRPUBLISH I FIREFOX. PLUGINOMRÅDET ER MARKERT MED EN RØD RAMME. PLUGINEN REFERENCES KJØRER. 7 S ide

2.2 Hva programmet gjør? Brukergrensesnittet til pluginen er enkelt og oversiktlig. Funksjonaliteten er delt i tre hoveddeler, som hver er gjemt bak en knapp. De tre knappene er: 2.2.1 Filer En journalist mottar filer med nyhetskilder fra nyhetssentraler som NTB, AP og lignende. I tillegg kan råmateriale av video og andre filer som en artikkel er tuftet på, være nyttig å ta vare på. References gjør dette enkelt ved at filene kan lastes opp, lagres til artikkelen, og dermed samles på et sted. De kan enkelt åpnes gjennom pluginen når enn man måtte ønske. FIGUR 2.2 BILDET VISER OPPLASTINGSOMRÅDET ETTER Å HA TRYKKET PÅ ADD FILES. HER ER EN FIL BLITT LASTET OPP. 2.2.2 Notater For en journalist kan det være nyttig å skrive ned små idéer og tips til artikkelen, men som kanskje ikke skal publiseres med en gang. For å spare tid kan det derfor være fint å kunne ha slike notater direkte i nettleseren der artikkelen står. Dette kan enkelt gjøres i References, og notatene kan leses når og hvor man vil, og kan også redigeres. FIGUR 2.3 BILDET VISER OMRÅDET FOR LAGRING AV NOTATER, ETTER Å HA TRYKKET PÅ ADD NOTE. 2.2.3 Lenker 8 S ide

Nettpublikasjoner finner ofte kilder fra andre sider på nettet. I en verden hvor det blir en stadig større jungel av nettadresser, kan det bli vanskelig å finne igjen de kildene man har brukt. References lar en ta vare på lenkene man bruker, og samler disse på et sted for ettertiden. FIGUR 2.4 - BILDET VISER HVOR MAN KAN LEGGE TIL EN LENKE, ETTER Å HA TRYKKET PÅ KNAPPEN ADD URL. 9 S ide

3 Systemkrav DrPublish er et backend-program, og Aptoma kan derfor sette strenge krav til programvare. 3.1 Aptoma Framework Aptoma Framework (heretter kalt AFW) er Aptoma sitt eget rammeverk. Dette er et rammeverk de selv har utviklet og som blir benyttet i utviklingen av alle Aptoma sine produkter. Det er et krav om at AFW er av nyeste versjon, og alle dets innebygde tester passerer. For å oppfylle disse testene må man følge Aptomas regler for oppsett av utviklingsmiljø. Se vedlegg for installasjonsinstrukser av AFW. 3.2 DrPublish Det er et krav om å bruke nyeste versjon av DrPublish, og at AFW er riktig installert og konfigurert. For å installere DrPublish kreves en større prosess, som er nærmere beskrevet i vedlegget om Oppsett av DrPublish. 3.3 Firefox Det er et krav om at brukeren benytter Mozilla Firefox av versjon 3.5 eller nyere. 3.4 Database Det er et krav om at det er satt opp en SQL-database der alle tabellene som pluginen trenger er lagt til. Dette blir gjort ved å kjøre SQL-spørringene som ligger i filen create.sql som er vedlagt. 10 S ide

4 Teknologier Her er en oversikt over de forskjellige teknologiene og versjonene av disse som References er bygget på. 4.1 HTML Produktet er skrevet med XHTML 1.0 Transitional. 4.2 PHP Produktet benytter PHP v. 5.2.10 4.3 CSS CSS kodingen følger CSS 2 standarden, sammen med Mozilla sine egne CSS utvidelser. Disse kan vi bruke, da systemkravet fra Aptoma krever at brukeren benytter seg av Mozilla Firefox. De særegne CSS-kodene for Firefox starter alle med moz-, og vi har blant annet brukt dette for å runde av hjørner på elementene i pluginen. En oversikt over disse utvidelsene i CSS koden, finnes på https://developer.mozilla.org/en/css_reference:mozilla_extensions. 4.4 JavaScript Produktet benytter JavaScript-bibliotek versjon 1.8.1. 4.5 JQuery I tillegg til det standard JavaScript-biblioteket, benytter vi oss av tilleggsbiblioteket JQuery v.1.4.2. http://jquery.com/ 4.6 SWFUploader References inneholder SWFUploader av versjon 2.2.0.1, som er et JavaScript-bibliotek som benytter seg av Adobe Shockwave Flash sin opplastingsfunksjon. http://code.google.com/p/swfupload/ 4.7 Adobe Shockwave Flash For å kjøre SWFUploader, må References kjøre med Adobe Shockwave Flash av minimum versjon 9.0.28 installert. http://www.adobe.com/flashplatform/ 11 Side

4.8 MySQL Databasen til References benytter MySQL Ver 14.14 Distrib 5.1.37 for Debian-linux-gnu (i486). http://www.mysql.com/ 12 S ide

5 Kodestruktur Dette kapittelet tar for seg hvordan koden vår er bygget opp. For å ha en best mulig struktur i koden, har vi benyttet oss av designmønsteret MVC og vi har fulgt kodestandarden til Aptoma. 5.1 MVC Programmet er delt inn i tre lag; et datalag, et presentasjonslag og et kontrollerlag. Dette gir en god kodestruktur, og forenkler vedlikehold og videreutvikling. Dette er også en del av kodestandarden til Aptoma. Ut i fra figur 5.1 kan man se at elementene MVC består av, ligger i mappen WEB-INF. En mer detaljert oversikt over hver modul er beskrevet nedenfor. FIGUR 5.1HER VISES WEB-INF MAPPEN FRA REFERENCES 5.1.1 Kontrollerlaget (Controller) Kontrollerlaget er sjefen. Her instansierer vi modellaget og presentasjonslaget. Dette er bindeleddet i applikasjonen. Her er det metoder som tar imot forespørsler som kommer fra presentasjonslaget. Det validerer inndataene, og sender disse forespørslene videre til riktige 13 S ide

metoder i modellaget. I kontrollerlaget sjekkes også resultatet som kommer tilbake fra modellaget, og korrekt data blir sendt tilbake til presentasjonslaget og brukeren. Det første som skjer når pluginen lastes, er at initialiseringsfunksjonen _init() kjøres. Se figur 5.2. Her settes standard-views, som alle metodene skal bruke. Dessuten instansieres prosessor-klassen. Her har vi også lagt på et tillegg som sjekker at brukeren er logget inn i DrPublish, hvis ikke vises bare en feilmelding. FIGUR 5.2 - _INIT() -FUNKSJONEN De forskjellige metodene i kontrolleren kalles med å bruke parameteren do, som sendes fra JavaScript. Når dette skjer, validerer vi POST-data. Valideringen skjer ved bruk av AFW sin metode, getpostrequestvar(). Denne metoden har innebygd validering av data, men vi har valgt å bruke casting i tillegg. Dette som en ekstra sikkerhet for å forsikre oss om at det er riktig datatype vi sender videre til modellaget. Se figur 5.3 for eksempel på datavalideringen. FIGUR 5.3 EKSEMPEL PÅ EN KONTROLLERFUNKSJON 14 S ide

5.1.2 Modellaget (Model) Modellaget vårt inneholder kun en klasse, en prosessor kalt ReferencesProcessor.php. Denne klassen tar seg av all databasekommunikasjon. Her kaster vi unntak, såkalte exceptions, hvis feil skulle oppstå, eller om databaseresultatene ikke er som forventet. Vi har en egen exception-klasse der vi håndterer våre egne unntak. AFW har en egen exception-klasse, og vår klasse baserer seg på denne. Denne klassen brukes av kontrolleren, og av AFW sin testmodul. På denne måten sikrer vi oss at alle parametere som sendes med i metodekallene er validert, og de trenger derfor ikke noen ekstra validering. Se figur 5.4 for et eksempel på en prosessorfunksjon. Dette er funksjonen som oppretter et nytt notat, og setter det inn i databasen. FIGUR 5.4 - PROSESSOR-METODE 5.1.3 Presentasjonslaget (View) Det er i presentasjonslaget at mesteparten av magien skjer. Vi har et standard-view, som henter inn alle de eksterne filene vi benytter oss av, som for eksempel JavaScript og CSS filer. I dette viewet kaller vi på et subview, som inneholder hele brukergrensesnittet. Grensesnittet i seg selv er ikke stort i størrelse, da vi har forsøkt å få et så minimalistisk utseende som mulig. Det meste av funksjonalitet ligger i JavaScript-filene. Dette gir pluginen et mer elegant og dynamisk utseende. I JavaScript-filen References.js ligger blant annet alle metodekall som kjører når brukeren trykker på funksjonsknappene. Eksempelvis gjøres et kall mot 15 Side

makenewnote() når man lagrer et nytt notat. Denne gjør igjen et AJAX-kall som kontrolleren plukker opp. På denne måten slipper siden og lastes gjentatte ganger. Siden bygges dynamisk ut i fra valgene brukeren tar. FIGUR 5.5 - VIEW KALLER CONTROLLER MED ET AJAX-KALL 5.2 Kodestandard Aptoma har sin egen kodestandard, som har vært påkrevd å følge. Dette var for å kunne skrive ryddig, sikker og lettfattelig kode. Vi har fulgt kodestandarden hele veien, bortsett fra at vi har valgt å bruke JQuery-biblioteket i stedet for Prototype fordi Aptoma ønsket det. Her er kodestandarden forklart. 5.2.1 Gylne regler Ikke skriv kort og uforklarlig kode, skriv heller klare og strukturerte uttrykk. Bruk beskrivende navngiving på variabler og metoder, men hold navnene kortfattet. Ikke bruk tvetydige forkortelser. All kode og kommentarer skal skrives på engelsk. 5.2.2 Krav til testing Skriv enhetstester kun for metoder som ikke er selvforklarende, og som ikke kan bli verifisert med en rask gjennomgang av koden. Skriv enhetstester for bugs før du retter dem, slik at det er sikkert at de ikke kommer igjen. Se figur 5.6 for et eksempel på en av våre enhetstester. 16 S ide

FIGUR 5.6 - ENHETSTEST 5.2.3 Navnkonvensjoner 5.2.3.1 Klasser Bruk bare alfanumeriske tegn, ikke bruk understrek. Bruk stor forbokstav for hvert ord i navnet. Ikke bruk påfølgende store bokstaver. Bruk statiske klasser og metoder der det er fornuftig. Se figur 5.7 for et eksempel på våre klassenavn. FIGUR 5.7 - VÅRE KLASSER 5.2.3.2 Metoder Alltid erklære tilgangsnivå for metoder (public / protected / private). Metodeparametere skal være adskilt med et enkelt mellomrom. Bruk en blank linje mellom metoder. Metodenavn starter med liten forbokstav. Metodenavn skrives etter CamelCase-standarden (det vil si stor forbokstav for hvert ord i metodenavnet). 17 Side

Se figur 5.8 for et eksempel på en av våre metoder. FIGUR 5.8 - EN METODE 5.2.3.3 Tekststrenger (Strings) Tekststrenger som ikke inneholder variabler, markeres med enkle anførselstegn. Tekststrenger som inneholder variabler, markeres med doble anførselstegn. 5.2.3.4 Arrayer Assosiative arrayer: AFW bruker enkle anførselstegn for å markere array-nøkler. 5.2.3.5 Exceptions AFW kaster exceptions ved de tilfellene der videre dataprosessering ikke er fornuftig. Dette skjer for eksempel når et databasekall feiler. All kasting av exceptions i AFW-applikasjoner er arvet fra klassen AFWException. Man skal ikke bruke AFWExceptions direkte, og man skal aldri kaste exceptions ved å bruke klassen Exception. Uhåndterte exceptions vil automatisk bli fanget opp av AFW sin interne 18 Side

unntakshåndterer, og vil vise en feilmeldingsside. AFWException-klassen er en underklasse fra PHP sin kjerneklasse Exception og LinkedException-klasse. I References bruker vi en egen exception-klasse, ReferencesException, som arver DrPublish sin egen exception-klasse. Denne arver igjen AFW sin exception-klasse. Konstruktøren i denne klassen har to innparametere. Den første er en feilkode, og den andre en feilmelding. Det er en strict- restriksjon i PHP som sier at arvede metoder må ha samme parameterdefinisjon som forelderen. Så, selv om vi ikke bruker $message- parameteren i getusermessage, så må den være der siden AFW har den. Ellers får vi en PHP- Notice feilmelding. Se figur 5.9 og 5.10 for et innblikk i exception-klassen vår. FIGUR 5.9 - EXCEPTION SIN GETUSERMESSAGE() FIGUR 5.10 - DELER AV EXCEPTION-KLASSENS KONSTUKTØR 5.2.3.6 Views Alle views bruker templates. Suffikset til alle templates er.tpl.php Subviewet fra en «do-action» bør ha samme navn som metoden. 19 S ide

5.2.3.7 Databaser Skal alltid brukes store bokstaver på nøkkelord i SQL-spørringer. Det skal ikke være NULL-verdier i noen tabellfelt. Databaseentitetstabeller (som users eller events) er skrevet i entallsform med flertallsendingen «s». Denne regelen kan produsere navn med feil staving, men Aptoma trenger denne navnekonvensjon på grunn av automatisk generering av deres kode. Relasjonstabeller (koble sammen to entitetstabeller) skal følge følgende notasjon: Navnet på entitetstabellene i entallsform i alfabetisk rekkefølge, adskilt med en understrek. 5.2.3.8 HTML For intranettprogrammer har vi muligheten til å sette restriksjoner på nettlesertype og - generasjon. Derfor er HTML-standarden vi bruker ganske løs, dette for å gjøre utviklingsprosessen enklere og raskere: <! DOCTYPE html PUBLIC "- / / W3C / / DTD XHTML 1.0 Transitional / / EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml1-transitional.dtd"> 5.2.3.9 CSS CSS-klasser skal være definert i separate CSS-filer og ikke i selve HTMLdokumentet. CSS-koding direkte i HTML-filen, såkalt inline CSS-koding, er kun tillatt for dynamisk skapte attributter/verdier. 5.2.3.10 Javascript JavaScript-klasser og -funksjoner skal bli definert i separate JavaScript-filer, og ikke i HTML-dokumentet. AFW har et krav om at JavaScript skal basere seg på Prototype sitt bibliotek. Vi har derimot valgt å basere JavaScript på JQuery sine biblioteker, da Aptoma hadde et ønske om dette. 20 Side

5.2.3.11 Dokumentasjon Det brukes JavaDoc kommenteringsstil for å kommentere AFW-klasser. Hver klasse-fil skal starte med en kommentarseksjon. Kort beskrivelse av klassen. @package no.aptoma.afw.model @copyright Copyright (c) 2006-2008 Aptoma AS (http://www.aptoma.com) @license http://framework.aptoma.com/afw/license/new-bsd @version $Id$ (remember to run "svn propset svn:keywords Id /path/to/afwfoo.php") @author user@aptoma.com (@see (references to related classes)) Alle metoder skal dokumenteres med en kort beskrivelse av metoden: @param @return @author (Kun hvis forfatter skiller seg fra resten av klassen, ikke aktuelt for oss) @throws (Kun hvis metoden kaster exceptions) 21 S ide

6 Programmets hoveddeler Her finner du en mer teknisk detaljert beskrivelse av produktet, delt opp i dets tre hoveddeler. Med hovedfokus på de største utfordringene ved hver del. 6.1 Generelt 6.1.1 Kort presentasjon av formål Formålet med pluginen er å ta vare på referanser, enten i form av filer, lenker eller notater. 6.1.2 Funksjonalitet Felles for de forskjellige hoveddelene er funksjonene for å slette og å angre, samt måten de listes opp på. Brukeren skal oppleve å få en ryddig opplisting over referansene, som skal gjøre at det hun/han måtte lete etter, raskt skal finnes igjen. Legges det til feil referanser, eller brukeren ikke ønsker å knytte en referanse til artikkelen, er det mulig å slette den. En referanse som blir slettet forsvinner øyeblikkelig. Noen advarsel vil man ikke få, fordi vi ønsker at ting skal flyte naturlig og raskt, uten forstyrrelser (Som en popup-melding som ønsker godkjenning). Ettersom de er så lette å slette, har vi utviklet en knapp for å angre eventuelle slettinger. 6.1.3 Særlige forhold Hver gang pluginen starter, kjører en privat metode i kontrolleren. Denne kjører igjen tre metoder fra modellaget, til å hente ut filer, notater og lenker fra databasen. Alt opplastet materiale skal vises i samme liste, og for å kunne sortere disse på forskjellige måter, er de tre arrayene blitt slått sammen til et array. For å skille mellom type referanser, er det lagt med et type felt i arrayet. Dette har vi også brukt til å liste opp referansene på forskjellige måter, etter hvilken type de er. Det som er viktig å merke seg angående sletting av filer, notater og lenker at de aldri blir fysisk slettet fra databasen. Når en referanse blir slettet, legges ID og dato inn i en database med enten navn deleted_file, deleted_note eller deleted_url, etter hvilken type den er. Dermed kan man for eksempel slå sammen deleted_file tabellen med tabellen files, der filene er lagret, for å se hvilke filer som er markert slettet. Det er et unntak hvor referansen blir fysisk slettet fra databasen. Dette skjer når man for eksempel legger til en fil med samme navn, på samme artikkel, som en fil som er markert 22 S ide

slettet. Grunnen til at vi fysisk sletter filen, er at man ikke kan lagre to filer med samme navn på server. Hver gang en referanse blir slettet, kopieres informasjonen om denne referansen inn i et angre-array, som bare eksisterer så lenge pluginen kjører. Referansen blir også slettet fra det opprinnelige arrayet som lister opp alle referansene, slik at brukeren ser at den er slettet. Når noen trykker på angre -knappen slettes referansen fra deleted-tabellen. Hvis den ikke finnes i databasen, blir metoden kjørt rekursivt og neste plass i angre-arrayet hentes ut. For at det ikke skal bli rotete med opplistingen av referanser med lange lenkenavn, notatoverskrifter og filnavn, har vi satt disse til å vises med maks 25 tegn i listen. Hele navnet ser man derimot i et tooltip ved musepekeren, om man beveger den over. Lenkene, overskriftene og filene vil allikevel lagres med hele navnet, men fordi pluginen arbeider på sterkt begrenset plass, blir det mer oversiktlig når det gjøres slik. Ved opplisting av lenker og notater, har vi et regulært utrykk som sjekker og bytter ut alle forekomster av < og >, med henholdsvis < og >. Dette gjør at hvis man legger til et notat som har et navn som inneholder HTML-tagger, så vil disse vises som tekst og ikke fungere som kode. Her kan du se hvordan vi bytter det ut i koden: FIGUR 6.1 - REGULÆRT UTTRYKK FOR FJERNING AV HTML TAGGER 6.2 Filer 6.2.1 Kort presentasjon av formål Formålet med filopplasting er som navnet tilsier muligheten til å laste opp filer. En journalist mottar filer med nyhetskilder fra nyhetssentraler som NTB, AP og lignende. I tillegg kan råmateriale av video og andre filer som en artikkel er tuftet på, være nyttig å ta vare på. References gjør dette enkelt ved at filene man har liggende lokalt, kan lastes opp og lagres til artikkelen. Dermed samles alt på et sted. De kan enkelt åpnes gjennom pluginen når man måtte ønske. Denne sentraliseringen gjør at flere kan nyte godt av slik informasjonen. 23 S ide

6.2.2 Funksjonalitet Filopplasteren baserer seg på SWFUpload-prosjektet sin kildekode (http://swfupload.org/swfupload). SWFUpload er et lite bibliotek bygget på JavaScript og Flash. Dette forsøker, i følge utviklerne selv, å utnytte det beste fra begge verdenene. SWFUploader benytter seg av de gode opplastingsegenskapene til Adobe Shockwave Flash, sammen med tilgjengeligheten og enkelheten fra HTML og CSS. SWFUploader har en lang rekke konfigurasjonsmuligheter, som vi fant ut passer våre krav til en filopplaster godt. Her er en liste over funksjonalitet vi har implementert, som skiller seg fra den vanlige HTMLfilopplasteren. Muligheten til å velge flere filer samtidig i dialogvinduet for opplasting. JavaScript- callbacks på alle events. Med dette mener vi at det kalles en JavaScript-metode hver gang spesielle hendelser skjer, som for eksempel når man er ferdig med å laste en fil, før man skal laste neste fil og så videre. Opplasteren henter filinformasjonen før filen lastes opp. Mulighet for å designe opplastingselementet med XHTML og CSS. Vise informasjon mens filer laster opp, ved hjelp av HTML. Opplasteren gjør det unødvendig å laste siden på nytt. Fungerer på alle plattformer/nettlesere som har Shockwave Flash -støtte. Man har muligheten for å konvertere filopplasteren til en vanlig HTML-opplaster, om Flash eller JavaScript ikke skulle være tilgjengelig. Dette er imidlertid en funksjonalitet vi ikke har valgt å benytte oss av. Det kreves JavaScript for å kjøre DrPublish, og vi ønsker å bruke mulighetene Flash gir oss. Derfor får brukeren heller feilmeldinger, dersom Flash ikke er riktig installert. Bare vise utvalgte filtyper i dialogvinduet for fil-velging, slik at om man kun ønsker å kunne lagre bildefiler, vil man kunne sette at kun disse kan velges. Legge opplastninger i kø, fjerne/legge til filer før man starter opplastingen. 24 S ide

All konfigurasjonen skjer ved hjelp av JavaScript, se figur 6.2 for et eksempel på denne konfigureringen: FIGUR 6.2 -KONFIGURASJON AV SWFUPLOADER Noe av det vi har hatt god nytte av, er handlingshåndterere. Det finnes ferdige klasser med slike handlingshåndterere ute på internett, men vi ønsker å være sikre på hva som skjer i dem. For å kunne gå god for den tekniske kvaliteten på koden, har vi valgt å skrive dem selv fra bunnen av. Klassen har fått navnet Handelers.js, og ligger i mappen /js/swfupload/js. Handelers.js har et stort fokus på feilhåndtering og validering. Handlingshåndtererene våre benytter seg både av data de mottar fra SWFUpload, metoder fra DrPublish sin API og pluginen vår. De har funksjonalitet som gir detaljerte feilmeldinger til utviklere, hvis aktivering av alternativet for debug i SWFUpload velges. Vi har implementert funksjonalitet som gir brukeren beskjed, dersom SWFUpload ikke klarer å starte. Se figur 6.3 og 6.4. FIGUR 6.3 - SWFUPLOADER LASTES 25 S ide

FIGUR 6.4 - FEIL VED LASTING AV SWFUPLOADER Muligheten med opplasting av flere filer benytter seg av en kø-plugin, som ikke er originalt i produktet. Vi fant denne i en av de medfølgende demonstrasjonene til SWFUploader. 6.2.3 Særlige forhold Opplasteren returnerer tidvis ganske generelle feilmeldinger. For eksempel kategoriserer den alle rettighetsproblemer som en HTML-feil, og returnerer feilkode 500 (Blant annet om man ikke har rette tilganger på filserveren). Verdt å legge merke til, er at selv om man setter file_size_limit i opplasteren, vil ikke dette overstyre begrensninger som er satt på webserveren den kjøres på. For å forandre på maks filstørrelse man kan laste opp, må man inn å endre i konfigurasjonen til selve webserveren. Verdiene post_max_size og upload_max_filesize må der settes til ønskelig grense for filopplasting. 6.3 Notater 6.3.1 Kort presentasjon av formål Til hver artikkel kan journalistene legge til eller lese eksisterende notater. Når journalister legger til notater skal det gå raskt, og være brukervennlig. Hvis de har skrevet noe galt eller ved en feiltagelse lagt til uferdig tekst i notatet, er det mulig å redigere notatet i etterkant. 6.3.2 Funksjonalitet For å legge til et notat, må man trykke på Add Text. Da vil det dukke opp et tekstområde hvor det er mulig å skrive inn tekst. Overskriften til notatet blir automatisk generert ut fra første linje, samtidig som den også blir første linje i notatet. Tekstområdet hvor man kan skrive inn notatet, starter som et vanlig en-linjes tekstboks. Etter hvert som man skriver inn tekst i tekstboksen, utvider området seg ut fra hvor mye tekst som 26 Side

blir skrevet inn. Dette er gjort ved å bruke en JQuery-plugin som utvider tekstarealet. Funksjonaliteten fungerer også motsatt, slik at når tekst fjernes fra tekstarealet, vil området krympe inn igjen. Notatet kommer automatisk opp i opplistingen av alle referansene. For å redigere notatet, trykker man på innholdet av notatet der det listes opp. Man vil se at feltet forandrer farge til hvitt, og det blir redigerbart. Teksten blir automatisk lagret når fokuset på tekstområdet forsvinner. Dette blir gjort ved HTML-funksjonen onblur, som igjen kjører en JavaScriptfunksjon som lagrer notatet. Det kjøres en JavaScript-funksjon som sender notatets ID til PHP-kode, som oppdaterer notatets innhold og eventuell overskrift. Når et notat blir oppdatert, blir også en kolonne i tabellen notes endret. 6.4 Lenker 6.4.1 Kort presentasjon av formål Siden journalister i stor grad finner kildene sine på nettsider, har vi gjort det mulig å lagre lenker til nettsider på pluginen. Når de sitter og jobber med en artikkel, kan det være vrient å holde styr på alle de forskjellige lenkene. Vi så det derfor som praktisk å ha en liste over dette lett tilgjengelige ved posting av en artikkel. 6.4.2 Funksjonalitet Vi har implementert funksjonalitet for å kunne lagre lenker til nettsider. Lenken lagres i databasen og listes opp i pluginområdet. Når man trykker på lenken, åpnes tilhørende nettside i et nytt vindu. Vi valgte dette, da området pluginen er tildelt i DrPublish har en veldig begrenset plass. Det er derfor mer hensiktsmessig å åpne i et nytt og større vindu. Vi har dessuten gjort det slik at hvis brukeren legger til en lenke uten prefikset http://, legges dette til uten at brukeren trenger å gjøre noe. Til dette brukte vi et regulært utrykk sammen med JavaScript som sjekker om lenken starter på http:// eller https://. 27 S ide

FIGUR 6.5 - FUNKSJONEN MED DET REGULÆRE UTRYKKET SOM SJEKKER LENKENS PREFIKS Man kan enten lagre lenken man skriver inn ved å trykke på Save-knappen med musepekeren, eller bare trykke på Enter. Hurtigtasten Enter fungerer slik at man kan skrive inn lenken i tekstfeltet, så trykke Enter og lenken vil lagres automatisk. Tekstfeltet tømmes, og man kan skrive inn ny lenke for lagring hurtig. Dette skjer fordi pekeren fortsatt vil være i tekstfeltet, og man kan fortsette å skrive uten å løfte fingrene fra tastaturet. 28 S ide

7 Dataflyt Denne figuren viser dataflyten i pluginen. Den gir et lite innblikk i hvordan de forskjellige klassene, samt Aptoma sitt rammeverk og API, og vår database henger sammen. FIGUR 7.1 - SYSTEMETS DATAFLYT 29 S ide

På figuren betyr fargene på boksene følgende: Blått er klasser vi har laget selv. Gult er det Aptoma står for. Grønt tilhører SWFUpload-biblioteket, som vi har benytter ved filopplasting. Lilla er JQuery sitt JavaScript-bibliotek. Rosa er tekstområde-utvideren, et JavaScript vi har laget etter en guide på nettet. Figurene er tilpasset mengden metoder som benyttes av pluginen, og datatrafikken som er innom den. Pilene illustrerer retningen dataene flyter og tykkelsen representerer mengden data. 30 S ide

8 Enhetstesting Prosessoren vår, altså modell-laget i MVC sitt designmønster, er det vi har testet med enhetstester. Her har vi oppnådd det Aptoma kaller Complete code coverage, noe som betyr at samtlige metoder i klassen er testet. Vi tester alle funksjoner og særegenheter som har mulighet for å feile, i henhold til kodestandarden vi har benyttet. Vi bruker ikke en såkalt Stub, slik mange enhetstester gjør, men har heller valgt å opprette en egen testdatabase. Denne settes opp med prefabrikkerte tabeller og data, før hver testkjøring. På denne måten, kan man være sikker på at dataene som ligger i databasen når testene starter, ikke er endret siden forrige kjøring. Enhetstesten kjøres gjennom AFW sitt testmiljø, og tilknytningen til dette blir konfigurert i filen /WEB-INF/classes/tests/ReferencesAllTests.php. Vi har valgt å kjøre alle testene i en klasse som heter ReferencesProcessorTest.php, da pluginen vår kun benytter en klasse i modellaget. Disse testene er det ingen hensikt å dele opp, så ReferencesAllTests.php kjører bare ReferencesProcessorTest-klassen. Konfigurasjonsfilen ReferencesAllTests.php er gjengitt i figur 7.1. FIGUR 8.1 - REFERENCESALLTESTS.PHP På figur 7.1 kan man på kodelinje 18 se det refereres til create.sql og insert.sql. Dette er de forhåndsdefinerte test-tabellene og testdataene vi benytter oss av. Disse settes opp i databasen UNITTEST_ReferenceBase. Standard SQL-syntaks for oppsett av tabeller og innsetting av data er benyttet i SQL-filene. Se vedlegg for filen create.sql og insert.sql. 31 S ide

Selve testene utføres i ReferencesProcessorTest.php. Her opprettes en kobling mot prosessoren, og det forsøkes å gjøre metodekall med forskjellige data. Deretter sammenlignes det faktiske resultatet, med det man forventet å få tilbake fra klassen. På denne måten vet man at så lenge testene er grønne, gjør prosessoren slik vi ønsker. Siden alle testene arves til AFW sin testklasse, er det viktig å bruke navnestandarden til AFW også her. Alle testmetoder må begynne med test for at AFW skal gjenkjenne dem som testmetoder. Derfor skal tester begynne med test, etterfulgt av en selvforklarende tittel av hva metoden tester. For eksempel testdeletefilefromdatabase. På Figur 7.4 vises et eksempel på hvordan disse testene er bygget opp. FIGUR 8.2 - EN ENHETSTEST For en mer detaljert oversikt over enhetstestene, se produkt vedlagt testdokumentasjon. 32 S ide

9 Brukergrensesnitt Brukergrensesnittet hos oss ligger på en meget begrenset plass, noe som gjør minimalisme og brukervennlighet essensielt. Ettersom dette vil bli brukt av journalister, er det viktig at skjermens fokus ligger på artikkelen, og ikke i pluginen vår. Derfor er fargevalg og nedtoning av disse nøye gjennomtenkt i formgivingen. Pluginen bør vises i høy skjermoppløsning, på minimum 1280x800. Ellers blir pluginområdet for lite, og elementer kan flyte over hverandre. FIGUR 9.1: PLUGINEN VISES I SITT EGET IFRAME SOM DRPUBLISH OPPRETTER. DET GIR ET MEGET BEGRENSET ARBEIDSOMRÅDE. HER VISES DETTE I FORHOLD TIL RESTEN AV DRPUBLISH. 9.1 Farger Pluginen er en liten bestanddel av selve programmet DrPublish, og det er viktig at fokuset til brukeren skal være på selve artikkelområdet. Derfor tonet vi ned fargene i pluginen, slik at det ikke krevde mer fokus enn hva som var nødvendig. Vi jobbet med å få pluginen til å gli naturlig inn i DrPublish sitt design. De nåværende fargene mener vi gjør dette på en slik måte at man ikke tenker over at pluginen er på skjermen, før man faktisk trenger å bruke den. FIGUR 9.2 - PLUGINEN SLIK DEN SER UT NÅR MAN ÅPNER EN NY ARTIKKEL. 33 S ide

9.2 Minimalisme Siden området pluginen har å operere på er så begrenset, har det som nevnt medført at minimalisme i utformingen av pluginen har vært viktig. Vi har konsentrert oss om å få flest mulig avanserte funksjoner til å bli vist så enkelt som mulig til brukeren. Tre knapper er plassert ved siden av hverandre øverst i vinduet, Add File, Add Text og Add URL. Grunnen til at vi gjorde det slik, er at vi ønsket å samle alle opplastingsmulighetene på samme sted. Når man trykker på hver enkelt knapp, glir det frem et funksjonsområde for denne knappen Elementer som finnes i databasen, legges inn i en egen liste nederst i plugin-området. De forskjellige elementene har egne fargekoder, som er lik de tilhørende knappene øverst på skjermen. 9.3 Brukeropplevelse Alt som skjer i programmet er laget slik at det skal være så naturlig som mulig for brukeren. Den eneste gangen pluginområdet lastes på nytt, er når man bytter artikkel. Ellers skjer alt asynkront ved hjelp av AJAX. Dette gjør at pluginen føles mer responsiv. Pluginen jobber med serveren i bakgrunnen, og alt som skal vises på skjermen av nye referanser dukker opp kronologisk i listen over lagrede elementer. Uavhengig om man velger fil, lenke eller notat så vil det nyeste elementet man lagrer på artikkelen vises øverst. Alle elementer i listen kan slettes ved å trykke på det røde krysset på høyre side. Til høyre for de tre hovedknappene finnes det også en angreknapp, slik at om man sletter ett eller flere elementer ved en feil, kan man gjenopprette disse igjen. Denne knappen er deaktivert som standard, og blir kun aktivert om noe faktisk er blitt slettet. 9.4 Sortering Referanseelementene kan sorteres etter både type (filer, tekst og lenker) og etter datoen disse er blitt lagt til artikkelen. Dette gjør man ved å trykke på henholdsvis Type og Created over listen av referanser. Det er lagt til små piler på disse knappene, som viser om det er sortert i stigende eller synkende rekkefølge. Elementenes farge er alltid lik knappen de kommer fra, slik at opplastede filer, notater og lenker har fargene til henholdsvis Add Files, Add Text og Add URL. Fargene vil ikke endres, uavhengig av hvordan man sorterer listen, slik at det er lettere for brukeren å få oversikt over elementene. 34 S ide

FIGUR 9.3 - SORTERING AV ELEMENTER ETTER OPPRETTELSESDATO - ELDST TIL NYEST FIGUR 9.6 - SORTERING AV ELEMENTER ETTER OPPRETTELSESDATO, NYEST TIL ELDST FIGUR 9.5 - SORTERING AV ELEMENTER ETTER TYPE NEDENFRA OG OPP FIGUR 9.4 - SORTERING AV ELEMENTER ETTER TYPE OVENFRA OG NED 35 S ide

10 Database Vi har brukt MySQL som database-grunnlag, og har seks forskjellige tabeller for lagring av notater, lenker og filer. Tabellene er normalisert etter fjerde normalform. 10.1 Konfigurasjon Når man konfigurerer databasen pluginen benytter, må man først sette opp navnet på databasen i filen /WEB-INF/config/settings.php. Her legger man til innstillinger i settingsarrayet (se eksempel nedenfor) som kommer fra AFW. Det som legges inn her, vil få høyere prioritet enn det som er satt fra før, av AFW. En bruker som har tilgang til databasen må også deklareres. Denne konfigureringen legges inn i filen /WEB-INF/config/shadow.php. Her er et eksempel på hvordan settings.php-filen ser ut: $settings = array( DB-NAME => DATABASENAVN, DB_NAME_TEST => DATABASENAVN ); 10.2 Oversikt Pluginen benytter seg av seks database-tabeller. Disse tabellene er selvforklarende og er skissert under i figur 10.1. Pluginen er designet slik at når man sletter en fil, en lenke eller et notat, settes det inn i en egen tabell med informasjon om objektets ID og tidspunktet for når det ble slettet. Vi opprettet disse tabellene for å slippe å ha nullverdier i databasen. Av den grunn slettes ikke data automatisk fra databasen. Man er nødt til enten å lage et eget script som går inn og sletter data som er markert for sletting, eller å gjøre det manuelt. Dette er standard metodikk hos Aptoma. 36 S ide

NOTES -------------------------------------- ID INTEGER NAME VARCHAR(255) CONTENT BLOB AUTHOR VARCHAR(45) ARTICLEID INTEGER CREATED DATETIME MODIFIED DATETIME -------------------------------------- PRIMARY KEY(ID) DELETED_NOTE -------------------------------------- NOTEID INTEGER DELETED DATETIME -------------------------------------- PRIMARY KEY(NOTEID) FOREIGN KEY(NOTEID) REFERENCES NOTES(ID) FILES -------------------------------------- id INTEGER articleid INTEGER filename VARCHAR(255) author VARCHAR(45) created DATETIME -------------------------------------- PRIMARY KEY(id) DELETED_FILE -------------------------------------- fileid INTEGER deleted DATETIME -------------------------------------- PRIMARY KEY(fileId) FOREIGN KEY(fileId) REFERENCES files(id) URL_REF -------------------------------------- id INTEGER url VARCHAR(255) articleid INTEGER author VARCHAR(45) created DATETIME -------------------------------------- PRIMARY KEY(id) DELETED_URL -------------------------------------- urlid INTEGER deleted TIMESTAMP -------------------------------------- PRIMARY KEY(urlId) FOREIGN KEY(urlId) REFERENCES url_ref(id) 10.1 - OVERSIKT OVER TABELLER 37 S ide

11 Sikkerhet Sikkerhet har ikke vært hovedfokuset vårt, da dette er et back-end produkt. Gjør man skade her, så skader man kun seg selv. Men vi har allikevel sikret oss mot SQL-injeksjoner, samt at vi caster alle variabler. 11.1 Validering Pluginen er både klient- og servervalidert. Klientvalideringen blir utført i References.js i alle funksjoner som får input fra bruker eller fra DrPublish. Et eksempel på hva som kan gå galt i DrPublish, er at artikkel-id ikke blir satt. Det vil da komme en feilmelding som sier at feil er oppstått og metoden avsluttes. Servervalidering blir utført i kontrolleren. Vi caster alle input-variablene, slik at det ikke er tvil om hva slags type variabel som skal komme inn. Etter at variablene er hentet ut, blir det sjekket at de ikke er tomme eller NULL. Er det noe som ikke stemmer, vil metoden bli avsluttet, og en feilmelding sendt tilbake til References.js. Siden de ferdige metodene vi bruker for å gjøre spørringer mot databasen sjekker for SQLinjections, har vi ikke gjort noen særlige valideringer utover dette. Unntaket her er når vi i databasen skal slette eller editere noe, får vi med IDen til det som skal editeres. Denne IDen sjekker vi om eksisterer, hvis den ikke gjør det, kaster vi en exception. Exceptionen blir tatt i mot i kontrolleren som igjen sender ut feilmelding. 11.2 Feilmeldinger I pluginen vil det aldri bli vist noen detaljerte feilmeldinger. Oppstår det noe galt blir feilmeldinger vist ved å bruke API-et til DrPublish, men med egne feilmeldinger vi har skrevet til brukeren. 38 S ide

12 Kravspesifikasjonen og det endelige produktet Tidlig i prosessen fant vi ut at vi skulle gå vekk fra drag and drop -funksjonalitet. Dette var fordi den teknologien som Aptoma ønsket at vi skulle bruke, Google Gears, ikke skulle bli videreutviklet av Google. Vi så ikke på dette som noe stort problem, da det egentlig er ganske uvanlig å bruke drag and drop i nettleserprogrammer. Det var ikke umulig at brukere heller ville benyttet seg av den vanlige opplasteren, istedenfor å dra filene rett i nettleseren om dette ble mulig. I starten hadde vi kun planer om å laste opp filer i pluginen. Det viste seg etter hvert at det også ville være praktisk å kunne lagre notater og lenker til artikler. I kravspesifikasjonen skrev vi at alle navn i HTML-koden skulle starte med tre bokstaver som forklarte hva slags HTML-tag det var. Dette gikk vi noe bort i fra, fordi Aptoma mente vi kun trengte disse bokstavene på HTML-tagger som ikke var selvforklarende. For eksempel ble det en flere div-tagger som ikke hadde denne typen navngiving. 39 S ide

13 Videreutvikling Vi har fulgt en streng kodestandard, for at pluginen skal føye seg inn i resten av Aptomas produktportefølje. Dette gjør det enkelt for utenforstående å sette seg inn i vår plugin, og også at de lettere kan videreutvikle denne. Dette er de utviklingsforslagene vi har. Vi har ikke undersøkt om dette er ønsket funksjonalitet, men vi tror det kunne vært nyttig å ha med. Det er ikke nødvendig med så mange utvidelsesforslag til denne pluginen, fordi det skal være enkelt og lite. Derfor vil i hovedsak utvidelsene være å forbedre allerede eksisterende funksjonalitet. Ønsker man en annen funksjonalitet er det bedre å lage en ny plugin. 13.1 Drag and drop -opplasting Drag and drop -grensesnitt hvor man kan dra filer inn i pluginen, slik at de lastes opp. Vi tror dette vil gjøre pluginen enda mer brukervennlig. Brukeren kan laste opp på flere måter, som vi tror kan gi en større fleksibilitet. 13.2 Filbeskrivelse Kort notat med beskrivelse om hva hver av de opplastede filene inneholder. Dette kan gi brukeren mulighet for å vite innholdet i filen, uten å måtte bruke tid på å laste den ned. 13.3 Forhåndsvisning av lenke Forhåndsvisning av lenke i lite vindu ved musepekeren når denne er over lenken. 13.4 Fjerne knappen med legg til lenke Vi foreslår å fjerne knappen med legg til lenke og isteden ha denne funksjonaliteten innebygget i legg til tekst-knappen. Om man velger å ha kun en lenke i tekstboks-feltet, skal dette gjenkjennes automatisk og legges til som lenke i listen om man trykker lagre. Legger man til noe annet skal det legges til som notat. Dette er imidlertid noe flere kan føle er rotete, så vi har ikke valgt å gjøre det slik i denne omgang. 40 Side