Ismo Huhtiniemi
Paavo Itkonen
Joonas Lattu
Petteri Palojärvi
Seppo Tarvainen

Tekijät:

• Ismo Huhtiniemi (IH)
• Paavo Itkonen (PI)
• Joonas Lattu (JL)
• Petteri Palojärvi (PP)
• Seppo Tarvainen (ST)

Dokumentin nimi: Timber-sovellusprojekti, sovellusraportti

Tiivistelmä: Timber-projekti kehitti TIM-oppimisympäristöön WWW-sovelluksen, jonka avulla tehtävien tarkastusta voidaan yhdenmukaistaa ja nopeuttaa. Sovelluksen avulla TIM-ympäristössä olevien tehtävien vastauksiin voidaan tehdä merkintöjä, jotka sisältävät vakioidun huomion ("velppi") sekä mahdollisen pistemäärän ja vapaita kommentteja. Sovellusraportissa kuvataan sovelluksen kokonaisrakennetta, tavoitteiden toteutumista sekä heikkoja toteutusratkaisuja.

Muutoshistoria:

Timber-projektiryhmä kehitti TIM-oppimisympäristöön palautesovelluksen.

Tekijät:

• Ismo Huhtiniemi
• Paavo Itkonen
• Joonas Lattu
• Petteri Palojärvi
• Seppo Tarvainen

Tilaajat:

• Vesa Lappalainen
• Antti-Jussi Lakanen

Ohjaajat:

• Jukka-Pekka Santanen
• Mika Lehtinen

Yhteystiedot:

• Sähköpostilistat: timber@korppi.jyu.fi ja timber_opetus@korppi.jyu.fi
• Sähköpostiarkistot: https://korppi.jyu.fi/kotka/servlet/list-archive/timber ja https://korppi.jyu.fi/kotka/servlet/list-archive/timber_opetus

1. Johdanto

Timber-projekti kehitti kevään 2016 Sovellusprojekti-kurssilla TIM-oppimisympäristöön WWW-sovelluksen yhdenmukaistamaan ja helpottamaan tehtävien arviointia. Sovelluksen avulla tehtävän tarkastaja voi merkitä opiskelijan vastaukseen virheet sekä muut huomionarvoiset asiat. Merkintöihin voi sisällyttää myös pistemäärän sekä kommentteja, joilla voi muodostaa viestiketjuja.

Sovellusraportin laatimisessa on hyödynnetty Timber-projektin vaatimusmäärittelyä [1], Velp-toiminnon käyttöohjetta [2] ja Timppa-projektin sovellusraporttia [3]. Muita Timber-projektin laatimia olennaisia dokumentteja ovat projektiraportti [4], järjestelmätestausdokumentit [5], [6] ja [7], sovelluksen vaatimuksia [8] sekä luokkadokumentit [9] ja [10].

Sovellusraportti koostuu kuudesta luvusta. Luvussa 2 kuvataan sovelluksen kannalta keskeisiä termejä sekä luvussa 3 sovelluksen rakennetta ja toteutusratkaisuja. Luvussa 4 selitetään tarkemmin tietokannan rakennetta. Luvussa 5 arvioidaan tavoitteiden toteutumista ja heikkoja toteutusratkaisuja.

2. Termit

Luvussa kuvataan käyttäjän kannalta olennaisia aihealueen ja teknisiä termejä.

2.1 Aihealueen termejä

Aihealueen termejä ovat seuraavat:

• Avainsanan (eng. label) avulla velppejä voidaan ryhmitellä eri kategorioihin. Velppiin voi olla liitetty useampikin kuin yksi avainsana, mutta avainsanan liittäminen velppiin ei ole pakollista.
• Itsearvioinnissa opiskelija tarkastaa tekemänsä tehtävän itse.
• Merkintä (eng. annotation) sisältää velpin sekä mahdollisen pistemäärän ja vapaan kommentin. Merkintäikkunassa tarkastaja voi myös määritellä, ketkä merkinnän voivat nähdä.
• Opettaja vastaa tehtävien luomisesta TIM-dokumenttiin ja usein myös tehtävien tarkastamisesta.
• Opiskelija vastaa TIM-dokumentissa olevaan tehtävään ja tallentaa vastauksen tarkastamista varten.
• Reunamerkintä on kappaleen reunaan sijoittuva merkintä, jota käytetään kun merkintää ei voida tai haluta laittaa suoraan huomionarvoisen asian kohdalle.
• Tarkastusalue on TIMin dokumentti, kappale tai tehtävä. Siihen voidaan kirjata merkintöjä sekä liittää velppikokoelmia.
• TIM (The Interactive Material) on Jyväskylän yliopistossa kehitetty WWW-oppimisympäristö.
• Velppi (eng. velp) on vakioitu huomio, jolla tarkastaja voi osoittaa virheen tai muun huomionarvoisen asian opiskelijan tallentamassa vastauksessa. Velppiin voidaan tallentaa myös oletuspistemäärä.
• Velppikokoelma (eng. velp group) on joko oletuskokoelma tai käyttäjän luoma kokoelma. Jokainen velppi kuuluu johonkin kokoelmaan. Jos käyttäjä ei toisin valitse, hänen luomansa velppi sijoitetaan hänen henkilökohtaiseen tai dokumentin oletuskokoelmaan.
• Vertaisarvioija on opiskelija, joka tarkastaa toisen opiskelijan vastauksen tehtävään.

2.2 Teknisiä termejä

Käyttöliittymän tekniikoita ja kehitystyökaluja ovat seuraavat:

