Skip to content

Sisältömakrot

Jump to bottom
Ilkka Rinne edited this page Jan 31, 2022 · 2 revisions

Yleistä

Jekyll-sivustojen tuottamisessa voidaan HTML-kieleisen koodin lisäksi käyttää Liquid-kieltä generoimaan sivujen rakennetta ja sisältöä. Tällä sivulla kuvataan ne Liquid-kieliset makrot, jotka ovat käytössä Rakennetun ympäristön tietomallit-sivustolla. Makrolla tarkoitetaan tässä yleiskäyttöistä koodinpätkää, joka tuottaa tietyn (syötettä laajemman) tulostuksen annetulla syötteellä. Jekyll-sivustoilla makrot sijaitsevat docs/_includes-hakemistossa ja sen alihakemistoissa.

Yhteiset makrot (rytm-jekyll-includes)

Kaavamääräysoppaat-sivoston kanssa yhteisiä HTML/Liquid-makroja ylläpidetään GitHub-repossa sykefi/rytm-jekyll-includes, josta ne on linkitetty molempien sivustojen docs/_includes/common-alihakemistoiksi. Näin samaa koodia ei tarvitse kopioidaa molempien sivustojen alle, ja yhteinen koodi pysyy synkassa. (Makrojen lisäksi sivustoilla on myös yhteisiä sivupohjia ja tyylitiedostoja, mutta näille ei ole ainakaan toistaiseksi monimutkaisuuden välttämiseksi tehty omia GitHub-repoja. Samaan repoon niitä ei submodule-linkityksellä saa, sillä linkkinä toimiva hakemisto sisältää aina koko linkitettävän repon sen juuresta alkaen.)

Alla yhteiset makrot on jaettu lukuihin niiden käyttötarkoituksen mukaan.

Sisällön muotoilumakrot

Sisällömuotoilumakroja on tarkoitus käyttää Markdown-kielisten sivujen tekstisisällön kirjoittamisen helpottamiseen. Sisältömakroa kutsumalla voidaan tuottaa tiettyyn kohtaan helposti monimutkainen HTML-kielinen sisältö.

Seuraavassa yksikertaisessa esimerkissä tuotetaan huomauskappale tekstin sekaan:

Sisältö:

{% include common/note.html content="Rakennetun ympäristön tietomallit -sivusto on vielä keskeneräinen, ensimmäinen versio valmistuu vuoden 2021 loppuun mennessä." %}

Kutsuttava makro note.html:

<div markdown="span" class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i>&nbsp;{{include.content}}</div>

Sivugeneroinnin aikana ajettaessa makron include-kutsun sisältö korvautuu seuraavalla HTML-fragmentilla:

<div markdown="span" class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i>&nbsp;Rakennetun ympäristön tietomallit -sivusto on vielä keskeneräinen, ensimmäinen versio valmistuu vuoden 2021 loppuun mennessä.</div>

Hieman monimutkaisemmassa esimerkissä tuotetaan viittaus tietyn sanaston tietyyn käsitteeseen:

Sisältö:

{% include common/definitionref.html dict="rytj-kaava" dictname="Kaavatietomalli" id="concept-1008" name="kaava" def="maankäyttö- ja rakennuslain mukaisen kaavoitusprosessin lopputuloksena syntyvä lainvoimainen maankäyttöä tai rakentamista ohjaava suunnitelma." %}

Kutsuttavassa makrossa definitionref.html hyödynnetäään Liquid-kielen ehtolauseita ja useita include-komennon mukana välitettäviä parametreja:

<div class="definitionref">
    <div class="btn-group">
    {%- if include.status -%}
        <button type="button" disabled="disabled" class="status btn btn-{% case include.status %}{% when 'Keskeneräinen' %}danger{% when 'Luonnos' %}warning{% when 'Ehdotus' %}warning{% when 'Muutosehdotus' %}warning{% when 'Hyväksytty' %}success{% else %}info{% endcase %}">{{ include.status }}</button>
    {%- endif -%}
    </div>
    {%- if include.dict -%}
    <h1>Yhteentoimivuusalustan sanasto: <a href="http://uri.suomi.fi/terminology/{{ include.dict }}/terminological-vocabulary-0">{{ include.dictname }}</a></h1>
    {%- else -%}
    <h1>Paikallinen sanasto: {{ include.dictname }}</h1>
    {%- endif -%}
    <dl class="definition">
        <dt class="definition-concept">Termi: {{ include.name }}</dt>
        {% if include.def %}
        <dd class="definition-text">Määritelmä: {{ include.def }}</dd>
        {% else %}
        <dd class="definition-text">Ei määritelmää</dd>
        {% endif %}
        {% if include.note %}  
        <dd class="definition-note">Huomautus: {{ include.note }}</dd>
        {% endif %}  
    </dl>
    <p>
    {%- if include.dict and include.id -%}
        <a href="http://uri.suomi.fi/terminology/{{ include.dict }}/{{ include.id }}" class="definition-uri">http://uri.suomi.fi/terminology/{{ include.dict }}/{{ include.id }}</a>&nbsp;<i class="fas fa-external-link-alt"></i>
    {%- else -%}
        (viittaus sanaston termiin puuttuu)
    {%- endif -%}
    </p>
