1. Dokumentin asetukset

Tässä dokumentissa kuvataan TIM-dokumentin asetuksia.

Dokumentin asetukset määrätään dokumentin alussa olevalla lohkolla, jossa on settings-attribuutti. Lohkoa pääsee muokkaamaan vasemman yläreunan rattaan kuvasta ja sitten Edit settings.

Kun ratasta painetaan ensimmäisen kerran, tulee seuraavanlainen pohja:

``` {settings=""}
example:
```

Tähän on tarkoitus lisätä erilaisia dokumentin asetuksia.

Asetusten muuttamisen jälkeen asetuslohko voisi näyttää vaikkapa seuraavalta:

``` {settings=""}
auto_number_headings: true
css: |!!
.huomautus {
  background-color: lightblue;
}
!!
```

# syntaksi

2. Asetusten syntaksi

Asetuksissa käytetty kieli on YAML. Asetusten arvoja sanotaan attribuuteiksi. Attribuutti voi olla yksittäinen arvo, taulukko tai sanasto (dictionary). Asetukset sinänsä ovat yksi sanasto. Taulukko voi taas sisältää arvoja, taulukkoja tai sanastoja. Samoin sanasto.

Lue myös YAML-kieli TIMissä.

2.1. avain, kaksoispiste ja arvo

Sanastossa on aina alussa avainarvo, kaksoispiste ja arvo.

Esimerkiksi:

auto_number_headings: true

Perus-YAML -kielessä on kaksoispisteen jälkeen oltava aina välilyönti. TIMin YAML-kieli sallii tähän poikkeuksen, missä puuttuva välilyönti lisätään tarvittaessa.

2.2. Lainausmerkit

Mikäli arvo sisältää kiellettyjä merkkejä, kuten kaksoispisteen, pitää arvo laittaa lainausmerkkeihin.

triesText: 'Yrityksiä jäljellä:'

Mikä jono sisältää lainausmerkkejä, voidaan käyttää kaksinkertaisia lainausmerkkejä. Muussa tapauksessa kaksinkertaisten lainausmerkkien käyttäminen ei useimmiten ole suositeltavaa, sillä silloin joudutaan enemmän "eskeippaamaan" merkkejä, erityisesti \-merkkiä. Toki joskus nimenomaan halutaan että \n tarkoittaa rivinvaihtoa eikä kahta kirjainta ja silloin arvo pitää laittaa kaksinkertaisiin lainausmerkkeihin.

2.3. Markdown attribuuteissa

Mikäli arvon sisältö on sellainen että se tulostuu dokumenttiin ja arvoon kirjoitettujen markdown merkintöjen halutaan vaikuttavan, pitää arvo aloittaa jonolla md:. Myös TeX-merkinnät lasketaan tässä tapauksessa markdown merkinnöiksi. Seuraavissa esimerkeissä näkee lainausmerkkien eron.

stem: 'md:$\int f(x)$'
stem: "md:$\\int f(x)$"
stem: 'md:Kissa **istuu** puussa'

Tämä on sen takia, että markdown muutos on aika kallis ja aina sitä ei edes haluta (vaan halutaan kirjoittaa esimerkiksi *-merkkejä). Lisäksi suurin osa attribuuteista ei tarvitse markdown-käsittelyä ja kuten todettua, se voisi monelle olla jopa haitaksi. Tämän takia TIMissä on jätetty käyttäjän päätettäväksi, milloin hän haluaa markdown-käsittelyn attribuutin arvolle.

2.4. Rivinvaihdot

Lainausmerkkeihin (kumpaan vaan) kirjoitettu jono voi katketa ja jatkua seuraavalla rivillä. Silloin rivinvaihto tulkitaan välilyönniksi. Jos riviin halutaan rivinvaihtoja, niin niitä voidaan tehdä \n merkinnällä. Tämä tosin vaikuttaa lähinnä tekstisyötteiden sisältöön:

byCode: "kissa\nistuu"

Edellä on nimenomaan käyettävä kaksinkertaisia lainausmerkkejä jotta \ tulkitaan prefix-merkiksi.

Usein monirivisyyttä tavoiteltaessa on parempi käyttää monirivisiä merkkijonoja.

2.5. Moniriviset merkkijonot

Monirivinen merkkijono on monirivisyydestään huolimatta vain yksi arvo. Alkuperäisessä YAML-kielessä monirivinen merkkijono voidaan kirjoittaa muodossa

byCode: |
 kissa
 istuu
 muussa

jossa | aloittaa jonon ja ensimmäinen rivi määrää vasemman marginaalin paikan. Jono loppuu kun on uusi attribuutti, jonka avain alkaa samalta tasolta kuin missä oli monirivisen aloittanut avain.

Koska tämä on usein hankalaa hahmottaa, on TIMIssä YAML-kieleen nähden lisäsys, jossa voidaan ilmoittaa monirivisen tekstin lopetusmerkki ja tällöin saadaan sisennykset säilymään

byCode: |!!
 kissa
 istuu
 puussa
!!

Eli | merkin jälkeen on annettu merkkiyhdistelmä (joka voi olla melkein mikä vaan, kunhan ei esiinny monirivisen tekstin osana) joka lopettaa monirivisen tekstin kirjoitettuna 1. sarakkeeseen.

Tässä on kuitenkin yksi ongelmatapaus:

byCode: |!!
 kissa
istuu
puussa
!!

Eli jos ensimmäinen merkkijono on muita sisempänä, tulee tästä syntaksivirhe. Useissa tapauksissa (erityisesti csPluginin) tätä voidaan kiertää niin, että lisätään ylimääräinen // jono jonka plugin tuhoaa käyttötilanteessa pois:

byCode: |!!
//
 kissa
istuu
puussa
!!

Mikäli moniriviseen merkkijonoon halutaan markdown käsittely, lisätään jono md: ensimmäisen rivin alkuun:

stem: |!!
md:
kissa
**istuu**
puussa
!!

tai

stem: |!!
md: kissa
**istuu**
puussa
!!

Tosin tässä esimerkissä monirivisyydestä ei juurikaan ole hyötyä, koska stem ladotaan yhdelle riville. Jos se halutaan oikeasti monelle riville, pitää esimerkin rivit päättää \ merkkiin:

stem: |!!
md:kissa\
**istuu**\
puussa
!!

jolloin esimerkistä saadaan tehtävän otsikkoteksti, joka on kolmella rivillä ja toinen sana on lihavoituna.

Usein lainausmerkki yms ongelmia voidaan välttää tekemällä monirivinen merkkijono.

2.6. Taulukkoarvot

Taulukkotyypiset arvot kirjoitetaan omille riveilleen miinusmerkillä (-) aloittaen:

  rows:
  - 'On'
  - Sopiva
  - Liian lämmin

Huomattakoon että tässä sana On on laitettu lainausmerkkeihin, koska muuten se voidaan tulkita joissakin tapauksisa totuusarvoksi true.

Taulukko voidaan kirjoittaa myös käyttäen taulukkomerkintää:

  rows: ['On', Sopiva, Liian lämmin]

Jos jonot sisältäisivät pilkkuja, pitäisi ne laittaa lainausmerkkehin.

Mikäli joku joista halutaan menevän markdown käsittelyn läpi, pitää sille erikseen sanoa se:

  rows:
  - 'On'
  - md:**Sopiva**
  - "Liian lämmin"

Sama taulukkomerkinnällä:

  rows: ['On', 'md:**Sopiva**', Liian lämmin]

Tyhjä taulukko on helpinta esittää taulukkomerkinnällä:

headers: []

2.7. Sanastot

Sanastossa kukin alkio aloitetaan sen avaimella. Esimerkki taulukollisesta sanastoja:

choices:
 - 
    correct: true
    text: Haukka
    reason: osaa lentää
 - 
    correct: false
    text: Koira
    reason: ei osaa lentää
 - 
    correct: false
    text: Kettu
    reason: ei osaa lentää