• CSS (Cascading Style Sheets) on kokoelma tyyliohjeita, joilla yhdessä HTML:n kanssa muotoillaan WWW-sivun ulkoasu.
• HTML (HyperText Markup Language) on koodauskieli, jonka avulla WWW-sivun sisältö näytetään käyttäjälle.
• HTTP-pyyntö on WWW-selaimen lähettämä pyyntö palvelimelle.
• JavaScript on komentosarjakieli, jolla voidaan lisätä WWW-sivulle dynaamista toiminnallisuutta.
• JSON (JavaScript Object Notation) on tiedonsiirrossa käytettävä tiedostomuoto.
• Ohjain toimii välittäjänä järjestelmän eri osien välillä.
• Python on ohjelmointikieli, jolla TIMin palvelimen sovelluslogiikka on ohjelmoitu.
• SQL (Structured Query Language) on tietokantojen luomiseen ja hallintaan kehitetty ohjelmointikieli.
• WWW-selain on sovellus, joka pyytää WWW-sivuston palvelimelta ja esittää sen käyttäjälle.

2.3 Ulkopuoliset komponentit

Sovellus hyödyntää seuraavia sovelluskehyksiä ja muita ulkopuolisia komponentteja:

• AngularJS on JavaScript-sovelluskehys, jonka avulla mm. haetaan ja muokataan käyttöliittymän dataa.
• Bootstrap on sovelluskehys, jonka avulla on toteutettu käyttöliittymän layout.
• Flask on sovelluskehys, jonka avulla on toteutettu palvelimen reitit.
• Dumbo kääntää TIMin tekstieditorilla tehdyt merkinnät HTML:ksi, ja se sisältää myös tuen matemaattisille symboleille.
• Docker on avoimeen lähdekoodiin perustuva jalusta, jonka avulla voidaan rakentaa, välittää ja suorittaa jaettuja sovelluksia.

Lisää teknisiä termejä on selitetty luvussa 3.

3. Sovelluksen kokonaisrakenne

Luvussa esitellään Velp-sovelluksen taustaa ja tavoitteita, sekä sovelluksen rakennetta, toteutusratkaisuja ja ulkopuolisia komponentteja. Tietokantaa ja käyttöoikeuksien toteutusta on kuvattu tarkemmin luvussa 4.

3.1 Sovelluksen taustaa ja tavoitteita

Tilaajan tarpeena oli sovellus, jolla voidaan tukea ja yhtenäistää tehtävien tarkastusta ja palautteen antamista. Tällaista sovellusta käytettäessä niin opettaja kuin opiskelijakin näkevät yhteenvedon tehdyistä virheistä sekä muista huomionarvoisista asioista, ja näin molemmat tietävät, mihin asioihin tulisi jatkossa kiinnittää mahdollisesti enemmän huomiota.

Sovelluksen tuli mahdollistaa tehtävien nopeampi tarkastus, jolloin opettaja voi keskittyä enemmän erityishuomiota vaativiin asioihin rutiinin sijaan. Toinen sovelluksen keskeinen hyöty on se, että tehtävien tarkastamisesta tulee tasa-arvoisempaa, kun kurssin jokaisen opiskelijan vastaus tarkastetaan samojen velppien avulla. Tämän merkitys korostuu kursseilla joilla käytetään apuopettajia, koska sovelluksen avulla apuopettajat on helpompi kouluttaa tarkastamaan tehtäviä yhdenmukaisesti.

Sovellus voi myötävaikuttaa myös opetuksen laajempaan kehittämiseen, kun opettajille jää enemmän aikaa huomiota vaativiin asioihin. Yhdenmukaisempien tarkastuskriteerien ansiosta opettajien on myös helpompi laatia vertailukelpoisia tilastoja eri vuosien tuloksista. Sovellus kehitetään virtuaaliseen TIM-oppimisympäristöön, jota voidaan käyttää kaikilla oppiasteilla.

3.2 Sovellus pääpiirteittäin

TIM-oppimisympäristö ja siten myös Velp-sovellus jakautuu kuvan 3.1 mukaisesti päätelaitteen käyttöliittymään, palvelinsovellukseen ja tietokantaan.

Päätelaitteen WWW-selaimella käytetään TIMin asiakassovellusta, eli tässä tapauksessa Velp-toiminnon käyttöliittymää. Käyttöliittymässä esitettävät näkymät ja niiden toiminnot riippuvat käyttöoikeuksista. Käyttöliittymää on esitelty tarkemmin Velp-toiminnon käyttöohjeessa [2].

Palvelin vastaanottaa pyyntöjä WWW-selaimelta ja lähettää pyynnöt edelleen tietokantaan. Palvelin myös välittää datan tietokannasta päätelaitteelle.

Tietokanta sisältää sovelluksen varastoimat tiedot. Timber-projektissa tietokantaan lisättyjä tauluja ja kenttiä kuvataan luvussa 4.

Yleisessä käyttötilanteessa käyttäjä navigoi laitteensa WWW-selaimella TIM-ympäristöön, kirjautuu sisään, ja navigoi edelleen Velp-käyttöliittymään. Tämän jälkeen hän suorittaa käyttöliittymässä jonkun toiminnon, jolloin selain lähettää palvelimelle toimintoon liittyvät tiedot HTTP-pyynnöllä. Palvelin tarkastaa että pyyntö on hyväksyttävä, sekä tarvittaessa suorittaa kyselyn tietokantaan tai tallentaa dataa tietokantaan. Seuraavaksi palvelin vastaa käyttäjälle lähettämällä vastauksen JSON-muodossa. Käyttöliittymä käsittelee saamansa vastauksen ja esittää sen käyttäjälle.

3.3 Sovelluksen osat

