Sivuston rakenne

Toimintaperiaate

Rakennetun ympäristön tietomallit on GitHub Pages-sivusto, jonka sivut generoidaan GitHub Flavored Markdown-formaatilla tuotetuista sisällöistä HTML-muotoon Jekyll-sivumoottorin ja sen tukemien Liquid-kielellä toteutettujen koodimakrojen avulla. Kuten muillakin GitHub Pages -sivustoilla, sivuston HTML-sivut on valmiiksi generoitu niiden julkaisuprosessin aikana, ja dynaamista sisältöä sivuilla tuotetaan lisäksi javascript-koodin avulla (mm. GitHub REST API:sta haettavat tiedostojen muutostiedot ja EA-raporttien sisäinen navigointi).

Sivuston lähdekoodi on GitHub-repossa ry-tietomallit, jossa on käytössä vain yksi kehityshaara (main). Lähdekoodiin tehtävät muutokset ry-tietomallit-repossa aiheuttavat automaattisesti sivuston päivittymisen https://tietomallit.ymparisto.fi -osoitteessa.

Pääosan sivuston sisällöstä muodostavat tietomallimodulit, joita ylläpidetään erillisissä Git-repoissaan, ja joiden halutut versiot on linkitetty sivuston sisältöhakemistoon. Sivustolla voidaan esittää kustakin tietomallista kaikkien sen haluttujen versioiden mukaiset kuvaukset, laatu- ja elinkaarisäännöt ja muut ohjeet. Toisaalta kutakin tietomallia voidaan kehittää erikseen omissa repoissaan ilman vaadittavia muutoksia ry-tietomallit-repon sisältöön.

Muutokset tietomallikohtaisissa repoissa eivät automaattisesti vaikuta Rakennetun ympäristön tietomallit -sivustolla esitettävään sisältöön, sillä tiedon päivitys vaatii aina tietomallimodulin linkin kiinnittämiseen uuteen muutosavaimeen (git-commit) tietomallin repossa. Nämä muutokset voi tehdä vain ry-tietomallit -repon hallinnoija.

Hakemistorakenne

Sivuston lähdekoodin hakemistorakenne on seuraava:

• README.md: ry-tietomallit -repon README-kehittäjäohje
• docs/: GitHub Pages -sisällön juuri
  • index.md: etusivun sisältö.
  • _data/: sivuston generoinnissa hyödynnettävä koneluettava, yaml-muotoinen data
    • modules/: tietomalli- ja kehitysprojektimodulien konfiguraatiot
    • topnavigation.yml: yläpalkissa esitettävä päätason navigaatiorakenne.
  • _includes/: sisältösivuilla hyödynnettävät HTML/Liquid-makrot
    • common/: erillisestä GitHub-reposta rytm-jekyll-includes linkitetyt Kaavamääräysoppaat-sivuston kanssa yhteiset HTML/Liquid-makrot.
  • _layouts/: HTML-sivupohjat
    • default.html: oletussivupohja
    • ea-frame.html: Entreprise Architect -sovelluksella generoitujen HTML-raporttien upottamiseen suunniteltu sivupohja.
    • redirect-to-module-default.html: ohjaa kävijän automaattisesti sivun osoitepolun mukaisen modulin oletusversion oletussivulle. Käytetään tyhjien välitason hakemistojen index.md-tiedostoissa.
    • redirect.html: yleinen uudelleenohjauspohja.
  • assets/
    • css/: sivuston tyylit, kielenä Sass.
    • fonts/: kirjasinlajit
    • img/: yleisesti käytettävät kuvatiedostot
  • kehitys/: kehitysprojektien modulit
  • ry-yhteiset/: Yhteiset komponentit -tietomoduli
  • kaavatiedot/: Kaavatietomallin tietomoduli
    • soveltamisprofiili/asemakaava/: Asemakaavan soveltamisprofiilin tietomoduli
    • soveltamisprofiili/yleiskaava/: Yleiskaavan soveltamisprofiilin tietomoduli
  • tonttijakosuunnitelma/: Tonttijakosuunnitelman tietomallin tietomoduli
  • rakennuskohteet/: Rakennuskohteiden ja huoneistojen tietomallin tietomoduli
  • rakentamisenluvat/: Rakentamiseen liittyvien lupapäätösten tietomallin tietomoduli

Uusille tietomoduleille lisätään omat hakemistonsa docs/-hakemiston alihakemistoiksi.

Sisällöt

Tietomallien modulit

Sivustolla on kullekin tietomallille ja kehitysprojektille omat tietomodulinsa. Kunkin tietomallimodulin hakemiston alla on oma alihakemistonsa kullekin ko. tietomallin julkaistulle versiolle, minkä lisäksi kunkin tietomallin seuraavan kehitysversion ehdotus voi olla julkaistu omana dev-versionaan. Kehitysprojektien osalta erillisiä versioita ei ole tarjolla, ja niiden tietosisältö voi olla joko suoraan osa ry-tietomallit-repon sisältöä tai linkitetty projektin omasta git-reposta.