Yksittäinen sanastoarvo voidaan esittää myös käyttäen sulkumerkintää (JSON):

  - {correct: true, text: 'Haukka',  reason: 'osaa lentää'}

2.8. Esto selaimelle lähettämisestä

Esimerkiksi csPlugin välittää kaikki attribuutit oletuksena myös selaimelle. Joidenkin attribuuttien kohdalla tämä välitys kannattaa kieltää, erityisesti jos attributin arvona on jotakin, mitä esimerkiksi oppilaan ei kuuluisi nähdä. Tyypillinen tällainen attribuutti on pointsRule, joka voi sisältää tehtävän vastauksen. Attribuutin vieminen eteenpäin voidan kieltää laittamalla sen avainnimen eteen miinusmerkki -:

    -pointsRule:
       ...

Tämä ei toimi vielä aivan kaikilla attribuuteilla ja kaikkien eteenpäin vientiä ei edes saa kieltää, koska nimenomaan selain käsittelee attribuutin arvon.

# settings_list

3. Lista dokumentin asetuksista

access_denied_message

oletus: None
mikä teksti näytetään, jos dokumenttiin ei ole oikeutta
jos ei määritelty, näytetään TIMin geneerinen oletusvirheilmoitus

esimerkki:

access_denied_message: Sinulta puuttuu oikeudet tähän dokumenttiin.

add_par_button_text

oletus: 'Add paragraphs'
mikä teksti näytetään dokumentin lopussa olevassa lohkon lisäämispainikkeessa.
jos tekstiksi laitetaan tyhjä, ei painiketta tule

esimerkki:

  add_par_button_text: 'Lisää uusi lohko'

allow_self_confirm_from

oletus: None
mistä dokumentista sallitaan oikeuden omatoiminen vahvistaminen
katso lisätietoja ohjeesta ketjutus

esimerkki:

  allow_self_confirm_from: kurssit/tie/ohj1/2019s/tentti/osa1

anonymize_reviewers

oletus: None
millä käyttäjäoikeustasolla oleville dokumentista piilotetaan velppien antajien ja kommentoijien, sekä tehtävien pisteiden antajien nimet ja tunnisteet. Korkeampaa oikeustasoa omaavat näkevät nimet normaalisti
kaikki käyttäjät näkevät silti oman nimensä niissä velpeissä tai velppien kommenteissa, jotka ovat itse tehneet
esimerkki:
```
  anonymize_reviewers: view
```

answerBrowser

määrittää tehtävän vastausselaimeen liittyviä asetuksia
koostuu aliattribuuteista:
- pointsStep: tehtävään manuaalisesti annettavien pisteiden numerovälit
  - oletuksena ei mitään
- validOnlyText: Oletusteksti Show valid only -valinnan kohdalle
  - oletuksena Show valid only
- showValidOnly: Oletusasetus sille, näytetäänkö vain käyttäjän hyväksytyt (valid) vastaukset
  - oletuksena true
Samat asetukset voi antaa yksittäiseen tehtävään pluginin attribuuttina, jolloin asetus vaikuttaa yksittäiseen tehtävään

esimerkki: opettajat arvostelevat tehtävän asteikolla, 0.5, 1, 1.5...,
```
  answerBrowser:
   pointsStep: 0.5
```
esimerkki: tehtäville on annettu viimeinen vastausaika (deadline-attribuutti), ja vastaajille halutaan selventää hyväksyttyjen (valid) ja hylättyjen (invalid) vastausten eroa
```
  answerBrowser:
   validOnlyText: "Näytä vain ajoissa palautetut vastaukset"
   showValidOnly: false
```

answer_grace_period

oletus: 5
montako minuuttia sallitaan vastausten tallennus oikeuden päättymisen jälkeen
oikeuden päättymisen jälkeen yliajalla tallennetut vastaukset ovat invalid (siis eivät pistelaskuissa mukana)
esimerkki:
```
  answer_grace_period: 5
```

answer_submit_time_tolerance

oletus: 1000
montako millisekuntia sallitaan vastauksen tallennus oikeuden päättymisen jälkeen
toisin kuin answer_grace_period, tämän ajan sisällä vastaanotettu vastaus ei merkitä invalid, eli vastaus tulkitaan ajoissa lähetetyksi vastaukseksi
voidaan käyttää yhdessä answer_grace_period-asetuksen kanssa
- answer_submit_time_tolerance-asetuksen arvon tulee aina olla pienempi kuin answer_grace_period
asetuksen tarkoitus on ensisijaisesti "antaa anteeksi" mahdolliset viiveet verkkoliikenteessä
pienin sallittu arvo on 0, mutta käytännössä suositeltu minimi on 100 selainten ajastimien sisäänrakennetun epätarkkuuden takia
esimerkki:
```
  answer_submit_time_tolerance: 5000
```

anonymous_login

oletus: false
kirjataanko sisäänkirjautumaton käyttäjä sisään anonyymillä tunnuksella, kun hän saapuu dokumenttiin?
jos on true ja käyttäjä avaa dokumentin ilman sisäänkirjautumista, hänelle annetaan väliaikainen anonyymi käyttäjätunnus
- käyttäjä voi vastata kaikkiin tehtäviin istunnon aikana
- käyttäjän vastaukset tallentuvat anonyymille tunnukselle, ja kaikkien käyttäjien vastaukset voi tarkastella Teacher-välilehdessä
toistaiseksi käyttäjän anonyymi tunnus sulkeutuu automaattisesti, kun käyttäjä poistuu dokumentista
- käyttäjän anonyymi tunnus kuitenkin säilyy, jos hän avaa saman dokumentin useassa välilehdessä
esimerkki:
```
  anonymous_login: true
```

auto_confirm

oletus: None
mikä on se dokumentti, joka avautuu, kun nykyinen suljetaan
katso myös ketjutus

esimerkki:

  auto_confirm: kurssit/tie/ohj1/2019s/tentti/osa2

auto_number_headings

oletus: 0
minkä tason otsikot saavat ensimmäisen tason numeron. Jos esim 2, niin 1. tason otsikkoja ei numeroida. Pienessä dokumentissa 2 on hyvä, isoissa joissa monta 1. tason otsikkoa, 1
katso myös heading_format
esimerkki:
```
  auto_number_headings: 2
```

auto_number_start

oletus: 0 kaikilla otsikkotasoilla
käyttäytyminen riippuut arvosta:
- jos arvona on luku: mikä on ensimmäisen numeroidun pääotsikon numero+1. Eli oletuksella ensimmäinen pääotsikko saa numeron 1.
- jos arvona on taulu i: numero: i. otsikkotason numerointi alkaa luvusta numero+1
toistaiseksi ei voi sisältää md:-määrettä
esimerkki päätason numeroinnin aloittamiseksi nollasta:
```
  auto_number_start: -1
```
esimerkki 2. otsikkotason aloittamiseksi nollasta:
```
  auto_number_start:
    2: -1
```

cache

oletus: false
onko dokumentissa käytössä välimuistitus: dokumentti latautuu nopeammin kun käyttäjä avaa sen seuraavan kerran, jos muutoksia ei ole tapahtunut
ei oletuksena käytössä, koska välimuisti ei ihan kaikissa tilanteissa virkisty, vaikka pitäisi, mm.
- kun dokumentissa on viitelohkoja ja viitedokumentti muuttuu
- kun dokumentin preamble muuttuu

charmacros

oletus: None
"kirjainmakroja" jossa esitetyille jonoille tehdään tekstuaalinen korvaus

esimerkki:

charmacros:
  charmacros:
    £: "punta"
    USA$: "dollari"

valmiita char-makroja on automaattisen numeroinnin tilassa:

charmacros:
    '{§':  '%%"'             # nimetyn laskurin alku
    '\§}': '"|c_tag%%'       # nimetyn laskurin loppu kun tarvitaan tag
    '§}':  '"|c_%%'          # nimetyn laskurin loppu
    §a:    '%%0|c_%%'        # autom. nimetty laskuri + anchor
    §n:    '%%0|c_n%%'       # autom. nimetty laskuri ei anchor
    §\:    '%%0|c_tag%%'     # autom. nimetty tag-laskuri (LaTeX)

comments

oletus: None, eli voi tehdä kaikille näkyviä kommentteja
mille tasolle näkyviä kommentteja voi tehdä dokumenttiin. Kokeessa yleensä kannattaa estää julkiset kommentit
esimerkki:
```
comments: private
```

css

oletus: None
CSS-lisätyylit dokumentille

esimerkki:

  css: |!!
  .huomautus {
    background-color: lightblue;
  }
  ol {
    list-style-type: upper-alpha;
  }
  !!

disable_answer

oletus: None
kieltää dokumentin tehtäviin vastaamisen, jos käyttäjällä ei ole isompaa oikeutta kuin asetuksessa annettu
esimerkki:
```
disable_answer: view
```

editor_templates

oletus: None
editorin lisätoiminnot. Tällä voidaan lisätä editoriin uusia tabeja ja menukohtia. Kursori tulee lisäyksen jälkeen ⁞-merkin kohdalle, joka on paras kopioida tästä.

esimerkki:

  editor_templates:
    editor_tabs:
     - text: Uusi tab
       items:
        - text: Uusi menu
          items:
           - text: Uusi alamenu
             data: |!!
  Tästä tulee uutta⁞ tekstiä           
  !!

exam_mode

oletus: None
millä käyttäjäoikeustasolla oleville dokumentti näytetään tenttinäkymänä. Korkeampaa oikeustasoa omaavat näkevät dokumentin normaalisti
lue lisää käyttöohjeesta
esimerkki jossa vain view-tason omaaville näytetään dokumentti tenttinä:
```
  exam_mode: view
```

expire_next_doc_message

oletus: None
mikä viesti näytetään, kun käyttäjä sulkee dokumentin ja vahvistaa oikeuden seuraavaan dokumenttiin
ks. ketjutus

esimerkki:

  expire_next_doc_message: Voit siirtyä teoriaosioon alla olevasta painikkeesta.

extraPreambles

oletus: None
toimii vain preambleissa (ks. johdantodokumentit)
lista preambleista, jotka ladataan tätä asetusta käyttävän preamblen lisäksi
asetus tukee jinja2-makroja sekä filttereitä
polun on oltava absoluuttinen ilman verkkotunnusta. Esimerkiksi
```
kurssit/tie/ohj1/templates/preambles/preamble
```
huom: käyttäjällä on oltava view-oikeus extraPreambleen, jotta se latautuu
- tämä estää mielivaltaisten dokumenttien sisällön katsomista extraPreamble-asetuksella.
listan voi määrittää YAML-listana tai yksittäisenä merkkijonona
- jos käyttää merkkijonoa, jokainen alkio erotetaan rivinvaihdolla

esimerkki (YAML-lista):

extraPreambles:
  - "{% if ('kurssi1'|belongs) %}polku/kurssi1/preambleen{% endif %}"
  - "{% if ('kurssi2'|belongs) %}polku/kurssi2/preambleen{% endif %}"

esimerkki (merkkijono):

extraPreambles: |!!
    {% if ('kurssi1'|belongs) %}
      polku/kurssi1/preambleen
      polku/kurssi1/preambleen/toinen-preamble
    {% elif ('kurssi2'|belongs) %}
      polku/kurssi2/preambleen
    {% endif %}
!!

Tässä tapauksessa jos henkilö kuuluu kurssi1 -ryhmään, hänelle näytetään kaksi lisäpreamblea.

global_plugin_attrs

oletus: None
pluginien oletusattribuutit
attribuuttien arvo riippuu kustakin pluginista erikseen

esimerkki:

  global_plugin_attrs:
      csPlugin:
          stem: Kaikkien csPluginien yhteinen otsikko
          deadline: '2019-02-25 23:10:05'
      all:
          stem: Kaikkien pluginien yhteinen otsikko

globalmacros

oletus: None
globaalit makrot, jotka liitetään lohkoon ennen makrojen aukilaskentaa
tällä voidaan tehdä koko dokumentin kattavia Jinja2-funktioita
lue lisää satunnaistus-dokumentista

# docgroup

group

oletus: None
määrittelee opettajan sivulla mikä on käytettävä ryhmä, mikäli ei URL-parametrissa ole group-arvoa.
lue lisää ks. URL-group
esimerkki jossa ohjelmointi 1 syksy 2019 ryhmä:
```
  group: ohj1s19
```

heading_format

oletus: kaikki otsikkotasot numeroidaan
sanasto, jolla määritellään kunkin otsikkotason numeroinin näyttötapa
katso myös auto_number_headings
tarkemmat ohjeet katso käyttöohjeesta

esimerkki jossa ylintä tasoa ei numeroida näkyvästi:

  auto_number_headings: true
  heading_format:
    1: '{text}'
    2: '{h2}. {text}'
    3: '{h2}.{h3} {text}'
    4: '{h2}.{h3}.{h4} {text}'
    5: '{h2}.{h3}.{h4}.{h5} {text}'
    6: '{h2}.{h3}.{h4}.{h5}.{h6} {text}'

hideBrowser

oletus: false
piilottaa tehtäväplugineiden yläpuolella näkyvän vastausselaimen (answerBrowser)
vaikuttaa kaikkiin dokumentin vastattaviin tehtäviin
osan yksittäisten tehtävien vastausselaimista saa piiloon antamalla itse tehtävälle attribuutin hideBrowser: true, mutta joillekin tehtävätyypeille ainoa tapa piilottaa vastausselain on koko dokumentin kattava hideBrowser-asetus

hide_top_buttons

oletus: None
millä käyttäjäoikeustasolla olevilta piilotetaan dokumentissa oleva TIMin logot, hakupainike sekä näkymäpainikkeet.
lue lisää käyttöohjeesta
esimerkki jossa vain view-tason omaavilta piilotetaan logo ja hakupainike:
```
  hide_top_buttons: view
```

hide_readmarks

oletus: false
jos true, dokumentissa ei pidetä kirjaa lukumerkinnöistä eikä niitä näytetä
Huom: jos asetus on päällä, lukumerkintöjen seuranta ei toimi! Jos lukumerikintöjen seurantaa tarvitaan, exam_mode saattaa olla sopivampi asetus.
Asetuksen käyttäminen cache-asetuksen kanssa nopeuttaa dokumentin lataamista
esimerkki
```
  hide_readmarks: true
```

hide_sidemenu

oletus: None
millä käyttäjäoikeustasolla olevilta piilotetaan TIMin sivupalkki
lue lisää käyttöohjeesta
esimerkki jossa vain view-tason omaavilta piilotetaan sivupalkki:
```
  hide_sidemenu: view
```

hide_links

oletus: None
millä käyttäjäoikeustasolla olevilta piilotetaan dokumentissa olevat TIMin generoimat linkit. Dokumentin kirjoittajan lisäämät linkit toimivat
lue lisää käyttöohjeesta
esimerkki jossa vain view-tason omaavilta piilotetaan ylimääräiset linkit:
```
  hide_links: view
```

oletus: None
asetukset, jotka liittyvät sisäänkirjautumisdialogin toimintaan
tukee seuraavat asetukset ja niiden alioption:
- hide -- mahdollistaa dialogin toimintojen piilotuksen
  - hakaLogin (oletus: false) -- piilottaa Haka-tunnistautumisen
  - emailLogin (oletus: false) -- piilottaa tavallisen sähköpostikirjautumisen
  - signup (oletus: false) -- piilottaa rekisteröitymisen
  - passwordRecovery (oletus: false) -- piilottaa "unohdin salasanani"-toiminnon