</div>

Alla kuvataan kaikki rytm-jekyll-includes -reposta Rakennetun ympäristön tietomallit-sivustolle linkitetyt sisällönmuotoilumakrot.

common/bug.html

Tuottaa Bootstrap-kirjaston alert-elementin, jonka avulla voidaan ilmaista havaittu, ja korjaamista vaativa virhe.

Parametrit:

  • content: laatikon teksti.

Lähdekoodi: sykefi/rytm-jekyll-includes/bug.html

common/important.html

Tuottaa Bootstrap-kirjaston alert-elementin, jonka avulla voidaan ilmaista erityisen tärkeä huomautus.

Parametrit:

  • content: laatikon teksti.

Lähdekoodi: sykefi/rytm-jekyll-includes/important.html

common/note.html

Tuottaa Bootstrap-kirjaston alert-elementin, jonka avulla voidaan ilmaista huomautus.

Parametrit:

  • content: laatikon teksti.

Lähdekoodi: sykefi/rytm-jekyll-includes/note.html

common/question.html

Tuottaa Bootstrap-kirjaston alert-elementin, jonka avulla voidaan ilmaista avoin kysymys.

Parametrit:

  • content: laatikon teksti.

Lähdekoodi: sykefi/rytm-jekyll-includes/question.html

common/tip.html

Tuottaa Bootstrap-kirjaston alert-elementin, jonka avulla voidaan ilmaista vinkki.

Parametrit:

  • content: laatikon teksti.

Lähdekoodi: sykefi/rytm-jekyll-includes/tip.html

common/callout.html

Tuottaa Jekyll Doc Theme-kirjastosta lainatun callout-elementin, jonka avulla voidaan ilmaista korostettu kappale.

Parametrit:

  • type: arvo jokin seuraavista: "danger", "default", "primary", "success", "info", tai "warning".
  • content: laatikon teksti.

Lähdekoodi: sykefi/rytm-jekyll-includes/callout.html

common/clause_start.html ja common/clause_end.html

Tuottaa tunnuksellisen vaatimuksen tai suosituksen aloitus- ja lopetus-elementit.

Parametrit (clause_start):

  • type: joko "req" (oletus) tai "rec"
  • id: vaatimuksen tai suosituksen tunnus

Vaatimuksen tai suoristuksen tekstisisältö tuotetaan clause_start ja clause_end-makrojen väliin käyttäen markdown-syntaksia:

{% include common/clause_start.html type="req" id="elinkaari/vaat-identiteettitunnus-maar" %}
Kaavatietomallin tietokohteissa identiteettitunnus kuvataan attribuutilla ```identiteettiTunnus```. Kahdella kaavatietomallin versioitavalla objektilla voi olla sama ```identiteettiTunnus```-attribuutin arvo ainoastaan, mikäli kaikki seuraavista ehdoista ovat tosia:
* Molemmat objektit kuvaavat saman kaavan tai sen sisältämän, nimettävissä olevan tietokohteen kehityskaaren eri tiloja.
* Molemmat objektit liittyvät samaan kaavaan.
* Molemmat objektit ovat saman loogisen tietomallin luokan edustajia.
{% include common/clause_end.html %}

Lähdekoodi: sykefi/rytm-jekyll-includes/clause_start.html ja sykefi/rytm-jekyll-includes/clause_end.html

common/codelistref.html

Tuottaa viittauksen Yhteentoimivuusalustan koodistoon.

Parametrit:

  • registry: viitattava Yhteentoimivuusalustan koodiston rekisteri
  • id: viitattava Yhteentoimivuusalustan koodiston tunnus
  • name: viitattava Yhteentoimivuusalustan koodiston nimi

Lähdekoodi: sykefi/rytm-jekyll-includes/codelistref.html

common/definitionref.html

Tuottaa viittauksen Yhteentoimivuusalustan Sanastotyökalun tai paikallisen sanaston tiettyyn käsitteeseen.