WWW-sovellukset voivat toimia käyttöliittymän ja palvelimen välisinä pyyntöinä ja vastauksina, mutta projektissa kehitetyssä sovelluksessa myös tietokannan käyttö on käytännössä välttämätöntä. Vaikkei käyttäjän tarvitse luoda uusia velppejä, hänen tulee kuitenkin hakea jo luotuja velppejä tietokannasta. Myös tehdyt merkinnät sekä velpit ja velppikokoelmien sisältö tallentuvat tietokantaan.

Velp-sovellus koostuu kuvan 3.2 mukaisesti seuraavista tasoista:

• Käyttöliittymä on sovelluksen näkyvä osa, jonka avulla käyttäjä käyttää sovellusta.
• Käyttöliittymän ohjaimet tarkistavat käyttäjän syötteet sekä kommunikoivat palvelimen kanssa HTTP-pyyntöjen välityksellä.
• TIMin WWW-sivut tiedostoineen on tallennettu palvelimelle, joka mm. varmistaa käyttäjällä olevan oikeus toteuttaa HTTP-pyynnön mukainen toiminto. Palvelin toimii välittäjänä käyttöliittymän ja tietokannan välillä, sekä aina tarvittaessa kutsuu tietokannan ohjaimissa olevia metodeja.
• Tietokannan ohjaimet tekevät tarvittavat muutokset tietokantaan tai hakevat sieltä tarvittavan tiedon.
• Tietokantaan tallentuu sovelluksessa tarvittava data.

Käyttöliittymän ulkoasun osalta olennaisimpia tiedostoja ovat seuraavat:

• static/css/velpSelection.css sisältää suuren osan käyttöliittymän tyyleistä.
• static/templates/annotation.html on merkintöjen HTML-tiedosto.
• static/templates/velpSelection.html on velp-valikon (Velp menu) HTML-tiedosto.
• templates/velp_view.html toimii pääluokkana velp-käyttöliittymälle.

Käyttöliittymän toiminnallisuuden osalta olennaisimpia tiedostoja ovat seuraavat:

• static/scripts/controllers/reviewController.js sisältää suuren osan metodeista, joiden avulla velppejä kirjataan tarkastuksen aikana.
• static/scripts/directives/annotation.js ohjaa merkintöjen toiminnallisuutta.
• static/scripts/directives/velpSelection.js ohjaa velp-käyttöliittymän toimintaa lähtötilanteessa.

Palvelimen osalta olennaisimpia tiedostoja ovat seuraavat:

• routes/annotation.py määrittelee palvelimelle reitit, jotka liittyvät merkintöihin.
• routes/velp.py määrittelee palvelimelle reitit, jotka liittyvät velppeihin ja velppikokoelmiin.

Tietokannan osalta olennaisimpia tiedostoja ovat seuraavat:

• schematimber.sql luo sovelluksen tarvitsemat taulut ja näkymät tietokantaan.
• timdb/annotations.py sisältää merkintöihin liittyvät SQL-skriptit.
• timdb/icons.py sisältää ikoneihin liittyvät SQL-skriptit.
• timdb/velpgrouplabels.py sisältää velppikokoelmien avainsanoihin liittyvät skriptit.
• timdb/velpgroups.py sisältää velppikokoelmiin liittyvät skriptit.
• timdb/velps.py sisältää velppeihin liittyvät SQL-skriptit.

Timber-projektissa täydennettyjä tiedostoja ovat muun muassa seuraavat:

• initdb2.py luo tietokannan.
• static/scripts/view_html.js toimii pääluokkana käyttöliittymän ohjaimille.
• static/stylesheet.css sisältää osan koko TIMin tyyleistä.
• templates/view_html.html toimii pääluokkana TIMin eri näkymille.
• tim.py sisältää mm. koodin, joka rekisteröi käytössä olevat reitit.
• timdb/timdb2.py alustaa tietokannan ohjaimet.

3.4 Toteutusratkaisut

Luvussa on kuvattu sovelluksen keskeisten toimintojen toteutusratkaisuja.

3.4.1 Merkintöjen teko

Merkintöjen teon yhteydessä sovellus tarkistaa ensin, minkä alueen käyttäjä on tekstistä valinnut. Mikäli valitussa alueessa on joitain vaatimuksissa 1.10-1.12 (Viimeksi valittu merkintä näytetään päällimmäisenä, Merkinnän tekeminen tulee estää silloin kun merkinnän sisälle jää toinen merkintä, Merkinnän tekeminen tulee estää toisten merkintöjen sisälle) mainittuja piirteitä, merkintä tullaan asettamaan reunamerkinnäksi. Jos puolestaan tekstiä ei ole valittuna, mutta jokin kappale on valittuna, tullaan kappaleeseen sijoittamaan reunamerkintä.

Kun valittu alue on määritelty ja käyttäjä klikkaa velppiä, valittuun alueeseen liitetään merkintä. Valittu alue yksilöidään tietokantaan tallennusta varten asiakassovellukessa mm. seuraavilla attribuuteilla:

• par_id määrittää kappaleen ID:n.
• t määrittää kappaleen tiivisteen.
• el_path sisältää listan elementtipolusta elementtien järjestyksen mukaan kappaleessa. Esimerkiksi jos kappale on ensimmäisen elementin toisessa lapsielementissä, arvoksi tulee [0, 1].
• node määrittää merkinnän noden järjestysnumeron. Esimerkiksi jos merkintä sijoittuu ensimmäisessä elementissä elementin ensimmäisen lapsen jälkeen ja lapsi ei sijaitse elementin alussa, arvoksi tulee 2 (järjestysnumero alkaa numerosta 0).
• offset määrittää merkin järjestysnumeron nodessa