esimerkki käytöstä (piilottaa kaikki toiminnot paitsi sähköpostikirjautumisen):
```
login:
  hide:
    hakaLogin: true
    signup: true
    passwordRecovery: true
```

loginMessage

oletus: None
sisäänkirjautumisohjeet, jotka näytetään yksinkertaisen loginin ollessa päällä
tällä hetkellä toimii vain, jos dokumenttiin on Anonymous -oikeus

lazy

oletus: riippuu dokumenin koosta, pienille false, pitkille true
tällä määritellään avataanko dokumentissa olevat tehtävä heti, vai vasta kun kun niiden päälle mennään. Pitkissä dokumenteissä false-arvo tekee dokumentin avaamisen hitaaksi erityisestyi hitailla laitteilla
esimerkki:
```
  lazy: true
```

live_updates

oletus: None
tällä voidaan tehdä dokumentista "reaaliajassa päivittyvä". Jos joku toinen muuttaa dokumentin sisältöä, tulee muutos automaattisesti tämän ajan kuluessa muidenkin käyttäjien dokumenttiin näkyville.
esimerkki viiden sekunnin välein päivittyvästä dokumentista:
```
  live_updates: 5
```

macros

oletus: None
sanasto Jinja2 makroista, joita käytetään korvaamaan tekstissä oleviä esiintymiä
lue lisää käyttöohjeesta kohdasta Makrot
esimerkki:
```
  macros:
   vuosi: '2017'
```
ja käyttötilanteessa silloin teksti %%vuosi%% korvaantuu jonolla 2017.

Korvattavia arvoja voi tehdä myös Jinja2-kielen muutujilla (joiksi oikeastaan macros arvot muutetaan). Tästä lisää dokumentissa Satunnaistus.

macro_delimiter

oletus: '%%'
vaihdetaan Jinja2 makrojen erotinjonoa
vaihtamista ei suositella erityisesti jos dokumentin haluaa tulostaa LaTeXin kautta.
katso lisää käyttöohjeesta
esimerkki:
```
  macro_delimiter: '%!'
```

math_type

oletus: mathjax
dokumentissa käytettävä matematiikan ladontatapa
katso lisää käyttöohjeesta
esimerkki:
```
  math_type: svg
```

max_points

oletus: None
dokumentista saatavien pisteiden maksimisumma. Ainakin pelillistämiskomponentti käyttää tätä laskemaan minkälainen osa linnasta pitää piirtää
katso lisää pelillistämiseohjeesta
esimerkki:
```
  max_points: 10
```

max_uncollapsed_toc_items

oletus: 40
sisällysluettelon automaattisen luhistamisen raja
jos sisällysluettelossa on enemmän otsikoita kuin tämän asetuksen mukainen luku, sisällysluettelo automaattisesti luhistetaan pienemmäksi
käyttäjän oma asetus voi ylikirjoittaa tämän arvon
esimerkki:
```
  max_uncollapsed_toc_items: 100
```

nomacros

oletus: false muille paitsi texplain true
estetäänkö makrojen suorittaminen

no_question_auto_numbering

oletus: false
numeroidaanko luentokysymykset automaattisesti

override_user_themes

oletus: false
Määrittää, korvataanko käyttäjän teema-asetukset dokumentin teema-asetuksilla.
Jos false, dokumentin teemat liitetään käyttäjän teemoihin dokumentin näyttämisen yhteydessä.
Jos true, käyttäjän teema-asetukset hylätään ja sen sijaan käytetään themes-asetuksessa määritellyt teemat.

parAuthorOnlyEdit

oletus: false
rajoitetaanko lohkojen muokkausta käyttäjälle, joka alun perin teki kyseisen lohkon
jos true ja show_authors-asetus on true, niin käyttäjä voi muokata vain ne dokumentin lohkot, joita hän teki alunperin
hyödyllinen esimerkiksi keskustelualueissa, jossa kaikilla käyttäjillä on edit-oikeus

esimerkki:

  parAuthorOnlyEdit: true
  show_authors: true

pars_only

oletus: None
millä käyttäjäoikeustasolla oleville näytetään vain dokumentin sisältöosa
lue lisää käyttöohjeesta
esimerkki jossa vain view-tason omaaville näytetään vain dokumentin teksti:
```
  pars_only: view
```

plugin_md

oletus: true
suoritetaanko dokumentissa pluginein markdown konversioita. Eli jos pluginin attribuutti alkaa md: suoritetaan attribuutille markdown konversio, eli tulkitaan tekstissä olevat muotoilukomennot. Mikäli dokumentissa ei ole kertaakaan käytetty markdown merkintää pluginien attribuuteissa, voi dokumentti lataantua hieman nopeammin jos tällä on arvo False. Myös LaTeX-merkinnät lasketaan markdown merkinnöiksi, eli jos niiden halutaan muuttuvan, ei tätä asetusta saa poistaa.
esimerkki:
```
  plugin_md: false
```

point_sum_rule

oletus: None
pistelaskun ryhmittely tehtäväkokonaisuuksiin
katso lisää käyttöohjeesta

esimerkki:

  point_sum_rule:
   groups:
    t1: t1.*
    t2: t2.*
    t3: t3.*
   count:
    best: 2

preamble

oletus: preamble
määrää, minkä nimistä johdantodokumenttia (preamble) tähän dokumenttiin käytetään (nimen viitattava preamblen lyhytnimeen)
voi antaa useita nimiä, esim. preamble,chat tai poistaa preamblen käytöstä jättämällä arvon tyhjäksi

esimerkki:

  preamble: /kurssit/tie/ohj1/macros/yleiset,preambe,chat

print_settings

oletus: None
ei käytössä vielä (texmacros korvaa tätä aika paljon)

read_expiry

oletus: hyvin suuri luku
määrää, kuinka monen minuutin kuluttua lukumerkinnät on_screen, hover_par ja click_par rekisteröidään uudelleen
esimerkki:
```
read_expiry: 10
```

saveTeacher

oletus: false
onko opettajanäkymässä "Save teacher's fix" -valintaruutu oletuksena päällä

scoreboard_docs

oletus: None
mitkä dokumentit otetaan mukaan sivupalkin pistetauluun
lista polkuja, jotka ovat suhteessa siihen kansioon, jossa nykyinen dokumentti sijaitsee
esimerkki:
```
scoreboard_docs:
 - d1
 - d2
 - d3
```

show_authors

oletus: false
näytetäänkö jokaisen lohkon yhteydessä sen alkuperäinen lisääjä
esimerkki:
```
  show_authors: true
```

show_scoreboard

oletus: false
näytetäänkö sivupalkissa pistetaulu, josta näkee määriteltyjen dokumenttien tehtävistä saadut pisteet
HUOM: tämä ei ota vielä täysin huomioon point_sum_rule-asetusta
esimerkki:
```
  show_scoreboard: true
```

show_task_summary

oletus: false
näytetäänkö dokumentissa tehtävien yhteispistemäärät
esimerkki:
```
  show_task_summary: true
```

slide_background_color

oletus: None (valkoinen)
määrää mitä väriä käytetään kalvojen taustana
lue lisää käyttöohjeesta
esimerkki:
```
  slide_background_color: "navy"
```

slide_background_url

oletus: None (jonka takia näyttää perus JYU-taustan)
määrää mitä kuvaa käytetään kalvojen taustana
lue lisää käyttöohjeesta

esimerkki:

  slide_background_url: "/images/118378/Aikajana.png"

slide_revealjs_options

oletus: None (Reveal.JS-kirjaston oletusasetukset)
määrää Reveal.JS-kirjaston kalvojen asetukset
lue lista kaikista asetuksista RevealJS-kirjaston käyttöohjeista