Parametrit:

  • status: "Keskeneräinen", "Luonnos", "Ehdotus", "Muutosehdotus", "Hyväksytty"
  • dict: viitattavan sanaston tunnus. Jos ei anneta, tulkitaan paikalliseksi sanastoksi
  • dictname: sanaston nimi
  • name: käsitteen nimi
  • def: käsitteen määritelmä
  • note: huomautus

Lähdekoodi: sykefi/rytm-jekyll-includes/definitionref.html

common/moduleLink.html

Tuottaa linkin kyseisen modulin version riippuvuudeksi konfiguroidun toisen modulin dokumentaatioon Rakennetun ympäristön tietomallit-sivustolla. Käyttämällä tätä makroa linkkejä viitatun riippuvuusmodulin dokumentaatioon ei tarvitse päivittää markdown-sisällössä, kun riippuvuusmodulin versio vaihtuu, vaan linkin polku päivitetään automaattisesti viitatun modulin konfiguraation perusteella. Tämä säästää huomattavasti työaikaa tilanteissa, jossa modulin dokumentaatio päivitetään uuden version mukaiseksi, ja myös riippuvuuksien versio vaihtuu, tai kun dokumentaatio laaditaan ensin käyttäen riippuvuuden dev-versiota, ja kun riipuvuus myöhemmin päivitetään käyttämään julkaisuversiota.

Parametrit:

  • moduleId: viitatun modulin tunnus
  • path: sivupolku modulin <basepath>/[<versionId>/]-osan jälkeen
  • title: linkin otsikko

Käyttää apufunktiota getDependencyVersionPath ja globaalimuuttujia site.data.modules ja current_module. Asettaa arvon globaalimuuttujalle current_module, mikäli se ei ole asetettu (yksittäisten sivujen sisällöt muodostetaan aiemmassa vaiheessa kuin missä sivupohja generoidaan, joten header-makroa ei vielä ole ajettu).

Lähdekoodi: sykefi/rytm-jekyll-includes/moduleLink.html

Sivujen rakenneosat

Alla esiteltyjen makrojen avulla tuotetaan sivujen sellaisia rakenneosia, jotka eivät koske sivun tekstisisältöä, vaan joiden avulla tuotetaan HTML-koodia varsinaisen sisällön ympärille, esim. sitä ennen ja sen jälkeen, tai sivuston navigaatiorakenteita. Näitä kutsutaan tyypillisesti sivupohjissa (docs/_layouts-hakemisto).

common/header.html

Tuottaa kaikkien sivuston HTML-sivujen yhteisen alkuosan, sisältäen head-osion kokonaan ja body-osion alkuosan ylänavigaatiopalkkiin saakka. Kutsuu apufunktiota assignCurrentModule, asettaa sivun konfiguraatiotietoihin perustuvan otsikon muuttujaan pageTitle, sivun lähdekooditiedoston nimen ja GitHub-polun muuttujaan filePath, sivun koko sivuston tasolla yksilöivän tunnuksen muuttujaan pageId ja valitun modulin lähdekoodin GitHub-repon tunnuksen muuttujaan gh_repo.

Sisältää myös sivun metatiedot GitHub REST APIna avulla noutavan ja sivujen metatietolaatikkoon avulla päivittävän JavaScript-koodin, joka käynnistetään sivun rakenteen latauduttua kokonaan (käynnistys tiedostossa footer).

Lähdekoodi: sykefi/rytm-jekyll-includes/header.html

common/footer.html

Tuottaa kaikkien sivuston HTML-sivujen yhteisen loppuosan, sisältäen alalaiden logopalkin ja erinäisiä JavaScript-kirjastojen latauskomentoja.

Lähdekoodi: sykefi/rytm-jekyll-includes/footer.html

common/navbar.html

Tuottaa sivujen yläreunan navigaatiopalkin päätason pudotusvalikkoineen docs/_data/topnavigation.yml-konfiguraatiotiedoston perusteella. Kukin pudotusvalikon navigaatiolinkki tuotetaan kutsumalla navbar_item-makroa ko. navigaatio-objekti parametrina.

Lähdekoodi: sykefi/rytm-jekyll-includes/navbar.html

common/navbar_item.html

Tuottaa yhden yläpalkin pudotusvalikon navigaatiolinkin.

Parametrit:

  • item: nav_items-listan navigaatio-objekti. Oletetaan seuraava alarakenne:
    • type: joko "link" tai "module"
    • jos type == "link" (ulkoinen linkki):
      • title: linkin otsikko
      • href: linkin osoite
    • jos type == "module":
      • moduleId: linkitettävän modulin tunnus
  • itemclass: tuotetun li-elementin sisälle tuotettavan a- tai span-elementin class-attribuuttiin tyylitystä varten lisättävä luokka.