Kaikki yllä mainitut attribuutit tallennetaan erikseen valitun alueen alkamis- ja loppumiskohdissa. Näiden lisäksi merkinnän tallennusta varten tarvitaan esimerkiksi myös velppi, pistemäärä ja käyttöoikeudet. Kun merkinnän tiedot ovat selvillä, se lähetetään palvelimelle. Vastaavien tietojen perusteella sovellus osaa ladata käyttäjien tekemät merkinnät sivulle. Merkintöjen ladonta aloitetaan takaperin, sillä attribuutteihin el_path, node ja offset vaikuttaa aiemmat merkinnät.

Merkintöjen muokkaaminen ja poistaminen ovat yksinkertaisia operaatioita, jotka suoritetaan palvelimella merkinnän id-attribuutin perusteella. Muokatessa ja poistettaessa tarkistetaan aina se, onko käyttäjällä riittävästi oikeuksia muokkausten tekoon. Käyttöliittymässä on esitetty harmaana toiminnot, johon käyttäjällä ei ole oikeuksia.

3.4.2 Velppien hallinta merkintöjen teon yhteydessä

Velppien lisäys ja muokkaus on sovelluksessa toteutettu yksinkertaisina operaatioina, jotka suoritetaan palvelimella velpin id-attribuutin perusteella. Uusi velppi voidaan luoda vain, jos sen nimessä on vähintään yksi merkki ja jokin velppikokoelma on valittuna.

3.4.3 Avainsanojen hallinta velppien lisäämisen tai muokkaamisen yhteydessä

Avainsanojen lisääminen ja muokkaaminen sovelluksessa tapahtuu aina velppien lisäämisen tai muokkaamisen yhteydessä. Avainsanoja ei voi poistaa, mutta avainsanaa ei näytetä käyttäjälle, jos se ei esiinny missään dokumentin velpissä.

3.4.4 Velppien haku ja järjestäminen merkintöjen teon yhteydessä

Velppien haku tai järjestäminen hoidetaan yksinomaan käyttöliittymässä. Siitä ei siis tallennu tietokantaan tietoja myöhempää käyttöä varten. Esimerkiksi valittu järjestysperiaate ei säily sivun seuraavaan latauskertaan.

3.4.5 Velppikokoelmien näkyvyys

Velppikokoelmien näkyvyys tarkastusalueessa määräytyy default- ja show-valintaruutujen arvojen mukaan, kuvan 3.3 mukaisesti. Jos default-valintaruutu on valittu, myös vastaava show-valintaruutu on valittuna kyseisessä kappaleessa tai koko dokumentissa, mikäli käyttäjä ei ole tätä show-valintaa muuttanut. Dokumentin oletuksena näkyy aluksi dokumentin oletusvelppikokoelma sekä käyttäjän henkilökohtainen velppikokoelma. Näkyvyys kappaleessa määräytyy dokumentin tasolta, mikäli default-valintaruutua ei ole kappaleessa valittu.

3.4.6 Dokumentin velppikokoelmien hallinta

Sovelluksen velppikokoelmat on toteutettu TIM-dokumentteina, joten niihin liittyvä käyttäjäoikeuksien hallinta voidaan suorittaa dokumentin käyttäjäoikeuksien kautta. Kaikki hakemiston velppikokoelmat tallennetaan kyseisen hakemiston velp groups -kansioon. Dokumentin velppikokoelmat tallennetaan tällöin hakemistopuussa osoitteeseen velp groups/dokumentin nimi/kokoelman nimi. Koko kansioon liittyvät kokelmat tallennetaan osoitteeseen velp groups/kokoelman nimi ja henkilökohtaiset kokoelmat osoitteeseen users/käyttäjänimi/velp groups/kokoelman nimi.

3.4.7 Palautenäkymän toiminnallisuudet

Vaatimukset 7.1 (Tehtävään vastannut käyttäjä näkee tarkastajan vastaukseen kirjaamat merkinnät) ja 7.2 (Tehtävään vastannut käyttäjä voi lisätä kommentteja saatuihin merkintöihin) toimivat suoraan vaatimusten 1.3 (Tarkastusalueen tekstissä korostetaan kohta, johon on liitetty merkintä) ja 1.5 (Merkintään tulee voida lisätä kommentti) kautta.

4. Tietokannan rakenne

Luvussa mainitaan käyttöoikeuksien toteutus, projektissa käytetyt jo olemassa olleet tietokantataulut, sekä kuvataan tarkemmin projektissa lisättyjä tietokantatauluja ja niiden kenttiä.

4.1 Käyttöoikeudet ja vanhat taulut

Sovelluksen tarvitsemat käyttöoikeudet toteutetaan pääasiassa hyödyntäen TIMissä jo olemassaolevaa toiminnallisuutta. Suoria SQL-hakuja tauluihin ei kuitenkaan tarvitse suorittaa, vaan jo olemassaolevien funktioiden kutsuminen riittää.

User-taulusta haetaan tarvittaessa käyttäjän nimi esimerkiksi silloin, kun halutaan näyttää kommentin tai merkinnän kirjannut käyttäjä.

UserAnswer-taulua käytetään selvittämään, minkä käyttäjän tai käyttäjien laatima vastaus on kyseessä.

Jotkin Timber-projektissa lisättyjen taulujen kentät viittaavat TIMin taulujen kenttiin, vaikka velp-sovelluksen lähdekoodi ei näitä tauluja käytä. Tällaisia ovat esimerkiksi käyttäjäryhmien tunnukset. Velppikokoelmien tunnukset ovat myös block-taulun tunnuksia.

