4. Produktrapport Forord Det er en forutsetning at leseren har gjennomgått presentasjonen av prosjektet før denne rapporten leses. Under denne forutsetningen, kan rapporten leses selvstendig og er da uavhengig fra de andre dokumentene. Denne rapporten gir et innblikk og en utfyllende informasjon om det rent tekniske rundt produktet og er i hovedsak beregnet for oppdragsgiver. Under denne rapporten vil det bli brukt mye ord og uttrykk rundt teknisk data og forståelse om dette. Om noe skulle være uklart henvises det til ordlisten som er vedlagt sist i kapitel 7, vedlegg. Det vil også bli gitt eksempler på kode vi har brukt i prosjektet. Ønsker leser å få med seg hele kodestrukturen, ber vi dem åpne det fullstendige programmet som finnes i vedlagt CD som inneholder all kildekode, eller lese den logiske koden i kapitel 7. Denne rapporten er delt inn i følgende hoveddeler: Brukergrensesnitt: Utforming Beskrivelse av applikasjon: Teknisk utredning Programmets oppbygging og virkemåte Arkitektur: Oppbyggingen av applikasjonen Sikkerhet: Teknisk beskrivelse av sikkerhetsløsningene i applikasjonen Videreutvikling: Hvordan oppdragsgiver kan gå frem for nye tilpasninger 1
Innhold Forord... 1 Innhold... 2 Utforming av brukergrensesnitt... 3 Skisser... 3 Det endelige brukergrensesnittet... 3 Fargevalg... 3 Knapper og ikoner... 4 Teknisk beskrivelse av applikasjon... 4 Mako framework... 4 Design... 5 Tilbakemelding til bruker... 5 Markdown... 5 Språkpakke... 6 Programmets oppbygging og virkemåte... 7 Model- view- controller... 7 Model database... 8 Repository/Interface Logisk mellomlag... 9 Controller logikk... 9 View utseende... 10 Generell kommentarer til kode... 10 Informasjonsarkitekturen bak utviklingen av applikasjon... 12 Organiseringsstruktur... 12 Bruk av navigering/ labels for å forenkle navigering... 14 Grupperingsmetoder til å kategorisere innhold for kategorier... 15 Metadata... 16 Språk i brukergrensesnittet... 16 Sikkerhet... 16 Videreutvikling... 17 Referanser/ kilder... 18 Vedlegg... 19 Vedlegg 1. Skisser... 19 Vedlegg 2. Det endelige brukergrensesnittet... 21 Vedlegg 3. Er- model (endret versjon av den som finnes i kravspesifikasjonen)... 23 Vedlegg 4. Blueprints... 24 2
Utforming av brukergrensesnitt Dette kapitlet tar for seg hvordan informasjonen skal fremstilles ovenfor brukeren. Vi fulgte Digitalarkivets retningslinjer for design og brukte skisser utdelt fra oppdragsgiver hyppig. Designet ble utarbeidet ved hjelp fra skissene som hadde et antatt enkelt design, men vi valgte å moderniserte og tilpasse utseendet så langt det lot seg gjøre. Fargevalg hadde liten betydning i starten av utarbeidelsen av designet. Det ble satt mest fokus på plassering av detaljer, knapper og funksjonalitet. Skisser Skissene av brukergrensesnittet fikk vi utdelt som en del av mockupen fra oppdragsgiver. Vi så på disse som et krav og hadde dermed en dialog med oppdragsgiver hvis vi ønsket å gjøre endringer. Nedenfor er skissene som ble tegnet digitalt. Dette er skissene som var en del av mockupen, og kan ses i vedlegg 1. Det endelige brukergrensesnittet Prosessen med det endelige designet for brukergrensesnittet ble startet ved å lage views. Her ble det fokusert på plasseringer av knapper, tekstbokser, avkryssingsbokser, kombinasjonsbokser, trevisninger, dialogvinduer med mer. I selve designet for brukergrensesnittet er det brukt Bootstrap, noe som var et krav fra oppdragsgiver. I vedlegget er brukergrensesnittet som ble laget med Bootstrap illustrert, der skissene er benyttet så langt det lot seg gjøre. Bildene er kun hoveddeler av programmet, disse kan ses i vedlegg 2. Fargevalg Det ble det bestemt å ta utgangspunkt i fargene på websiden til Digitalarkivet, og samtidig ble det tilpasset til det vi selv syntes var mest stilrent. Det forelå ingen krav til hvilke farger som skulle benyttes ettersom oppdragsgiver sørger for at det kosmetiske utseende stemmer overens med deres systemer og vil derfor senere bli satt opp mot deres CSS. Fargebruken ble derfor holdt enkelt og består av så få farger som mulig. Hovedtrekkene i applikasjonen er grå, blå, svarte, hvite og lyse toner. Når man står i et av hovedvinduene er all tekst svart, men knappene har hver sin illustrerende farge i henhold til funksjonaliteten. Holdes musepekeren over ulike elementer, som for eksempel knapper, dannes det en annen tone på knappens farge. Dette er for å kunne markere tydeligere hvor brukeren peker. Andre eksempler kan være at når tekstbokser trykkes på (se figur 4.1), dannes det en tekst- "cursor" i tekstboksen, samtidig som det dannes en blå ramme rundt boksen. Dette hjelper brukeren med å se hvor han eller 3
hun måtte befinne seg i brukergrensesnittet. Dette er også med på å skille ut de ulike elementene som finnes. Figur 4.1: Tekstboks Knapper og ikoner Vi skulle implementere mye forskjellig funksjonalitet og det ble nødvendig med en del knapper, tekstbokser og avkryssingsbokser i applikasjonen. For at funksjonene bak dette skulle komme så tydelig frem som overhode mulig bestemte vi oss for å bruke passende ikoner og tekst på alle knapper og bokser (se figur 4.2). Dette ville gjøre det enklere for brukeren å forstå hva de ulike funksjonene som vil bli utført. Vi har heller ikke som oppgave å designe knapper og tilpasse disse med ikoner og glyphicons, fordi disse vil også tilpasses av oppdragsgiver i deres systemer. Men vi designet elementene mest mulig etter oppdragsgivers behov. Figur 4.2: Knapper og ikoner Teknisk beskrivelse av applikasjon I dette kapitlet blir det beskrevet om generelle tekniske funksjoner i applikasjonen. Mako framework Det ble tidligere gitt en kort beskrivelse av det rammeverket vi benyttet oss av under prosjektet i prosessrapporten. Rammeverket som ble brukt som har blitt nevnt, er Mako framework. Mako (ref: makoframework) er et open- source applikasjonsrammeverk skrevet i PHP. Rammeverket inneholder en rekke komponenter som restful routing, ORM, autentisering med mer, og har som mål å gjøre det raskt og enkelt å lage raske og sikre webapplikasjoner. I likhet med mange andre rammeverk er det inspirert av MVC (se side5) designmønsteret. 4
Design Applikasjonen er basert på Bootstrap sitt bibliotek, som bruker kolonner og rader for å plassere HTML- elementer. Dette er et mye brukt stil- rammeverk grunnet den responsive naturen, som fører til at applikasjonen blir god å bruke på forskjellige skjermstørrelser. Vi har lagd vårt eget CSS- ark der vi overstyrer de vanlige attributtene hvis det har vært nødvendig, men til syvende og sist skal applikasjonen integreres med Digitalarkivet sitt system, og vil arve deres fargespektrum, tekst og unike valg. Vi har brukt Bootstrap sin hjemmeside http://www.getbootstrap.com/ når det har vært behov for rådføring og brukerinstruks hvis vi skulle bruke nye komponenter. Tilbakemelding til bruker Figur 4.3: Tilbakemelding til bruker Applikasjonen har behov for å gi tilbakemeldinger til bruker, så det benyttes en valideringsmeldinger (se figur 4.3) når bruker ikke har fylt ut obligatoriske felter ved lagring av innhold. Det er vi som utviklere som definerer de obligatoriske feltene, fulgt av oppdragsgiver sine krav. Om en valideringsmelding dukker opp, betyr det at skjemaet brukeren fyller ut mangler input, og brukeren blir nødt til å fylle ut de nødvendige feltene. Markdown Markdown (ref: daringfireball) er et tekst- til- HTML konverteringsverktøy for skriving i web. Tankegangen med bruk av dette verktøyet er at når brukeren skriver, benyttes et easy- to- read, easy- to- write- format. Når brukeren velger et av funksjonene i verktøyet, konverterer Markdown den til en HTML- struktur. Fordelen ved å benytte dette verktøyet er at brukeren får en bedre skrive- og leseopplevelse, derav at det er hurtig, og enkelt for den som skal skrive tekstinnhold til nettsider. Ved denne formateringen får det endelige produktet en mer stilren og pen formatering. Vi har benyttet oss av Bootstrap- Markdown. Biblioteket vi benyttet oss av er hentet fra http://www.codingdrama.com/bootstrap- markdown/ Figur 4.4: Markupen er blitt satt 5
Figur 4.5: Konverteringen er blitt utført, og teksten blir forhåndsvist via to- markdown biblioteket Språkpakke Vi har bygd opp en pakke med engelsk og norsk språk (se figur 4.6) for å kunne presentere programmet til en bredere brukergruppe. En språkpakke er uendelig utvidbar, og nå som det allerede er implementert en språkpakke, er det enkelt å kunne legge til flere språk. Når språket endres vil labels, overskrifter, knapper og alt annet av statisk tekst endres til det relevante språket. Figur 4.6: Endring av språk 6
Programmets oppbygging og virkemåte I dette kapitlet vil det detaljert vises hvordan oppbygningen av de ulike delene av applikasjonen er satt opp, og hvilke komponenter samt virkemåte som er benyttet. Model- view- controller MVC (Ref: Tor Krattebøl) Model- view- controller er et applikasjonsmønster. Dette betyr at det er en standard applikasjonsarkitektur, oppbygning og design, som er brukt av mange leverandører av webapplikasjoner. Arkitekturen består av fire hoveddeler, en modell (Model), logisk mellomlag (repository/interface), en kontroller (Contoller), og en presentasjonsdel (View). Vi brukte denne applikasjonsarkitekturen under i utviklingen av programmet. Arkitekturen ser slik ut (se figur 4.7): Figur 4.7: Arkitekturen av MVC Inspirasjon fra Tor Krattebøl, Webapplikasjon, forelesning uke 41, 2014 MVC Hvordan denne kombinasjonen fungerer: Det er Controller som styrer det hele. Hensikten med repository er at ikke all virksomhetselogikk skal ligge i en controller, men heller dele opp koden som visningslogikk og databaselogikk. Samtidig som dette, vil dette laget styres av hvilke view's som skal kalles på. Modellen skal som før, kun inneholde databaserelasjoner. View's er presentasjonslaget, altså det fremviser dataene i et brukergrensesnitt, og består av HTML for hvert View. Når man for første gang skriver inn en URL til applikasjonen gjøres dette mot controlleren. Det vil si at man ved å oppgi en URL starter en metode i en controller- klasse. Denne 7
metoden kan utføre virksomhetslogikken og databaselogikken. Videre vil den kalle opp et view. Det er i dette view'et vi kan vise data fra controlleren. Dersom vi skal ha mulighet for å skrive data inn i et skjema for å lagre dette i databasen må view et som vises inneholde et slikt HTML- skjema. Når et kall gjøres i dette view et bestemmer skjemaet hvilken controller og hvilken metode i denne som skal kalles, ved hjelp av HTML <form action>. Inne i denne metoden vil så dataene fra skjema være tilgjengelig og vi kan skrive kode for å sende dataen fra controller, til interface, til repository, helt ned til modell- laget som manipulerer databasen etter forespørsel. Fordeler med MVC: (ref: itpro) God struktur og gjenvinnbar kode Kraftig URL- mapping Støtter funksjoner som autentisering Enklere å utføre tester God oversikt og skille mellom de ulike applikasjonslagene Med en slik inndeling kan man endre på brukergrensesnitt uten at dette har noen innvirkning på hvordan dataene blir håndtert Endringer av hvordan dataene håndteres påvirker heller ikke brukergrensesnittet En modell kan representeres til brukeren på flere måter (flere views) Model database Dette laget i strukturen setter opp relasjonene tabellene har til hverandre i databasen. ORM som gjør det mulig å kartlegge alle relasjoner i databasen støtter hasone(), belongsto(), hasmany() og manytomany() relasjonstyper. Modellen lagrer data, og en relevant controller henter ut dataen som skal vist i grensesnittet. Når det skjer en endring mot modellen er det controller som sender oppdateringen gjennom MVC strukturen. For å se databasen i sin helhet med relasjoner henviser vi leser til dette kapittelets vedlegg 3. 8
Her ser vi (se figur 4.8) et eksempel på hvordan modellkoden bygges opp. Hver relasjon context har til andre tabeller i databasen blitt definert i henhold til om det er en mange- til- mange relasjon, hører- til relasjon, en- til- mange relasjon eller en- til- en relasjon. Figur 4.8: Tabell fra database og modellkode Figur 4.9 Tabell fra database Denne tabellen (se figur 4.9) er definert av en mange til mange relasjon mellom context og languages, og betyr at man kan ha flere språk til en kontekst, en enkel hjelpetabell for å unngå dobbellagring. Repository/Interface Logisk mellomlag Dette er et lag som lar deg isolere store deler av den logiske koden, slik at man ikke trenger å legge all logikk i controller. Dette har en hensikten med å enklere kunne teste kode, gjenbruk av metoder i flere deler av prosjektet, og forenkling av vedlikehold i det logiske laget. Ved å legge til dette laget har vi tatt høyde for at Digitalarkivet kan bytte ut den underliggende databasestrukturen, og bare endre i dette logiske mellomlaget. Controller logikk Denne delen av strukturen sender kommandoer til repositories, gjennom interface, for å endre modellens tilstand; endre, slette eller legge til et objekt. Den er også ansvarlig for 9
hvordan modellens innhold skal representeres til brukeren. Hovedsakelig responderer controlleren på en klientforespørsel og konstruerer en respons, og via Mako sitt routing bibliotek kan du dirigere controllerens respons og sende brukeren til riktig sted. View utseende Viewet er delen der all HTML i applikasjonen skal skrives. Et view kan være en hel webside eller bare deler av en, som header eller footer. Bruken av views lar deg separere logikken og presentasjonen av en applikasjon, som tillater uavhengig utvikling, testing og vedlikehold av MVC lagene. Generell kommentarer til kode Biblioteker Bootstrap - Tidligere kalt twitter Bootstrap er et verktøy for å lage nettsider og webløsninger. Bootstrap inneholder HTML og CSS design elementer for utvikling og design, og tilpasses godt til mobile løsninger. Det inneholder maler for typografi, former, knapper, navigasjon og andre grensesnitt komponenter. Bootstrap har også en valgfri JavaScript utvidelse. Bootstrap Markdown - Gjør det mulig å integrere Bootstrap tekstområder med markup funksjonalitet. Slik at man kan enkelt modifisere teksten sin med HTML markup, uten å huske all syntaksen. To- markdown - En tredjepart pakke som gir muligheten til å foråndsvise teksten som HTML i det definerte tekstområdet. Jquery - Jquery er et JavaScript- bibliotek utviklet for å forenkle klientskripting av HTML. Dette brukes for å kunne lettere navigere et dokument. jquery File Upload - Håndterer fil opplasting via jquery kall, og er lett til passelig med Bootstrap og HTML. Select2 - Gjør vanlige selectbokser meget tilpasningsvennlig, og gir støtte for søk, uendelig scrolling, tagging og mye mer. Autosize - Et enkelt script som automatisk ekspanderer våre spesifiserte tekstområder til en maksimum definert høyde. League Commonmark - Gir et enkelt system for å formatere markdown i backend, det gir betydelig bedre ytelse på større nettsider siden det ligger cachet som HTML i databasen, og det må da ikke bygges for hver sidelasting. 10
Bruk av kommentarer Vi har fulgt PHPdoc, som er en adapsjon av Javadoc, som igjen er den uformelle standarden for å kommentere PHP kode. Det er en kort beskrivelse, etterfulgt av parametere og returverdier, se figur 4.10. Figur 4.10: Kommentarstil Mako biblioteker mako\session\session - Biblioteket brukes til å persistere data mellom sidevisninger. mako\view\viewfactory - ViewFactory- klassen brukes til å generere et view- objekt som senere skal gjengi output til http. mako\http\request - Et abstraksjonslag som lar deg hente data fra klientforespørselen, for eksempel formdata, requestheader, med mer. mako\http\response - Et abstraksjonslag som lar deg manipulere tjenerresponsen. mako\validator\validatorfactory - Klassen returnerer et valideringsobjekt som brukes til å validere brukerinput ved hjelp av predefinerte regler. mako\http\routing\urlbuilder - En klasse som lar deg returnere en komplett url basert på egendefinerte navn. mako\utility\uuid - Klassen generer en unik universell identifikator som vi bruker for å kollisjon på filnavn. mako\utility\humanizer - Brukes til å formatere bytes til et leservennlig format. mako\utility\str - En klasse som inneholder metoder for stringmanipluering, og er brukt i vårt tilfelle for å generere slugs for url. mako\database\midgard\orm - Mako ORM er en implementasjon av active record designmønsteret som inneholder funksjonalitet for å snakke med en relasjonsdatabase. mako\file\filesystem - Et abstraksjonslag som lar oss jobbe med filer og filsystemer, med denne klassen unngår vi mye boiler- plate kode. mako\auth\gatekeeper - Biblioteket lar oss håndtere brukerinnlogging og autentisering. 11
Informasjonsarkitekturen bak utviklingen av applikasjon I dette kapitlet skal vi se på hvordan arkitekturen for applikasjonen er bygget opp. Informasjonsarkitekturen (ref: Gerd Berget) definerer noe om hvordan design og informasjon er strukturert. Det er en kombinasjon av organisering, navngivning og navigasjonssystemer. Arkitekturen sier noe om kunnskapen for hvordan man kan fremme brukervennlighet og gjenfinnbarhet sammen med designprinsipper for det digitale landskapet. Organiseringsstruktur Strukturen må være så god at brukeren ser hvor elementer er plassert i forhold til hverandre. Med det som bakgrunn valgte vi en hierarkisk struktur. Denne strukturen er en av de mest brukte strukturene på en webside, noe som gjør det enkelt og gjenkjennbart for brukeren. Ved hjelp av denne strukturen ønsket vi en top- down tilnærming, den nevnte strukturen gir en oversikt over hva som finnes av informasjon for de ulike elementene på skjermen. Det vi ønsket å oppnå ved en slik flat struktur, er at brukeren utfører få klikk for å komme til målet sitt. Fordelen med en flat struktur er at utviklingen av strukturen blir bedre for videre implementering av funksjonene, og dermed kreves det ikke mye rekonstruering av organiseringen. Eneste ulempen vi så ved en slik struktur, var at det til tider kan bli for mange valg for brukeren. Samtidig ser vi at dette er nødvendig ettersom innholdet er så stort. Under er den hierarkisk organiseringsstrukturen for applikasjonen presentert (se figur 4.11): 12
Figur 4.11: Hierarkisk struktur I følge (ref: Sciencedirect) kan en gjennomsnittlig person ha 7 ± 2 objekter i korttidsminnet. Dette brukte vi som en regel for antall valg som tilbys. Og valgene vi tilbyr har maks 7 valg i hele strukturen. 13
Bruk av navigering/ labels for å forenkle navigering Ved hjelp at blueprints, altså en beskrivelse av alle aspekter ved tjenesten i nok detalj, slik at den kan verifiseres og vedlikeholdes, kan vi vise hvordan applikasjonen er bygget opp. Samtidig som vi kan se hvordan de forskjellige komponentene henger sammen. Her viser vi hvordan organiseringen, navigeringen og labels vises på applikasjonen når bruker oppretter en ny artikkel (se figur 4.12): Figur 4.12: Blueprints av hvordan man oppretter en artikkel. Se vedlegg 3 for hva de ulike mønsterne betyr 14
Grupperingsmetoder til å kategorisere innhold for kategorier For å lage kategorisere brukte vi en tvetydig grupperingsmetode som tar utgangspunkt i hvilke kontekst brukeren befinner seg i. Vi tror at denne grupperingsmetoden gjør det enkelt for bruker å finne den informasjonen de faktisk er på jakt etter. Denne typen gruppering tillater å sortere kategorier på en intellektuell måte, og grupperingsmetoden er nyttig når man organiserer temaer som har sammenheng med hverandre. Denne metoden er en hybrid og har heller ingen krav om at grupperingen behøver å være alfabetisk, den er basert på en rekursiv sorteringsalgoritme som bare tar høyde for brukeren sin tidligere input. For å se denne strukturen som er beskrevet (se figur 4.13). Figur 4.13: Hierarkisk trestruktur av kategorier Figur 4.14: Ferdig utviklet kategoritre 15
Metadata Språk i brukergrensesnittet Det er viktig at språket i brukergrensesnittet er brukt for grupper av relaterte systemer. For at språket skal kunne øke gjenfinningen på nettstedet er det viktig med et språk som har kontroll over synonymer og økt konsistens. Språket som er benyttet, er et naturlig og gjenkjennelig språk. Dublin Core: Vi kan beskrive applikasjonen ved hjelp av et komplett sett av Dublin Core- elementer (ref: Gerd Berget). Dette brukes for å definere applikasjonen ved hjelp av 15 dataelementer. 1. Tittel: Publiseringssystem for Digitalarkivet 2. Opphav: Arkivverket - Digitalarkivet 3. Emne: Publisering 4. Beskrivelse: Publisere artikler i forskjellige kontekster 5. Utgiver: Arkivverket - Digitalarkivet 6. Bidragsyter: Arkivverket - Digitalarkivet 7. Dato: Ikke kjent 8. Type: Arkivmateriale, statlig og privat 9. Format: PHP, HTML 10. Identifikator: http://arkivverket.no/digitalarkivet 11. Kilde: http://arkivverket.no/digitalarkivet 12. Språk: Norsk, engelsk 13. Relasjon: Arkivverket og Digitalarkivet er organisert som et norsk statlig selskap 14. Dekning: Org.nr: 961 181 399. Pb 4013 Ullevål Stadion, 0806 Oslo 15. Opphavsrett: Arkivverket 2015 Sikkerhet I kravspesifikasjonen ble det nevnt følgende: "Som studentprosjekt utvikles det en "pakke" som skal inkluderes i deres systemer", og dermed er sikkerhetskrav noe oppdragsgiver selv tar høyde for, slik at dette blir tilpasset deres krav i systemet. Vi har selv lagt til en enkel innlogging, der brukerinformasjon blir validert. Som studentprosjekt tar vi høyde for hva brukergrensesnittet skal vise i forhold til hvilke rettigheter brukere får tildelt av administratorer. 16
Videreutvikling Som nevnt er vår applikasjon en pakke til et større system, som blir ferdigutviklet på et ubestemt tidspunkt. Dette medfører at det kan bli endring i prosjektet sin helhet når det gjelder rettigheter for brukere, dette inkluderer også spørringer mot databasen over hva som skal vises til brukere med forskjellige rettigheter. Dette betyr at videreutvikling av applikasjonen går ut på rettigheter og sikkerhet. Det kan også være mulighet for å åpne applikasjonen for tredjeparter, slik at de kan dele sine bilder eller gladsaker på en separert del av Riksarkivets nettsider. Alle punkter som oppdragsgiver selv skulle ta høyde for er for det meste lagt klart og til rette for i koden. 17
Referanser/ kilder Arkitektur. Om informasjonsarkitektur. Hentet 9.4.2015 fra Gerd Berget, forelesning i Informajosnsarkitektur 06.01.2014 Daringfireball. Om markdown. Hentet 20.5.2015 fra http://daringfireball.net/projects/markdown/ Itpro. Fordeler MVC. Hentet 18.2.2015 fra http://itpro.no/artikkel/13241/en- introduksjon- til- microsoft- mvc/ Mako framework. Om Mako framework. Hentet 10.3.2015 fra http://makoframework.com/ MVC. Om MVC. Hentet 18.2.2015 fra Tor Krattebøl, Webapplikajsoner, forelesning uke 37 2014 MVC MVC. Om MVC. Hentet 25.2.2015 fra Tor Krattebøl, Webapplikajsoner, forelesning uke 41 2014 MVC Sciencedirect. The Magical Number Seven, Plus or Minus Two. Hentet 15.4.2015 fra http://www.sciencedirect.com/science/article/pii/s0895717703900835 18
Vedlegg Vedlegg 1. Skisser Index Opprette konteks 19
Opprette artikkel Behandle kategorier Opplasting av bilde i artikkel 20
Vedlegg 2. Det endelige brukergrensesnittet Forside Opprette kontekst 21
Opprette artikkel Behandle kategorier Opplasting av bilde i artikkel 22
Vedlegg 3. Er- model (endret versjon av den som finnes i kravspesifikasjonen) 23
Vedlegg 4. Blueprints Beskrivelse av blueprints 24