esimerkki:

  slide_revealjs_options:
    pdfSeparateFragments: false

slide_size

oletus: None (Reveal.JS-kirjaston kalvon oletuskoko)
määrää kalvon koon muodossa [leveys, korkeus]
lue lisää käyttöohjeesta
esimerkki:
```
  slide_size: [1280, 720]
```

smart_punct

oletus: false
määrää, korvataanko tiettyjä merkkejä niiden "kirjallisuusversioon"
jos true, dokumenteissa tehdään seuraavat korvaukset:
1. "teksti" -> “teksti”
2. 'teksti' -> ‘teksti’
3. -- -> –
4. --- -> —
5. ... -> …
6. Jotkut erikoissanat (esim. "Mr.") pidetään samalla rivillä kuin sitä seuraava sana
lue lisää käyttöohjeesta
esimerkki:
```
  smart_punct: true
```

source_document

oletus: None
määrää lainausten oletusdokumentin. Käytetään toistaiseksi vain sitaattikopioissa.

sync_answerbrowsers

oletus: false
jos päällä, vastaajan vaihto yhden tehtävän kohdalla vaihtaa saman vastaajan näkyviin kaikissa muissa tehtävissä

texmacros

oletus: None
sanasto LaTeX-tulostuksen makroista
lue lisää tulostusohjeesta

esimerkki:

  texmacros: 
    texfontsize: 14pt
    texautonumber: 1

texplain

oletus: false
onko dokumentti 'puhdas' LaTeX-dokumentti. Jos on, niin tällöin dokumentin koodilohkot kerätään tulostuksessa yhteen ja muodostetaan niistä yksi iso dokumentti, joka käsitellään TeX-kääntäjällä.
katso lisää tulostuksen käyttöohjeesta
esimerkki:
```
  texplain: true
```

themes

oletus: []
Tämä asetus on YAML-lista TIM-tyyleistä, joita dokumentin kohdalla tulee kytkeä päälle. Esimerkiksi:
```
themes:
  - hide_focus
  - Georgia_fontti
```
Kytkee dokumentille tyylit hide_focus ja Georgia_fontti.
Tyyli määritellään annetuista merkkijonoista seuraavasti:
- Jos merkkijono näyttää polulta (esim. sisältää merkin /), etsitään kyseisestä polusta oleva TIM-dokumentti
- Muussa tapauksessa etsitään samanniminen virallinen tyyli styles/official -kansiosta
- Jos teema halutaan rajoittaa vain tiettyyn näkymään (esim. vaim view-näkymä), laita teeman eteen view:, esim view:hide_focus
  - Vastaavasti esim. teacher, answer, yms

Esimerkiksi:

themes: 
  - /styles/user/chat

Katso myös override_user_themes
Katso myös dokumentti TIM ja tyylit

Miten dokumenttiin suhteellinen polku?

— 19 Jan 22

timeLeft

oletus:

sync_interval: 600
sync_interval_deviation: 0.2
low_time_threshold: 60
low_time_glow_period: 45
low_time_glow_duration: 15
low_time_sync_interval: 30
low_time_sync_deviation: 0.15

Tämä on kokoelma asetuksia, jolla voi muokata TIMin oikeassa ylälaidassa olevaa "Aikaa jäljellä" -ajastinta
Aliarvojen selitykset:
- sync_interval - Kuinka monen sekunnin välein ajastin synkronoidaan palvelimen kellon mukaan. Synkronointi korjaa mahdolliset selaimen toiminnasta johtuvia aikaeroja palvelimen kelloon.
- sync_interval_deviation - Hajontakerroin synkronointivälille. Jos määritelty, jokaisen ajan synkronoinnin jälkeen lasketaan uusi synkroinintiaka kaavalla (1 + random(-sync_interval_deviation, sync_interval_deviation)) * sync_interval
- low_time_threshold - Ajanhetki sekunteina, jona siirrytään matalan ajan tilaan. Tässä tilassa ajastimen väri muuttuu punaiseksi, sen koko kasvaa ja käyttäjälle näytetään varoitusteksti "The time is about to run out, remember to save your answers."
- low_time_glow_duration - Kuinka kauan kello "vilkkuu" matalan ajan tilassa
- low_time_glow_period - Kuinka kauan kello odottaa vilkkumatta matalan ajan tilassa
- low_time_sync_interval - Sama kuin sync_interval, mutta pätee vain matalan ajan tilassa
- low_time_sync_deviation - Sama kuin sync_interval_deviation, mutta pätee vain matalan ajan tilassa

Esimerkki:

timeLeft:
  low_time_threshold: 120 # Näytä varoitusteksti jo 2 minuutin kohdalla

urlmacros

oletus: tyhjä
kuten macros, mutta arvoja voi antaa myös URL-riviltä tyyliin
```
  ?group=ohj1?field=d1
```
tätä voi käyttä hyväkseen esim yhdessä fieldien ja saveButtonin kanssa tekemään sivuja, joissa toiminta vaihtuu sen mukaan mitä kenttiin kirjoitetaan. Ks esimerkki: Käytettävän kentän ottaminen lomakkeelta tai linkistä

esimerkki:

  Valitse demokerta: %% ('[{0}](/teacher/users/vesal/koe/lomakkeet/tablefromurl?group='+group+'&field=d{0}) ') | srange(1,13) %%

4. Lista automaattisesti määritellyistä makroista

Aina automaattisesti määriteltyjä makroja ovat seuraavat:

makro	esimerkki
`userid`	`0`
`username`	`Anonymous`
`realname`	`Anonymous user`
`useremail`	`None`
`userfolder`	`users/Anonymous`
`docid`	`63`
`docpath`	`tim/ohjeita/TIM-ohjeet`
`docdir`	`tim/ohjeita`
`doclang`
`docname`	`TIM-ohjeet`
`doctitle`	`TIM-ohjeet`
`loggedUsername`	`Anonymous`
`host`	`https://tim.jyu.fi`
`"" \| now`	`21.11`

Makro loggedUsername antaa aina selainta käyttävän henkilön tunnuksen. username antaa opettajan Teacher-näkymässä valitun opiskelijan tunnuksen. Tätä makroa on syytä käyttää niin, että lohko otsikossa on nocache=true tyyliin:

#- {nocache=true}

muuten arvoksi jää viimeisen muokkaajan tunnus.

Filtterin now käytöstä katso lisää satunnaistusdokumentista.

Samoin katso docid ja docpath filtterimuodosta lisää satunnaistusdokumentista.

Makro username korvataan käyttäjän tunnuksella ja realname käyttäjän koko nimellä.

Esimerkki: Tunnuksesi on %%username%% ja koko nimesi %%realname%%.

Esimerkki: Tunnuksesi on Anonymous ja koko nimesi Anonymous user.

Kyseisiä makroja EI voi korvata dokumentin asetuksissa omilla vakioarvoilla.

5. Lohkon attribuutit

Lohkon alkuun voi määrittää lohkolle omia koko lohkoa koskevia attribuutteja. Tavallisiin tekstilohkoihin pitää itse lisätä lohkomerkintä #- ja kirjoittaa attribuutin sen perään. Plugineissa, koodilohkoissa ja otsikoissa attribuutit voidaan lisätä lohkon ensimmäiselle riville.

Esimerkkejä:

otsikko:
```
  ## Kissat puussa {.nonumber}
```

koodilohko:

  ``` {.huomautus}
  kissa
  istuu puussa
  ```

plugin:

  ``` {#mmcq1 plugin="mmcq" rnd="s5"}
  ...
  ```

tavallinen kappale:
```
  #- {.huomautus}
  kissa istuu puussa
```

CSS-luokka