4.2 Projektissa lisätyt taulut

Luvussa on kuvattu projektissa tietokantaan lisättyjä tauluja. Tietokannan ER-kaavio on kuvassa 4.1 luvun lopussa.

Annotation-tauluun tallennetaan kirjatut merkinnät, ja se sisältää seuraavat kentät:

• id on merkinnän yksilöivä tunnus.
• velp_version_id on merkinnässä käytetyn velpin version tunnus.
• icon_id on merkintään liitetty ikoni, jos sillä on sellainen.
• points on merkintään tallennettu pistemäärä.
• creation_time on merkinnän luontiaika.
• valid_from ja valid_until määrittävät merkinnän voimassaoloajan. Merkintöjen poisto toteutetaan näiden avulla.
• annotator_id on merkinnän tehneen käyttäjän tunnus.
• visible_to on käyttäjältä vaadittava oikeustaso, jolla merkintä näkyy.
• document_id on dokumentin tunnus, jossa merkintä on.
• answer_id on vastauksen tunnus, jossa merkintä on.

Merkinnästä tallennetaan alku- ja loppupaikka, joten Annotation-taulu sisältää lisäksi seuraavat _start ja _end -loppuiset kentät:

• paragraph_id on tunnus kappaleelle, johon merkintä on kirjattu.
• offset kertoo, monennestako textnoden merkistä merkintä alkaa tai monenteenko se loppuu.
• node kertoo, monennestako textnodesta merkintä alkaa tai monenteenko se loppuu.
• depth on elementtipolun pituus.
• hash on merkinnän sisältävän kappaleen tiiviste.
• elemenent_path kertoo html-elementin, jonka sisältä merkintä alkaa tai jonka sisälle se loppuu.

AnnotationComment-tauluun tallennetaan merkintöihin tehdyt kommentit, ja se sisältää seuraavat kentät:

• id on kommentin yksilöivä tunnus.
• annotation_id on tunnus merkinnälle, johon kommentti liittyy.
• comment_time on kommentin kirjaushetki.
• commenter_id on kommentin kirjaajan yksilöivä tunnus.
• content on kommentin sisältö.

Icon-taulu sisältää ikoneiden tiedot, ja se sisältää seuraavat kentät:

• id on ikonin yksilöivä tunnus.
• filename on nimi tiedostolle, josta ikoni löytyy.

ImportedVelpGroups-tauluun tallennetaan tieto siitä, mitkä velppikokoelmat on lisätty mihinkin dokumenttiin. Taulu sisältää seuraavat kentät:

• user_group määrittää käyttäjäryhmän, jonka käyttöön velppikokoelma on lisätty.
• doc_id määrittää dokumentin, johon velppikokoelma on liitetty.
• target_type määrittää kohdetyypin, johon velppikokoelma on liitetty. Vaihtoehdot ovat dokumentti, kappale tai alue.
• target_id on kohteen yksilöivä tunniste.
• velp_group_id on velppikokoelman yksilöivä tunniste.

LabelInVelp-taulu määrittää velpin avainsanat, ja se sisältää seuraavat kentät:

• label_id on avainsanan yksilöivä tunnus.
• velp_id on velpin yksilöivä tunnus.

LabelInVelpGroup-taulu määrittää velppikokoelman avainsanat. Se sisältää seuraavat kentät:

• velp_group_id on velppikokoelman yksilöivä tunnus.
• group_label_id on velppikokoelman avainsanan tunnus.

Velp-taulu sisältää velppien tiedot, ja se sisältää seuraavat kentät:

• id on velpin yksilöivä tunnus.
• creator_id on velpin luojan yksilöivä tunnus.
• creation_time sisältää velpin luomisajan.
• default_points sisältää velpin oletuspisteet.
• icon_id viittaa Icon-taulussa määriteltyyn velpin ikoniin, jos sillä on sellainen.
• valid_from ja valid_until määrittävät velpin voimassaoloajan. Niitä käytetään velppien poistamiseen niin, että tieto jää kuitenkin talteen.

VelpContent-taulu yhdistää velpin nimen tiettyyn versioon ja kieleen. Se sisältää seuraavat kentät:

• version_id on velpin version yksilöivä tunnus.
• language_id on velpin kielen yksilöivä tunnus.
• content on velpin tekstisisältö.

VelpGroup-taulu sisältää velppikokoelmien tiedot, ja se sisältää seuraavat kentät:

• id on kokoelman yksilöivä tunnus.
• name on kokoelman nimi.
• creation_time on kokoelman luomisajankohta.
• valid_from ja valid_until määrittävät kokoelman voimassaoloajan. Niitä käytetään kokoelmien poistamiseen niin, että tieto jää kuitenkin talteen.
• default_group on tosi, jos velppikokoelma on oletusvelppikokoelma.

VelpGroupDefaults-taulu sisältää tiedon siitä, mitkä velppikokoelmat ovat dokumentin eri osissa oletuksena valittuina. Taulu sisältää seuraavat kentät:

• doc_id on dokumentin yksilöivä tunnus.
• target_type on velppikokoelman kohteen tyyppi, joka voi olla dokumentti, alue tai kappale.
• target_id on velppikokoelman kohteen yksilöivä tunnus.
• velp_group_id on velppikokoelman yksilöivä tunnus.
• selected on tosi, jos velppikokoelma on valittuna.

VelpGroupLabel-taulu sisältää velppikokoelman avainsanojen tiedot, ja se sisältää seuraavat kentät:

• id on avainsanan yksilöivä tunnus.
• content on avainsanan näkyvä tekstisisältö.