Tietomodulien sisällön linkitys toisista git-repoista on toteutettu käyttäen git-submodule-toiminnallisuutta. Näin luodut tiedostot toimivat vastaavasti kuten hakemistot, mutta ovat todellisuudessa erityisisiä linkkejä toisen git-repon tiettyyn commit-ankkuriin. Niiden sisältö siis vastaa määrätyn muutoksen aikaista tilaa koko linkitetyn git-repon sisällöstä, ks. Kuva 1. Tekniset ohjeet tietomallimodulien linkityksen tekemiseen löytyvät erilliseltä wiki-sivulta Tietomallien kehittäminen ja ylläpito, kohdasta Tietomallimuutoksen hyväksyminen forkista päärepoon.

Kuva 1: Tietomallimodulien liittäminen git submodule -toiminnolla

GitHub Pages -julkaisumekanismi suorittaa automaattisesti modulilinkin sisältämän commit-tunnuksen mukaisten tietojen hakemisen viitatusta julkisesta git-reposta sivuston generoinnin yhteydessä, joten generoitu sivusto vastaa sisällöltään tilannetta, jossa submodule-linkit olisi korvattu kopioilla linkitetyn repon sisällöstä.

Ajantasainen lista linkitetyistä moduleista löytyy ry-tietomallit-repon etusivun kehittäjäohjeesta.

Kehitysprojektit ja ohjeet

Versioitujen tietomallimodulien lisäksi sivustolla julkaistaan tietomallien kehittämiseen liittyvien kehitysprojektien dokumentaatiota ja esimerkiksi mallien testaukseen ja tekniseen validointiin liittyvää materiaalia, sekä muuta tietomallien kehittämiseen ja hallintaan liittyvää ohjeistusta.

Kehitysprojektien materiaalien julkaisut tehdään ko. projektin omassa hakemistossa hakemiston kehitys alla. Nämä alihakemistot voidaan toteuttaa projektin tarpeista ja laajuudesta riippuen joko suoraan ry-tietomallit -repoon tai sitten git submodule-linkitettyinä erillisistä repoista. Kukin projektin kuvaukset ja tai muu ohjeisto lisätään omaan alihakemistoonsa.

Navigaatio

Sivuston navigaatiorakenne on kaksitasoinen: Päätason navigaatio yläpalkissa ja sen pudotusvalikoissa, ja kukin sisältömodulin sisäinen navigaatio vasemman reunan navigaatiopuuna. Molemmat navigaatiot tuotetaan automaattisesti sivuston kääntämisen yhteydessä Jekyll/Liquid -makroilla perustuen _data-kansion YAML-konfiguraatiotiedostoihin. Päätason navigaatiota ohjataan tiedostolla topnavigation.yml, jonka rakenne on seuraava:

- groupId: "yhteiset"
  title: "Yhteiset käsitteet ja komponentit"
  nav_items:
  - type: "module"
    moduleId: "ylaontologia"
  - type: "module"
    moduleId: "kasitemalli"
  - type: "module"
    moduleId: "yhteisetkomponentit"
- groupId: "alueidenkaytto"
  title: "Alueidenkäytön suunnittelu"
  nav_items:
  - type: "module"
    moduleId: "kaavatiedot"
    nav_items:
    - type: "module"
      moduleId: "sp-asemakaava"
    - type: "module"
      moduleId: "sp-yleiskaava"
    - type: "link"
      href: "https://sykefi.github.io/kaavamaaraysoppaat/"
      title: "Kaavamääräysoppaat"
...

Juuritason objektilistan perusteella luodaan yläpalkin navigaatiorakenne.

• groupId-kentällä annetaan kullekin pudotusvalikolle tunnus, jota käytetään mm. pudotusvalikon sisällön ja sen otsikon yhdistämiseen saavutettavuusmetatiedoissa (aria-labelledby-attribuutti).
• title-kentän arvo näytetään valikon otsikkona.
• nav_items-kentän arvolista kuvaa kunkin pudotusvalikon sisällön
  • objektit, joilla on kentän type arvona module tulkitaan sisältömoduleiksi, joide osalta tuotetaan ko. modulin konfiguraatiotiedoston perusteella linkin otsikko ja oletusversion ja -sivun mukainen linkki.
  • objektit, joilla on kentän type arvona linki tulkitaan sivuston ulkoisiksi linkeiksi, joiden sisältö kuvataan sen sisältämien title- ja href-kenttien avulla.

Päätason navigaation tyylityksessä on varauduttu 4-6 päätason pudotusvalikkoon, riippuen niiden otsikoiden pituudesta. Jos valikkoja on enemmän, ne eivät välttämättä mahdu kunnolla yläpalkkiin.

Kunkin modulin sisäisen navigaatiorakenteen konfigurointi ja sidonnaisuus modulin versiovalitsimeen on kuvattu Modulien konfigurointi-sivulla.