oletus: None
luetellaan CSS-tyylin luokkia välilyönnein eroteltuna. Huomattava että omien tyylien (ja suurimman osan TIM-tyylien myös) nimi pitää alkaa listassa pisteellä
esimerkki: lohko huomautuslaatikkon ja punaisella tekstillä:
```
  #- {.huomautus .red}
```

Hyppypaikat

oletus: lohkon id tai otsikon teksti muutettuna
nimi johonka voidaan hypätä toisaalta dokumentista tai toisesta dokumentista. Hyppypaikan nimi alkaa #-merkillä
esimerkki: halutaan lyhentää oletus joka olisi kissat_puussa
```
  ## Kissat puussa {#kissat}
```

nocache

oletus: None
tällä estetään makrojen laskenta (ja erityisesti %%username%% menetys) silloin kun dokumentin etukäteen laskettua versiota lasketaan. Tällöin lohkon makrot lasketaan vasta kun lohkoa näytetään tietylle käyttäjälle. Tätä tarvitsee käyttää silloin, kun tehdään ehdollisia mm- username:sta riippuvia lohkoja. Samalla myös dokumentin laskeminen hidastuu kun tällä määritellyt lohkot lasketaan aina uudelleen, eli tätä ei kannata käyttää liikaa.

esimerkki:

  #- {nocache=true}
  {% if username in group1 %}
  Tekstiä ryhmälle 1
  {% endif %}

nomacros

oletus: None
tällä voidaan estää se, että lohkossa suoritetaan Jinja-makroja. Tarpeen erityisesti, jos ollaan esittelemässä ko. makrojen käyttöä, koska silloin tulisi ristiriita siitä, että sisältö ei saada sellaisenaan näkyviin, vaan makrot suoritetaan. Samoin tarpeellinen esimerkiksi satunnaistuksen kanssa jotta varmasti eri käyttäjille lasketaan lohkon sisältö uudelleen.

esimerkki:

  #- {nomacros=true}
  Korvataan `%%` -väliin kirjoitetut symbolit

plugin

oletus: None
määritelee että lohko on jokin plugin. Tämä toimii vain ```-alkavilla lohkoilla.
pluginien tapauksessa plugineille pitää antaa myös yksikäsitteinen nimi risuaitamerkin # perään. Nimen perusteella tallennetaan vastaukset tietokantaan. Poikkeuksen tekevät pluginit, joiden tuloksia ei tallenneta, esimerkiki video-plugin. Silloin nimeä ei tarvita ja voi olla helpompikin olla käyttämättä, niin ei tarvitse keksiä jokaiselle erilaista nimeä.
esimerkki:
```
  ``` {#kysymys1 plugin="mmcq"}
```

rd

oletus: None
referenced document: dokumentin ID, johon viitataan
lue lisää dokumentin mallista
esimerkki:
```
  #- {rd="3" rp="744gh474t5t5"}
```

ra

oletus: None
referenced area: alueen nimi, johon viitataan
lue lisää dokumentin mallista
esimerkki:
```
  #- {rd=1 ra=alkuosaamnen}
```

rl

oletus: None
referenced link: näytetäänkö linkki alkuperäisen dokumentin lohkoon, johon ollaan viitattu. Arvo voi olla no.
lue lisää dokumentin mallista

rp

oletus: None
referenced paragraph: lohkon id, johon viitataan
lue lisää dokumentin mallista
esimerkki:
```
  #- {rd="3" rp="744gh474t5t5"}
```

r

oletus: c
viittauksen tyyppi, voi olla c (copy) tai tr (translation)
lue lisää dokumentin mallista

rt

oletus: None
viitatun lohkon tiiviste (ei mielekästä kirjoittaa käsin)
lue lisää dokumentin mallista

rnd

oletus: None
arvotaan satunnaisia lukuja
lue lisää dokumentista Satunnaistus