VelpGroupSelection-taulu sisältää käyttäjäkohtaisesti tiedon siitä, mitkä velppikokoelmat ovat kohteessa valittuina. Taulu sisältää seuraavat kentät:

• user_id on käyttäjän yksilöivä tunnus.
• doc_id on dokumentin yksilöivä tunnus.
• target_type on velppikokoelman kohteen tyyppi, joka voi olla dokumentti, alue tai kappale.
• target_id on velppikokoelman kohteen yksilöivä tunnus.
• velp_group_id on velppikokoelman yksilöivä tunnus.
• selected on tosi, jos velppikokoelma on valittuna.

VelpGroupsInDocument-taulu sisältää käyttäjäkohtaisesti dokumenttiin liitetyt velppikokoelmat, ja se sisältää seuraavat kentät:

• user_id on käyttäjän yksilöivä tunnus.
• doc_id on dokumentin yksilöivä tunnus.
• velp_group_id on velppikokoelman yksilöivä tunniste.

VelpInGroup-taulu yhdistää velpin ja velppikokoelman, ja se sisältää seuraavat kentät:

• velp_group_id on velppikokoelman yksilöivä tunniste.
• velp_id on velpin yksilöivä tunniste.
• points on velpin pistemäärä kokoelmassa.

VelpLabel-taulu sisältää avainsanojen tekstin käännöksineen, ja se sisältää seuraavat kentät:

• id on avainsanan yksilöivä tunnus.
• language_id on kielen yksilöivä tunnus.
• content on avainsanan sisältö.

VelpVersion-taulu yhdistää velpin sen eri sisältöversioihin, ja se sisältää seuraavat kentät:

• id on sisällön yksilöivä tunnus.
• velp_id on velpin yksilöivä tunnus.
• modify_time on version luontiaika.

5. Tavoitteiden toteutuminen

Huomattava määrä sovellukselle kirjattuja vaatimuksia ja ideoita sovittiin jatkokehitykseen. Projekti kehitti sovelluksesta prototyypin, ja sen rajattukin tuotantokäyttö vaatii jatkokehitystä. Kaikki tärkeimmät vaatimukset pystyttiin kuitenkin kehittämään sovellukseen. Kaikki vaatimukset sekä niiden toteutuminen on kuvattu vaatimusmäärittelyssä [1].

5.1 Vaatimusten toteutuminen

Timber-projektissa kirjattiin yhteensä 121 vaatimusta ja ideaa, joista kaikki välttämättömät 18 vaatimusta sekä 25 tärkeästä vaatimusta toteutettiin 24. Prioriteetin Ajan salliessa kaikki 26 vaatimusta sovittiin tilaajan kanssa jatkokehitykseen, kuten myös 51 ideaa. Prioriteetin Idea vaatimuksista 38 kirjattiin vaatimusmäärittelyyn sovellusprojektin viimeistelyvaiheessa. Yksi vaatimus kirjattiin prioriteetilla Ei toteuteta.

Sovelluksen ideoiduista toimintokokonaisuuksista ilmoitukset, vertaisarviointi ja korostusten hallinta olivat toissijaisia, joten kyseiset kokonaisuudet sovittiin jatkokehitykseen. Toteutettuja toimintokokonaisuuksia on kuvattu luvussa 3.4.

5.2 Heikot toteutusratkaisut

Sovelluksen teknisistä hankaluuksista, tekijöiden kokemattomuudesta sekä rajatuista työmääristä ja aikataulusta johtuen jotkin toteutetut ominaisuudet toimivat heikosti. Suuri osa ongelmista ilmenee käyttöliittymässä, mutta joitain puutteita ilmenee myös palvelinsovelluksessa.

5.2.1 Merkintöjen tekeminen

Merkintöjen teko onnistuu silloin, kun merkintä ei mene HTML-tagirajojen yli siten, että HTML-sivusta tulisi epävalidi. Merkintöjä voi siis tehdä tagirajojen yli, kun maalattu alue sisältää kokonaan jonkin HTML-elementin tekstikappaleen sisällä. Näitä elementtejä ovat mm. lihavoitu tai kursivoitu teksti.

Merkinnän koordinaatit haetaan käyttäjän maalamasta alueesta. Tietokantaan tallennetaan merkinnästä TIM-kappaleen id, elementin järjestysnumero, noden järjestysnumero, sekä koordinaatin alku- ja loppupaikka. Mikäli jatkokehityksessä toteutetaan merkintöjen teko HTML-tagirajojen yli, tulee tätä varten toteuttaa erillinen angular-directive, joka linkittää maalatut alueet viittaamaan oikeaan merkintään.

Seuraavissa esimerkeissä käytetään seuraavaa HTML-koodin osaa:

<p>
	Teksti <strong> jatkuu lihavoituna </strong><em>ja kursivoituna tänne asti.</em>
</p> 

Esimerkiksi, jos merkintä menee yhden tagirajan yli, voidaan muodostaa seuraavanlainen HTML-puurakenne. Esimerkissä tagiraja rikkoontuu, sillä strong-elementtiä ei ole maalattu kokonaisuudessaan, vaan käyttäjä on maalannut alueen tekstikappaleen alusta aina "jatkuu"-sanan loppuun.

<p>
	<annotation aid="12">Teksti </annotation>
		<strong>
			<annotation-link aid="12">jatkuu</annotation-link> lihavoituna.
		</strong>
		<em>ja kursivoituna tänne asti.</em>
</p>

Jos ylitettäviä tagirajoja on useita, vastaavaa tapaa voidaan soveltaa seuraavasti:

<p>
	<annotation aid="12">Teksti </annotation>
		<strong>
			<annotation-link aid="12">jatkuu lihavoituna </annotation-link> 
		</strong>	
		<em><annotation-link aid="12"> ja kursivoituna</annotation-link> tänne asti.</em>
</p>

Sekä annotation-elementillä että annotation-link -elementillä tulee ollat täsmäävät aid-attribuutit.

Mikäli merkinnän tekeminen toteutetaan jatkokehityksessä myös kuville, tulee tietokantaan tehdä joitain muutoksia. Tällä hetkellä tietokanta tallentaa koordinaatteja edellä esitetyllä tavalla, eikä siten pystyisi tulkitsemaan kuvasta suoraan pisteen x- ja y-koordinaatteja.

Timber-projektissa suunniteltiin myös mahdollisuutta lisätä merkintään ikoni. Vaikka tietokanta tukee ikoneiden käyttöä, jätettiin tämä ominaisuus kuitenkin asiakassovelluksen osalta jatkokehitykseen.

5.2.2 Velppikokoelmien näkyvyys tarkastusalueessa

Velppivalikon Manage-välilehdellä olevat Show- ja Default-valintaruudut voivat tuntua käyttäjästä epäloogisilta. Jos Default-valintaruutu on valittu, myös vastaava Show-valintaruutu on aina valittuna kyseisessä kappaleessa tai koko dokumentissa, mikäli käyttäjä ei ole tätä valintaa muuttanut. Dokumentin oletuksena näkyy aluksi dokumentin oletusvelppikokoelma sekä käyttäjän henkilökohtainen velppikokoelma. Ominaisuus toimii siten, että jos Default-valintaruutua ei ole kappaleen kohdalla valittu, valinnat peritään koko dokumentin tasolta.

Nykyisessä toteutuksessa ongelma on se, ettei käyttäjä näe Show-valintaruutua eri tavalla sen mukaan, onko hän sitä aiemmin klikannut vai ei. Näin ollen valintaruudulla on todellisuudessa kolme eri tilaa: "Valittu", "Ei valittu" ja "Koskematon". Jos velppikokoelman kohdalla Default-valintaruutu on valittuna ja Show-valintaruutu on tilassa "Ei valittu", kyseistä velppikokoelmaa ei näytetä valitussa kohdassa. Jos taas Show-valintaruutu on tilassa "Koskematon", velppikokoelma näkyy kyseisessä kohdassa. Käyttäjää voi mahdollisesti hämätä se, että Default-valintaruutua klikkaamalla myös Show-valintaruutu tulee valituksi, kun Show-valintaruutu on tilassa "Koskematon". Tämä ongelma ratkeaisi esimerkiksi sillä, että valintaruutujen sijaan käytössä olisivat valintapainikkeet, jotka tukevat useampaa (ainakin kolmea) tilaa.

5.2.3 Velppikokoelmien hallinta

Tieto velppikokoelmista tallennetaan sovelluksessa sekä TIM-dokumentteihin että tietokantaan. Tästä johtuen joitain ongelmia voi ilmetä, mikäli velppikokoelmadokumentteja muokataan. Esimerkiksi jos dokumentin nimeä muutetaan, muutos ei vaikuta velppikokoelman nimeen, mutta kokoelman ja dokumentin välinen yhteys säilyy. Velppikokoelmadokumentin siirtäminen toiseen kansioon voi myös aiheuttaa ongelmia, sillä kytkös kokoelman ja dokumentin välillä säilyy käyttäjillä, joilla on joskus ollut mahdollisuus käyttää ko. kokoelmaa dokumentissa. Lisäksi velppikokoelman poistaminen ei poista kokoelmaa velppikokoelman tietokantatauluista, mikä aiheuttaa ongelmia kokoelmien käyttöoikeuksia tutkittaessa.

5.2.4 Versiointitietojen tallentaminen ja hyödyntäminen

Versiointitietoja sovelluksessa on toteutettu puutteellisesti, eikä käyttöliittymä tue mitään palvelinsovellukseen toteutettuja versiointiratkaisuja. Avainsanojen osalta sovellus ei tallenna mitään versiointitietoja, vaan kaikki muokkaustiedot tallennetaan vanhojen tietojen päälle. Palvelinsovellus tallentaa velpin versioon sen sisällön ja muokkausajan, mutta ei tietoa muokkaajasta, velpin pisteistä eikä ikonista. Ikoneita ei toteutettu käyttöliittymään lainkaan, mutta tietokanta tarjoaa valmiudet niiden käyttöön.

5.3 Sovelluksen jatkokehitysideat

Vaatimusmäärittelyssä [1] mainitut osiot Ilmoitukset, Vertaisarvionti ja Korostusten hallinta sovittiin tilaajan kanssa jatkokehitykseen. Lisäksi projektiorganisaation palavereissa sovittiin joitain toiminnallisuuksia jatkokehitykseen.

Palaverissa 9 kirjattiin seuraavat jatkokehitysideat:

• Käyttäjälle annetaan ilmoitus, jos merkinnän teko ei onnistu valittuun paikkaan.
• Merkintöjä voi tehdä tabletilla.
• Useamman merkinnän näkyvyyden voi vaihtaa kerralla Summary-välilehdellä.
• Teacher-näkymässä Summary-välilehdellä näytetään yksittäisen vastaajan merkinnät kaikkien sijaan.
• Summaryssä voidaan avata merkintöjä.
• Summaryssä merkinnät ryhmitellään velpeittäin.
• Merkinnän näkyvyyden valintaan lisätään selventävät tekstit.
• Merkintöjä tulee voida kirjata limittäin.

Palaverissa 10 kirjattiin seuraavat jatkokehitysideat:

• Timber-ryhmän tekemä ohjelmakoodi integroidaan TIMiin.
• Velpit järjestetään sen mukaan, kuinka monta kertaa kyseistä velppiä on tarkastusalueessa käytetty.
• Velppikokoelmia tulee voida liittää TIMin alueisiin.
• Velp menu -ikkunan välilehtiä tulee voida irrottaa välilehtien joukosta.
• Velppivalikon osia tulee voida raahata näkymässä.
• Tulee pohtia anonyymien käyttäjien oikeuksia merkintöjen suhteen.

Palaverissa 11 kirjattiin seuraava jatkokehitysidea:

• Käyttäjän tulee voida käyttää pelkkiä reunamerkintöjä.

Palaverissa 12 kirjattiin seuraavat jatkokehitysideat:

• Pistelaskulogiikka kehitetään tehtäväpluginkohtaisesti.
• Kehitetään tehtävien vastausten kuittaaminen ja siihen liittyvä pisteiden lasku.
• Kehitetään peruuttamattomien toimenpiteiden varmistaminen, kuten merkinnän poisto ja kommenttien poisto.
• Summary-välilehdelle kehitetään merkintöjen järjesteleminen sekä käyttöoikeuksien hallinta.
• Kehitetään velppikokoelmien poistaminen.
• Kehitetään kuvien, videoiden ja matemaattisten kaavojen velppaaminen.
• Suunnitellaan ja yksinkertaistetaan kommenttinäkymää.
• Kehitetään Velp menun välilehdet irrotettaviksi ikkunoiksi.
• Suunnitellaan tarkemmin ja toteutetaan velppikokoelmien luonnin yhteydessä oikeuksien automaattinen määrittäminen.

Palaverissa 13 kirjattiin seuraavat jatkokehitysideat:

• Jos käyttäjällä ei ole velppikokoelmaan manage-oikeutta, tulee velppilistauksessa poistaa velppikokoelman kohdalla linkki manage-sivulle.
• Sähköpostiosoite näytetään kommentissa.
• Toteutetaan uusi oikeusryhmä, joka rajoittaa oikeutta luoda pisteitä sisältäviä velppejä.
• Käyttäjän tulee voida pitää vain yhtä merkintää kerrallaan auki.
• Käyttäjän tulee voida valita värit omiin merkintöihin.
• Tulee pohtia sitä, kenellä on oikeus kirjata kommentteja merkintään.
• Käyttäjän tulee voida kirjoittaa TeXiä merkinnän kommentteihin ja otsikkoihin.
• Merkintäikkunaa tulee yksinkertaistaa.
• Toteutetaan autofokus merkintäikkunan kommenttikenttään.
• Merkintöjä tulee voida katsoa puhelimella.
• Kun kappaleen valinnan osoittaminen värin muuttumisella toimii oikein, kappaleen oikeaan reunaan ilmestyvä "V" voidaan jättää pois.
• Merkinnän tekstin taustavärin tulee muuttua vasta merkinnän tallennuksen yhteydessä.
• Varoitus merkinnän poistosta siirretään omaan metodiin pois alert-funktiosta.
• Pisteille määritetään järkevä arvo-alue.
• Tulee pohtia pitkien kommenttien esittämistä. Kommentin pituutta voidaan rajoittaa, tai se voidaan näyttää vierityspalkin tai "lue lisää..."-linkin kanssa.
• Käyttäjälle näytetään varoitus selaimen paluu- tai päivitys-painikkeita klikattaessa, mikäli käyttäjällä on tallentamatonta tietoa.
• Jotkut JavaScriptin scope-muuttujassa olevat arvot tallennetaan sessiomuuttujiksi tai localstorageen.

Lisäksi jatkokehitykseen sovittiin yksikkötestien pilkkominen pienempiin osiin. Lisää ideoita on kirjattu Timber-sovellusprojektin vaatimuksiin ja tehtäviin [8].

6. Yhteenveto

Timber-projekti kehitti kevään 2016 Sovellusprojekti-kurssilla Jyväskylän yliopiston tietotekniikan laitokselle uuden sovelluksen prototyypin TIM-järjestelmään. Projektissa lisättiin TIM-järjestelmään opettajille mahdollisuus tarkastaa TIM-ympäristössä tehtyjä tehtäviä ns. velppien ja vapaiden kommenttien avulla. Prototyyppi mahdollistaa opiskelijoiden vastausten nopeamman ja yhdenmukaisemman tarkastuksen.

Projektiryhmän kokemattomuudesta, vaatimusten muokkautumisesta ja rajallisesta ajasta johtuen jotkut toteutusratkaisut jäivät vaillinaisiksi. Nämä toteutusratkaisut liittyvät merkintöjen tekemiseen, velppikokoelmien näkyvyyteen tarkastusalueessa, velppikokoelmien hallintaan sekä versiointitietojen tallentamiseen ja hyödyntämiseen. Mahdollisessa jatkokehityksessä huomiota kannattaa kiinnittää myös siihen, että prototyypissä hyödynnetyt sovelluskehykset saattavat muuttua.

Monia alunperin suunniteltuja toiminnallisuuksia ei ehditty kehittää lainkaan. Prototyyppiin ei ehditty tehdä esim. opiskelijan käyttöliittymää, eikä prototyypistä ehditty tehdä toimivaa versiota tabletti-tietokoneelle. Myöskään testaamista ei ehditty suorittaa kovin kattavasti, joten mahdollisessa jatkokehityksessä prototyyppiä on myös testattava perusteellisemmin. Prototyyppi on kuitenkin pyritty toteuttamaan siten, että jatkokehitys olisi mahdollisimman vaivatonta.