Lähdekoodi: sykefi/rytm-jekyll-includes/navbar_item.html

common/modulenav.html

Tuottaa modulin otsikkotiedon, versiovalitsimen ja sisäisen navigaatiopuun modulin konfiguraatiotiedoston, pageId- ja current_module_version-muuttujien arvojen perusteella.

Lähdekoodi: sykefi/rytm-jekyll-includes/modulenav.html

common/pagemeta.html

Tuottaan rungon sivujen metatietolaatikon tiedoille (sivun status, viimeisin muutosaika, muutoshistorialinkki, palautelinkki), joiden tiedot päivitetään GitHub REST APIa hyödyntävällä JavaScript-koodilla (ks. header).

Lähdekoodi: sykefi/rytm-jekyll-includes/pagemeta.html

Apufunktiot

Liquid-kielessä ei oikeastaan ole funktioiden määrittelyrakenteita, mutta kutsumalla funktiomakroa include-komennolla ja sijoittamalla sen tuottaman tulosteen muuttujaan capture-komennolla, on mahdollista simuloida yksinkertaisia merkkijonoja tai numeroita palauttavia funktioita.

Seuraava esimerkki kutsuu "funktiota" getPageTitle parametreilla haystack ja needle, nappaa talteen sen tulostaman merkkijonon ja sijoittaa sen muuttujaan pageTitle:

{%- capture pageTitle %}{%- include common/getPageTitle.html haystack=current_module.nav_items needle=page.id -%}{%- endcapture -%}

Huomaa, että Jekyll/Liquid -käännösympäristössä muuttujilla on vain globaali skooppi, eli myös include-komennolla sivulle sisällytetyt liquid-muuttujien asetukset ja muokkaamiset operoivat samaan muistiin kuin niitä kutsuvalla sivulla käytetyt. Liquid-muuttujien nimeämisen kanssa kannattaakin olla tarkkana.

common/assignCurrentModule.html

Päättelee ja asettaa sivun osoitteen perusteella nykyisen tietomoduliin muuttujaan current_module ja nykyisen version muuttujaan current_module_version.

Lähdekoodi: sykefi/rytm-jekyll-includes/assignCurrentModule.html

common/getDependencyVersionPath.html

Tulostaa parametrina annetun modulitunnuksen mukaisen modulin sen version, joka on asetettu nykyisen modulin tai sen riippuvuuden riippuvuudeksi, path-tiedon. Kutsuu itseään rekursiivisesti läpikäyden moduliversioiden riippuvuuksien riippuvuuksia kunnes kaikki on läpikäyty tai haettu modulitunnus löytyy.

Parametrit:

  • targetModuleId: kohdemodulin tunnus (.yml-tiedoston nimi)
  • target: kohdemodulin konfiguraatiodata
  • current_module_version: moduliversion konfiguraatio-objekti, jonka riippuvuusmoduleita ollaan läpikäymässä
  • traversed: taulukko jo rekursiossa läpikäytyjä modulitunnuksia luuppien tunnistamiseksi

Lähdekoodi: sykefi/rytm-jekyll-includes/getDependencyVersionPath.html

common/getFilePath.html

Tuottaa tiedostopolun annetulle sivutunnukselle etsien sitä annetusta nav_items-taulukosta tai rekursiivisesti taulukon sisältämien objektien nav_items-taulukoista. Mikäli GitHubFile-ominaisuutta ei ole annettu, palautetaan oletuksena <pageId>/index.md. Rekursiopolun varrella tavattujen välitasojen polkutunnukset lisätään tulostukseen.

Parametrit:

  • needle: läpikäytävä nav_items-taulukko
  • haystack: etsittävän sivun tunnus.

Lähdekoodi: sykefi/rytm-jekyll-includes/getFilePath.html

common/getNavItemPath.html

Tuottaa annetun osoitepolun nav_items-taulukon page- tai group-tyyppiselle sisältöobjektille. Mikäli path-tieto on annettu, palautetaan se sellaisenaan, muuten palautetaan merkkijono <pageId>/ tai <groupId>/.

Lähdekoodi: sykefi/rytm-jekyll-includes/getNavItemPath.html

common/getPageTitle.html

Tuottaa otsikon annetulle sivutunnukselle käymällä läpi nav_items-taulukon tai rekursiivisesti taulukon sisältämien objektien nav_items-taulukot.

Lähdekoodi: sykefi/rytm-jekyll-includes/getPageTitle.html

Clone this wiki locally