esimerkki:

  ``` {#kysymys1 plugin="mmcq" rnd="s5"}

settings

oletus: None
määritellään että lohko on asetuslohko. Näitä saa toistaiseksi olla vain yksi ja sen pitää olla dokumentin alussa
lue lisää tämän dokumentin alusta

visible

oletus: True
valitaan, näytetäänkö lohko tai alue
osittain tätä voi käyttää kommentointiin, mutta vielä hyödyllisempi tämä voi olla, jos Jinja2-makrojen avulla toteutetaan ehdollista dokumentin näyttämistä. Lue tästä lisää erillisestä ohjeesta.

esimerkki:

  ## Tämä otsikko laitettiin kommentiksi {visible=false} 
  ...
  ``` {#r1tehtava1 plugin="csPlugin" visible="%%username in group1%%"}
  type: py
  byCode: print("Tämä koodi näkyy vain ryhmälle 1")
  ```

# plugingen

6. Lista pluginien yleistä asetuksista

Seuraavassa on lista kaikille plugineille yhteisistä asetuksista. Yksittäisille plugineille on vielä omia asetuksiaan:

csPlugin - cs (computer science) plugin, ohjelmat, visualisaatiot yms
qst - uudet kysymystyypit
mcq - vanhemmat kysymystyypit (mcq, mmcq)
Imagex - kuvaraahauskomponentti
svn ja video - tiedostojen haku, upotus ja videot (ei vielä dokumenttia)

Tässä listassa esiteltävät attribuutit kirjoitetaan asetusten päätasolle.

accessDuration

oletus: None => vastaajan ei tarvitse aktivoida tehtävää erikseen
kuinka monta sekuntia tehtävän tekemiseen on aikaa tehtävän aktivoimisen jälkeen
tällöin tehtävän sijalla näkyy painike, jonka avulla vastaaja saa tehtävän näkyviin ja aikalaskuri käynnistyy.
opettajat näkevät tehtävän aina, eikä asetuksella ole vaikutusta heidän näkymäänsä
katso myös accessEndText, joka määrittää mitä tapahtuu kun vastaajan aika loppuu
esimerkki, jossa vastajalla on tehtävän avaamisen jälkeen minuutti vastausaikaa:
```
  accessDuration: 60
```

accessEndText

oletus: None => aikalaskurilla rajoitettu tehtävä jää näkyviin vastausajan jälkeenkin
käytetään yhdessä accessDuration-asetuksen kanssa
määrittää mitä ehtävälle tapahtuu aikalaskurin loputtua
tehtävissä, joissa on accessEndText-asetus, aikalaskurin loputtua tehtävä katoaa ja näytetään asetuksena annettu teksti
jos asetusta ei anneta, tehtävä jää näkyviin
esimerkki, jossa tehtävän vastausajan loputtua käyttäjälle näytetään teksti "Vastausaikasi loppui."
```
  accessEndText: 'Vastausaikasi loppui.'
```

answerBrowser

määrittää tehtävän vastausselaimeen liittyviä asetuksia
koostuu aliattribuuteista:
- pointsStep: tehtävään manuaalisesti annettavien pisteiden numerovälit
  - oletuksena ei mitään
- validOnlyText: Oletusteksti Show valid only -valinnan kohdalle
  - oletuksena Show valid only
- showValidOnly: Oletusasetus sille, näytetäänkö vain käyttäjän hyväksytyt (valid) vastaukset
  - oletuksena true
Samat asetukset voi antaa dokumenttiasetuksena, jolloin ne vaikuttavat dokumentin kaikkiin tehtäviin

esimerkki: opettajat arvostelevat tehtävän asteikolla, 0.5, 1, 1.5...,
```
  answerBrowser:
   pointsStep: 0.5
```
esimerkki: tehtäville on annettu viimeinen vastausaika (deadline-attribuutti), ja vastaajille halutaan selventää hyväksyttyjen (valid) ja hylättyjen (invalid) vastausten eroa
```
  answerBrowser:
   validOnlyText: "Näytä vain ajoissa palautetut vastaukset"
   showValidOnly: false
```

answerLimit

oletus: 1 mcq, mmcq, muilla None => ääretön
montako kertaa käyttäjä saa yrittää vastaamista
lue lisää käyttöohjeesta
esimerkki 5 yrityskertaa:
```
  answerLimit: 5
```

deadline

oletus: None
milloin tehtävään on vastattava viimeistään
kirjoitettava UTC-muodossa, mutta näkyy tehtävään vastaajalle omalla aikavyöhykkeellä
lue lisää käyttöohjeesta
esimerkki:
```
  deadline: '2016-08-25 23:10:05'
```

maxPoints

oletus:
teksti joka tulee käyttäjän pistemäärän viereen. Huom, tämä on vain informatiivista tekstiä, eikä vaikuta mihinkään muualle.

esimerkki:

  maxPoints: 5p kun kaikki kohdat oikein

tällöin tulostuisi käyttäjälle esim:
```
  3.2/5p kun kaikki kohdat oikein
```

modelAnswer

Huom, nämä attribuutit ovat vielä kehityksessä ja saattavat muuttua.

oletus: None
määrittää tehtävään mallivastauksen, sekä säännöt mallivastauksen katsomiselle ja sen seurauksille
koostuu aliattribuuteista:
- answer: Teksti joka näytetään mallivastauksena. Tukee markdown-muotoilua. Mikäli ei annettu, mallivastauslinkkejä ei näytetä ollenkaan.
- count: Vastausyritysten vähimmäismäärä ennen kuin vastauksen voi avata. Oletuksena 1.
- disabled: Estää mallivastauksen avaamisen. Voidaan käyttää esimerkiksi piilottamaan mallivastaukset kurssin jälkeen. Ei koske niitä, joilla on dokumenttiin opettajaoikeus.
- endDate: Aikaleima, jonka jälkeen mallisvastausta ei voi enää avata. Oletuksena ei mitään. Ei koske niitä, joilla on dokumenttiin opettajaoikeus.
- groups: Ryhmät, joihin kuuluvat henkilöt voivat avata mallivastauksen. Oletuksena tyhjä, jolloin ryhmärajoitusta ei ole. Erikoismerkillä '*' voidaan antaa oikeus niille, jotka ovat vastanneet tehtävään vähintään kerran. Ryhmäajoitukset eivät koske niitä, joilla on dokumenttiin opettajaoikeus.
- hidePoints: Jos true, vastauksista saadut pisteet ovat piilossa kunnes mallivastaus avataan. Vaatii toimiakseen että mallivastauksen lukitus on käytössä (katso kohta lock). Oletuksena false. Ei koske niitä, joilla on dokumenttiin opettajaoikeus.
- hideText: Teksti, jota painamalla auki oleva mallivastaus suljetaan.
- linkText: Teksti jota painamalla mallivastaus aukeaa
- linkTextBeforeCount: Teksti, joka näytetään jos mallivastauslinkin tilalla jos linkki on piilossa linkTextCount-attribuutin vuoksi. Oletuksena ei mitään.
- linkTextCount: Vastausyritysten vähimmäismäärä ennen kuin mallivastauslinkki tulee näkyviin. Oletuksena 0.
- lock: Jos true, tehtävä lukitaan mallivastauksen avaamisen jälkeen, ja seuraavat vastaukset merkitään epävalideiksi. Oletuksena true. Lukitus ei koske niitä joilla on dokumenttiin opettajaoikeus.
- lockedAnswerMessage: Virheviesti, joka annetaan vastattaessa mallivastauksen kautta lukittuun tehtävään.
- lockConfirmation: Varmistusdialogi, jolla kysytään halutaanko tehtävä lukita ja näyttää mallivastaus.
- lockedLinkText: Teksti, jota painamalla jo aiemmin lukitun tehtävän mallivastaus aukeaa. Korvaa linkText-attribuutin tekstin tehtävän lukittumisen jälkeen.
- minPoints: Pistemäärä, joka tehtävästä pitää saada ennen kuin mallivastauksen voi avata. Oletuksena ei mitään. Ei koske niitä, joilla on dokumenttiin opettajaoikeus.
- revealDate: Aika, jolloin mallivastauslinkki tulee näkyviin ja mallivastauksen voi aikaisintaan avata. Annettava UTC-muodossa. Oletuksena ei mitään. Ei koske niitä, joilla on dokumenttiin opettajaoikeus.
Jokainen aliattribuutti on valinnainen.
Linkkitekstit ja mallivastaukset avautuvat aina niille, joilla on dokumenttiin opettajaoikeus. Jos haluat kokeilla mallivastauksen rajoituksia, pudota oikeutesi view-oikeuteen
Katso myös previousTask-attribuutti, jolla tehtävien aukeamista voi ketjuttaa mallivastausten avulla

esimerkkejä:
- Tilanne, jossa käyttäjän pitää yrittää vastata tehtävään vähintään kaksi kertaa, ennen kuin mallivastauksen voi avata. Lisäksi mallivastausta ei voida katsoa ennen 1. syyskuuta 2022 kello 16:00 (aika on annettu UTC-muodossa). Mallivastauksen katsomisen jälkeen seuraavat vastaukset merkitään epävalideiksi:
```
modelAnswer:
 answer: "Kissa **istuu** puussa"
 linkText: Näytä viikkotehtävän mallivastaus
 hideText: Piilota malliratkaisu
 count: 2
 lock: true
 lockConfirmation: Lukitse tehtävä ja näytä mallivastaus?
 revealDate: '2022-09-01 13:00:00'
```
- Tilanne, jossa mallivastauksen katsomisen jälkeen tehtävään voi edelleen vastata normaalisti, mutta vastaajan täytyy yrittää ainakin kerran ennen kuin mallivastauslinkki tulee näkyviin:
```
modelAnswer:
 answer: "Kissa **istuu** puussa"
 linkText: Näytä luentoesimerkin ratkaisu
 linkTextCount: 1
 lock: false
```

pointsRule

oletus: None
säännöt, jolla tehtävästä saa pisteitä
tämä kannattaa yleensä aloittaa - -merkillä jotta tietoa ei turhaan viedä selaimeen asti
lue lisää käyttöohjeesta
numerosyötön arvioinnista myös käyttöohjeessa
esimerkki jossa vastauksesta Kissa saa yhden pisteen:
```
  -pointsRule: 
      expectCodePlain: "Kissa"
```

pointsText

oletus: 'Points:'
teksti joka näytetään pisteiden kohdalla
esimerkki:
```
  pointsText: 'Pisteet:'
```

previousTask

oletus: None
ketjuttaa tehtäviä niin, että tehtävään ei voi vastata ennen kuin edeltävään tehtävään riippuvat ehdot täyttyvät.
koostuu aliattribuuteista
- taskid: edellisen tehtävän tunniste. Pakollinen tieto.
- requireLock: jos true, tehtävään ei voi vastata ennen kuin edellinen tehtävä on lukittu. Toistaiseksi lukitus katsotaan modelAnswer-attribuutin antamasta lukituksesta.
- count: kuinka monta kertaa edelliseen tehtävään pitää vastata ennen kuin tehtävä aukeaa. Oletuksena 0, suosituksena esim 1.
- hide: jos true, tehtävä näytetään piilotettuna mikäli edellistä tehtävää ei ole lukittu ja requireLock tai count on käytössä.
  - Huomaa, että piilottaminen ei toistaiseksi ole "vahva" piilotus, joten tätä ominaisuutta ei ole suositeltavaa käyttää vielä kokeissa tai vastaavissa arviointitilanteissa
- hideText: teksti, joka näytetään piilotetun tehtävän kohdalla
- unlockText: teksti, joka näytetään piilotetun tehtävän avauspainikkeen kohdalla
- unlockError: virheviesti, joka annetaan mikäli piilotettua tehtävää yritetään avata vaikka edellisen tehtävän lukitusehdot eivät täyty
Vain taskid on pakollinen aliattribuutti, mutta toistaiseksi toiminnallisuus vaatii requireLock tai count-attribuuttien käyttöä
Alueita on mahdollistaa piilottaa ja näyttää aiemmasta riippuvien tehtävien kanssa antamalla alueelle attribuutti hide-with="tunniste", missä tunniste on edellisestä tehtävästä riippuvan tehtävän tunniste.

esimerkkejä:

Tehtävä demo_t1 pitää ensin lukita katsomalla sen mallivastaus

previousTask:
    taskid: demo_t1
    requireLock: true            
    hideText: Sinun täytyy ensin lukita ensimmäinen tehtävällä katsomalla sen mallivastaus ennen tämän tehtävän aukeamista
    unlockText: Avaa tehtävä 2
    unlockError: Tehtävää ei voitu avata. Painoithan ensimmäisestä tehtävästä kohtaa Näytä mallivastaus?

Tehtävään question1 täytyy ensin vastata ainakin kerran

previousTask:
    taskid: question1                                                 
    count: 1                                                          
    hide: true                                                        
    hideText: You need to answer question 1 before opening this task  
    unlockText: Show question 2                                       
    unlockError: You haven't answered question 1 yet!

spellcheck

oletus: None => selaimen oletus
saako selain tarkistaa tehtävän tekstikenttien kieliopin ja näyttää korjausehdotuksia
toistaiseksi toteutettu vain csPlugin-tehtävissä
esimerkki:
```
  spellcheck: false
```

starttime

oletus: None => alkuaika on rajaamaton
milloin tehtävään voi alkaa vastaamaan
lue lisää käyttöohjeesta
esimerkki:
```
  starttime: '2016-08-25 23:00:05'
```

triesText

oletus: 'Tries left:'
mikä teksti näytetään yrityskertojen kohdalla. Jos tyhjä, ei näytetä yrityskertoja
esimerkki:
```
  triesText: 'Yrityksiä jäljellä'
```

userMin

oletus:

userMax

oletus:

# url

7. Dokumentin URL-parametrit

Tässä luvussa kuvataan dokumentin URL-parametreja. Useimmille näistä ei ole vielä käyttöliittymää, vaan ne joudutaan kirjoittamaan käsin osoiteriville ? perään. Jos useita parametreja tarvitaan, erotellaan ne toisistaan &-merkillä

7.1. Dokumenttiin vaikuttavat parametrit

b

oletus: ei mtäään
aloittaa (begin) dokumentin näyttämisen lohkosto nro b

esimerkki:

https://tim.jyu.fi/teacher/kurssit/tie/ohj2/2019k/demot/DemoC2?b=23&e=24

check_username

oletus: null
jos on määritelty ja force_create=true, dokumentin luojan käyttäjätunnus on oltava sama kuin tässä asetuksessa
- dokumentin polulla ei ole merkitystä, koska se saatetaan normalisoida (esim. aalto.fi:testi normalisoituu polussa muotoon aaltofitesti)
jos linkkiä klikanneen käyttäjätunnus ei täsmää, tulee virheilmoitus: "This document is reserved for another user. Create a document for your username."
huom: tämä on vain kevyt rajoite, joka on tarkoitettu klikattavia linkkejä varten

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/uusi-dokumentti?force_create=true&check_username=Anonymous

create_public

oletus: false
jos dokumentti luodaan automaattisesti (katso force_create), tehdäänkö dokumentista heti julkinen

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/uusi-dokumentti?force_create=true&create_public=true

e

oletus: ei mtäään
lopettaa (end) dokumentin näyttämisen lohkokoon e-1

esimerkki:

https://tim.jyu.fi/teacher/kurssit/tie/ohj2/2019k/demot/DemoC2?b=23&e=24

force_create

oletus: riippuu templates-kansion sisällöstä
- true, jos kansiossa on force-niminen pohjadokumentti
- false muissa tapauksissa
luodaanko dokumentti automaattisesti, jos sitä ei ole olemassa
käyttää dokumentin pohjana template-parametrin arvon, jos se on määritelty

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/uusi-dokumentti?force_create=true&template=omapohja

hide_names

oletus: ei mitään
muuutetaan vastaajien nimet tuntemattomiksi. Asetus pysyy voimassa samalla koneella (local storage) kunnes sitä seuraavan kerran muutetaan

esimerkki:

  https://tim.jyu.fi/teacher/kurssit/tie/ohj2/2018k/demot/Demo1?hide_names=true

# urlgroup

group

oletus: ei mitään
rajoitetaan opettajan näkymään vain tiettyyn ryhmään kuuluvien vastaukset
voittaa mahdollisen dokumentin group-asetuksen.

esimerkki:

  https://tim.jyu.fi/teacher/kurssit/tie/ohj2/2018k/demot/Demo1?group=ohj2

voi antaa useita ryhmiä pilkulle erotettuina, esim:

  https://tim.jyu.fi/teacher/kurssit/tie/ohj2/2018k/demot/Demo1?group=ohj2eka,ohj2toka

noanswer

oletus: False
estetään vanhojen vastausten näyttäminen tehtävissä. Hyödyllinen esimerkiksi opettajalla jos on kokeillut vastaamista ja luennolla ei halua vastausten näkyvän opiskelijoille

esimerkki:

  https://tim.jyu.fi/view/tim/ohjeita/dokumentin-asetukset?noanswers=true

nocache

oletus: False
estetään dokumentin muistissa olevan version käyttäminen. Virkistää myös esilasketutut LaTeX SVG-kaavat (joka voi viedä paljon aikaa).

esimerkki:

  https://tim.jyu.fi/view/tim/ohjeita/dokumentin-asetukset?nocache=true

pars_only

oletus: False
dokumentista näytetään vain sen "sisältöosa"

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/dokumentin-asetukset?pars_only=true

run_jsrunners

oletus: tyhjä
ajaa määritellyt JSRunner-funktiot sivun avauksen yhteydessä
JSRunner-funktioiden nimet voi erottaa pilkulla

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/dokumentti?run_jsrunners=test1,test2

ajaa dokumentissa olevat JSRunnerit test1 sekä test2

# showAdmin

showAdmin

Toimii vain ylläpitäjille
oletus: false
Jos true, näyttää ylläpidolle tarkoitettuja laajennettuja toimintoja (esim. vastausten poisto)
Esimerkki:
```
https://tim.jyu.fi/?showAdmin=true
```

# themes-url

themes

oletus: null
pilkulla erotetut teemat, jotka otetaan käyttöön väliaikaisesti
teemojen nimet tulee antaa samassa muodossa kuin themes-asetus

Esimerkki:

https://tim.jyu.fi/?themes=Georgia_fontti,/styles/user/vihrea

title

oletus: null
jos asetettu ja dokumenttia ei ole olemassa, dokumentin nimeksi tulee tämän parametrin arvo
jos ei annettu, dokumentin otsikoksi tulee sama kuin dokumentin lyhytnimi

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/uusi-dokumentti?title=Hieno+dokumentti

template

oletus: force
mitä dokumenttipohjaa käytetään dokumentin luomisessa (jos dokumentti ei ole olemassa)
arvona on pohjan nimi, pohjan pitää toistaiseksi sijaita templates-kansiossa

esimerkki:

https://tim.jyu.fi/view/tim/ohjeita/uusi-dokumentti?template=ohjepohja

7.2. Järjestelmään vaikuttavat parametrit

7.3. URLin kautta annettavat komennot

https://tim.jyu.fi/cs/refresh   - tyhjentää esiladatun tiedostojen cache-muistin
                                  pitää käyttää jos muuttaa tiedostoja joita
                                  csPlugineissa haetaan
https://tim.jyu.fi/svn/refresh  - tyhjentää esiladatun tiedostojen cache-muistin
                                  pitää käyttää jos muuttaa tiedostoja joita
                                  svn-plugineissa haetaan