CSS-muuttujat ja laskelmat dokumentaation tukena

Aiempi DocRaptor-julkaisuputken päivitys DoX CMS:ssä mahdollisti CSS-muuttujien ja laskelmien käyttämisen myös sitä kautta kasatuissa PDF-julkaisuissa. Muut näiden tyylitiedostojen toimintojen kanssa yhteensopivat julkaisumuodot ovat oletuskasaajalla tehdyt PDF:t, ja verkkojulkaisut eli HTML ja WebHelp. Tämän päivityksen vuoksi on kuitenkin syytä tutustua näiden CSS:n toiminnallisuuksien mahdollisuuksiin tarkemmin.

CSS-muuttujat ovat tyylitiedostojen sisällä määritettyjä uudelleenkäytettäviä vakioarvoja. Niille voi tarvittaessa määrittää poikkeavat tilannekohtaiset arvot. Nämä muuttujat eivät liity millään tapaa DoX CMS:n muuttujiin, joita ei edelleenkään voi käyttää tyylitiedostoissa. Perusesimerkkejä CSS-muuttujien käyttötavoista ovat vakioidut värikoodit ja keskenään koordinoidut mitat kuten toteutuksiltaan erilaisten syvennyksien määrät.

Laskelmat ovat puolestaan keino määrittää numeroarvoja suhteuttamalla muualla käytettyjä arvoja toisiinsa tai käyttämällä laskukaavoja muista syistä. Niillä voi esimerkiksi yhdistää arvoja eri yksiköillä yhdeksi arvoksi tai viitata useampien CSS-muuttujien arvoihin.

Näillä keinoin voit välttää toisiinsa liittyvien arvojen toistamista. Kun näitä arvoja päivitetään, ei niitä tarvitse jäljittää erikseen jokaisessa niiden sijainneista. Lisäksi arvoja saa näin johdettua muista arvoista, jolloin johdannaiset arvot päivittyvät välittömästi vastaamaan muutoksia suoraan hallinnoiduissa arvoissa.

Käyn kuhunkin toiminnallisuuteen liittyen läpi siihen liittyvät merkintätavat sekä esimerkkejä keinoista käyttää sitä dokumentaation tukena.

CSS-muuttujat

Kukin CSS-muuttuja koostuu nimestä ja tilannekohtaisesti säädettävissä olevasta arvosta. Tällaiset muuttujat täytyy määrittää suhteessa niiden käyttöpaikat kattavaan valitsijaan. Oletusarvot kannattaa täten asettaa sisällön pohjaelementille kuten sen body-elementille. Saat lisättyä poikkeusarvot suhteessa vaadittuja poikkeustilanteita vastaaviin valitsijoihin.

CSS-muuttujat saa siis käyttöön alla esittämälläni tavoin. Se vaatii kaksi väliviivaa ja niihin kytketyn nimen. Arvot annetaan samalla tavoin kuin arvot muille CSS-säännöille. Käytetty valitsija määrittää, missä käyttöyhteyksissä annettu arvo pätee kyseiselle muuttujalle. Alla on esimerkki tästä merkintätavasta:

body {
    --example_variable: 20px;
}

.dita-table {
    --example_variable: 5px;
}

Tällä hetkellä DoX CMS:n CSS-editorin värikoodit eivät tunnista muuttujia päteviksi säännöiksi. Tästä syystä ne voivat rikkoa niiden alapuolella olevien osuuksien värjäykset editorissa, vaikka kaikki säännöt toimivat edelleen ongelmitta. Suosittelen siis muuttujien määrittämistä erillisessä tyylitiedostossa. Myös niiden lisääminen tyylitiedoston loppuun on mahdollista. Muuttujien lisäämisellä osaksi arvoja muualla ei ole samaa vaikutusta.

Näiden muuttujien käyttäminen arvoina muualla vaatii niiden nimien ympärille kehystä var(). Tällä tavoin muuttujat voi sijoittaa muiden sääntöjen arvoiksi tai osiksi kyseisiä arvoja. Kun muuttujan arvo muuttuu, muuttuu myös kyseisen säännön käyttämä arvo. Alla on esimerkki tästä merkintätavasta:

p, .topicBodyWrapper > div {
    margin-left: var(--example_variable);
}

td > p {
    padding: var(--example_variable);
}

Muuttujia voi myös käyttää osana toisia muuttujia. Esimerkiksi usean eri muuttujan arvot voi koota yhdeksi muuttujaksi niiden sijoittamiseksi muualle. Lisäksi muuttujan arvo voi perustua laskelmaan toisen muuttujan arvon perusteella.

Lisätietoja CSS-muuttujista löytyy W3C:n kautta.

Esimerkkisovelluksia: CSS-muuttujat

Nämä ovat esimerkkejä erilaisista soveltamiskeinoista CSS-muuttujille. En sisällytä mukaan keinoja, jotka vaativat laskelmia. Käyn erikseen läpi keinoja käyttää muuttujia osana laskelmia laskelmien osuudessa.

Vakioidut arvot

Tämä on kaikkein yksinkertaisin tapa käyttää CSS-muuttujia. Kun tarvitset samaa arvoa useampaan sijaintiin, voit muuttaa sen muuttujaksi. Tämä on erityisen hyödyllistä, kun kyseinen arvo on monimutkainen tai muutoin vaikea pitää mielessä. Alla antamani esimerkki esittää keinon lisätä brändin tyylioppaan mukaiset värit muuttujina. Niihin voi viitata tällöin nimeltä vaikeiden muistaa värikoodien sijaan.

body {
    --brand_green: #485f48;
    --brand_black: #171717;
    --brand_yellow: #fffdd0;
}

.topicTitleWrapper {
    color: var(--brand_black)
    border: 2px solid var(--brand_black);
    border-left: 5px solid var(--brand_green);
}

Arvojen muuttaminen

Saat tarvittaessa vaihdettua muuttujien arvoja tilannekohtaisesti. Kenties tällä tavoin saavutettu etu näyttää vähäiseltä, koska näissä tilanteissa voisi usein vain määrittää käyttöön muuttujasta riippumattoman uuden arvon. Näin vältät kuitenkin näihin arvoihin liittyvien sääntöjen toistamisen. Jos myös käytät samoja arvoja useamman eri säännön yhteydessä, kuten sekä otsikoiden että kehyksien värien määrittämiseen, tarvitsee kyseinen arvo tällöin merkitä vain kerran.

Elementtiluokat

Kuten mikä tahansa muu tilannekohtainen sovitus, on tällainen muuttujan arvon vaihtaminen sidottavissa elementtiluokkaan. Esimerkki alla tekee näin perustaulukoiden (simpletable) sarakkeiden leveyksille. Tällä tavoin saat käyttöön useampia taulukoiden asettelun pohjia tarvitsematta toistaa niihin liittyviä monimutkaisia valitsijoita ja sääntöjoukkoja. Tämä esimerkki ei havainnollista kuin kahden ensimmäisen sarakkeen säännöt kahdelle elementtiluokalle.

body {
    --column1: auto;
    --column2: auto;
}

table {
    width: 100%;
    table-layout: fixed;
}

table:not(.dita-table table) td:nth-child(1) {
    width: var(--column1);
}

table:not(.dita-table table) td:nth-child(2) {
    width: var(--column2);
}

[doxelementclass~="IconTable"] {
    --column1: 20%;
    --column2: 5%;
}

[doxelementclass~="CommandTable"] {
    --column1: 40%;
    --column2: 60%;
}

Päätekohtaiset sovitukset

Vastaavat ratkaisut ovat käytettävissä myös verkkojulkaisujen sovittamiseen erilaisille päätteille. Tällöin uudet muuttujien arvot täytyy määrittää eri päätetyypeille. Alla esittämäni esimerkki tekee näin otsikoiden koolle. Toki tämä on esimerkki, jossa erillisten arvojen sijaan olisi vielä helpompaa vain määrittää johdannaiset arvot laskelmien avulla.

body {
    --level1title: 24px;
    --level2title: 20px;
}

.titleWrapper_Level1 {
    font-size: var(--level1title);
}

.titleWrapper_Level2 {
    font-size: var(--level2title);
}

@media only screen and (max-width: 800px) {
    --level1title: 18px;
    --level2title: 16px;
}

Mukautuvat yksilähteistetyt sisällöt

Olen esittänyt aiemmin keinon muuttaa muuttujien arvoja sijaintikohtaisesti julkaisujen sisällä täällä. Tällainen ratkaisu antaa sijoittaa julkaisun sisällä toistuviin vakioituihin lauserakenteisiin tilannekohtaisesti muuttuvia osuuksia. Itse rakenne pysyy muotoilultaan yksilähteistettynä mutta muutokset tulevat käyttöön jokaiseen sen käyttöpaikkaan. Vastaava ratkaisu on toteutettavissa myös CSS-muuttujien avulla. Huomioi tosin, kuinka näin lisätyt osuudet eivät saa olla kieliopillisesti taipuvia.

Tämän ratkaisun tapauksessa kyse on tyylitiedoston kautta lisättävästä ilmaisusta muutoin tyhjään mutta asianmukaisesti merkittyyn fraasielementtiin (ph). Suosittelemani tapa merkitä nämä elementit ovat elementtiluokat. Jotta kyseinen osuus pysyy yksilähteistettynä, ei käytettyä arvoa hallinnoivia elementtiluokkia voi käyttää siihen. Ne täytyy lisätä sen ulkopuolisille kehyksille kuten osioelementeille (section). Oikean osuuden tunnistamiseen kehyksen sisällä vaaditaan tällöin tosin oma tunnisteensa. Tähän tarkoitetussa tyylitiedostossa annetut säännöt lisäävät näihin elementteihin sisältöä ::before-pseudoelementtien kautta. Kun lisätyn sisällön arvo on CSS-muuttuja, on sille helppo määrittää kielikohtaiset arvot. Alla on esimerkkitoteutus tälle.

[doxelementclass~="Menu_Editor"] span[doxelementclass~="InsertContent"]::before {
    content: var(--menu_editor);
}

[doxelementclass~="Menu_Tags"] span[doxelementclass~="InsertContent"]::before {
    content: var(--menu_tags);
}

span[doxelementclass~="InsertContent"]::before {
    text-transform: capitalize;
}

[lang="fi"] [doxelementclass~="Menu_Editor"] {--menu_editor: "editori";}
[lang="fi"] [doxelementclass~="Menu_Tags"] {--menu_editor: "editori";}

[lang="en"] [doxelementclass~="Menu_Editor"] {--menu_editor: "editor";}
[lang="en"] [doxelementclass~="Menu_Tags"] {--menu_editor: "editor";}

Varmuuden vuoksi alla on havainnollistus myös sisällöistä, jollaisia nämä säännöt vaatisivat. Mukana on sekä yksilähteistämiskeinona toimivan sisältöviitteen (conref) lähdeversio että yksi sijoitettava kohdeversio, jonka ympärillä ovat asianmukaiset tunnisteelliset kehykset. Kohta ’#333’ viittaa vain lähdeversion otsikkosisällön ID-arvoon.

<p id="system_toolbar_open_menu">Click on the related icon in the system toolbar to open the <ph doxelementclass="InsertContent"/> menu.</p>

<section doxelementclass="Menu_Editor">
    <p conref="#333/system_toolbar_open_menu"/>
</section>

Sijoittelun koordinointi

Kun tietyt arvot on sidottu muuttujiin, voi näitä muuttujia käyttää myös muualla tavalla, joka asettuu yhteen niiden alkuperäisten käyttötapojen kanssa. Jos pidät muuttujan arvon samana näiden käyttöpaikkojen kesken, saat koordinoitua sisällön eri osien asettumisen niiden avulla. Voit esimerkiksi kytkeä huomioelementtien (note) toistumattoman taustakuvan eli käytetyn ikonin leveyden ja niiden sisällön syvennyksen samaan muuttujaan. Tällä tavoin sisältö syventyy aina ikonin leveyden verran eikä koskaan asetu sen päälle. Laskelman avulla voit lisätä tähän syvennykseen myös vakioidun lisämäärän.

Tämä menetelmä pitää elementtien väliset suhteet vakioituina riippumatta käytetyistä arvoista. Tällainen keskinäinen koordinointi helpottaa näiden arvojen muuttamista esimerkiksi sisällön sovittamiseksi erilaisille päätteille. Lisäksi se tekee päivityksistä näihin arvoihin helpompia, koska muut koordinoidut arvot päivittyvät vastaavissa määrin samaan aikaan.

Alla esittämäni esimerkki tekee otsikoiden sisennyksestä suhteessa niiden numeroarvoihin saman kuin muun sisällön alkamiskohta. Lisäsin myös tähän käytetyn muuttujan osaksi toista muuttujaa näyttääkseni, kuinka tätä toiminnallisuutta voi käyttää. Tämä toteutus ei käytä laskelmia, mutta myös ne ovat hyödyllisiä osana vastaavia toteutuksia.

body {
    --BaseIndent: 25mm;
    --ContentPadding: 2mm 10mm 2mm var(--BaseIndent);
}

.titleWrapper .titleNumberWrapper {
    width: var(--BaseIndent);
}

.topicBodyWrapper > *:not(.dita-section), .dita-section > * {
    padding: var(--ContentPadding);
}

Laskelmat

Laskelmat antavat muodostaa laskukaavojen mukaisia numeroarvoja yksiköiden kanssa tai ilman yksiköitä. Niiden osana voi käyttää summaamista, vähentämistä, kertomista sekä jakamista. Niiden sisällä sallitut arvot ovat numeroita, joilla voi olla yksiköt, sekä CSS-muuttujia, joilla on vastaavat arvot. Laskelmat antavat myös yhdistää arvoja, joilla on eri yksiköt. Voit esimerkiksi lisätä lisäleveyttä millimetreissä sadan prosentin päälle, kun haluat elementin venyvän yli sitä ympäröivän elementin rajojen.

Laskelmat lisätään tyylitiedostoihin samaan tapaan kuin muut sääntöjen arvot. Niiden muotoilu koostuu laskukaavasta calc()-tunnisteen sisällä. Tämän laskukaavan osat eli siinä käytetyt arvot ja erikoismerkit täytyy erottaa toisistaan välilyönneillä. Jos lisäät toisen laskelman päälaskelman sisään tai haluat käyttää poikkeavaa laskujärjestystä, voit lisätä näiden osuuksien ympärille ylimääräiset sulkeet. Negatiiviset arvot ovat sallittuja. Myös rivinvaihdot sekä ylimääräiset välilyönnit laskukaavojen sisällä ovat sallittuja.

Alla ovat eri laskutoimituksien käyttämät erikoismerkit:

• X + Y: X ja Y summa
• X – Y: Y vähennettynä X:stä
• X * Y: X kertaa Y
• X / Y: X jaettuna Y:llä

Täten laskelma CSS:ssä voi näyttää esimerkiksi tältä:

h2 {
    font-size: calc(var(--TitleBaseSize) * 0.8)
}

Lisätietoja laskelmista löytyy W3C:n kautta.

Esimerkkitoteutuksia: Laskelmat

Nämä ovat esimerkkejä erilaisista soveltamiskeinoista tyylitiedostojen laskelmille.

Ilmaisujen selkiyttäminen

Paljonko on seitsemäsosa sadasta prosentista? Tämä arvo on mahdollista laskea etukäteen ja kirjata tyylitiedostoon. Jos tyylitiedoston myöhempi lukija ei tosin tiedä vastausta, voi hänen olla hankalaa päätellä, mihin arvo 14,3% viittaa. Sen sijaan auki kirjattu laskelma on tältä osin välittömästi ilmeinen ilmaisutapa. Sama pätee myös useammasta arvosta johdettuihin arvoihin kuten niiden yhteen laskettuun pituuteen. Käsittelen niitä kuitenkin erikseen alempana.

Tämä esimerkki on vastaava kuin edellinen esimerkki, mutta korvasin muuttujan sen arvolla. Suosittelen vahvasti muuttujan käyttämistä. Myös tämä merkintätapa kuitenkin havainnollistaa tyylitiedoston lukijalle, kuinka haluttu arvo on johdannainen toisesta arvosta eikä mielivaltainen pienempi luku.

h2 {
    font-size: calc(24px * 0.8)
}

Yksiköiden yhdistäminen

Laskelmien arvojen ei tarvitse koostua enintään yhdestä yksiköstä. Lopullinen arvo voi perustua useampaa yksikköä käyttävien arvojen yhdistämiseen. Nämä arvot voivat olla myös sekoitus sekä suhteellisia että määrättyjä yksiköitä kuten prosentteja ja millimetrejä. Tällä tavoin voit myös yhdistää CSS-muuttujia, joiden arvot ovat eri yksiköissä. Hyöty tältä osin on, kuinka toisten arvojen kanssa koordinoituja arvoja ei tällöin tarvitse yrittää ilmaista vain yhden yksikön kautta. Vastaavasti nämä muut arvot voivat myös koostua eri yksiköistä kuten valitusta suhteellisesta yksiköstä ja valitusta määrätystä yksiköstä, kun se on perusteltua.

Esimerkki alla näyttää arvon, jolla suuret kuvat voi venyttää yli tekstilaatikoiden rajojen. Huomioi kuitenkin, että tällaiset kuvat on yleensä syytä myös keskittää sivusuunnassa. Säännöt tälle eivät ole mukana esimerkissäni.

.dita-fig img {
    width: calc(100% + 20mm);
}

Suhteelliset mitat

Kun laskelmassa on mukana muuttujia, voit määrittää laskettavan uuden arvon suhteessa niiden arvoihin. Tällä tavoin lasketut arvot skaalautuvat samassa suhteessa, kun muuttujien kautta saadut pohja-arvot muuttuvat.

Tällä tavoin saat esimerkiksi sijoitettua siirretyn elementin suhteessa toisen elementin leveyteen. Suunniteltu päivitys omaan oppaaseemme sisältää tällaisia osuuksia. Ne ovat erityisen hyödyllisiä verkkojulkaisuissa, missä osa elementeistä on sijoitettavissa itse sisällön jatkumon ulkopuolelle. Alla esittämässäni esimerkissä siirrän fastpath-tyypin huomioelementin (note) muun sisällön sivuun. Tällä tavoin se toimii selatessa paikallaan pysyvänä säilytyspaikkana linkeille pitkän otsikkosisällön eri osuuksiin.

body {
    --FastpathPosition: calc(var(--TopicWidth) + var(--TopicRightMargin));
    --TopicRightMargin: 5vw;
    --TopicWidth: 55vw;
}

.topicWrapper {
    width: var(--TopicWidth);
    margin-right: var(--TopicRightMargin);
}

[data-ditaatribute-type="fastpath"] {
    position: fixed;
    right: var(--FastpathPosition);
}

Animaatiot

CSS:n kautta toteutetut animaatiot vaativat useimmiten eri vaiheisiin liittyvien arvojen määrittämistä. Niiden välisten vaiheiden arvot lasketaan siirtymälle määritetyn ajan sekä näiden avainarvojen perusteella. Laskelmat antavat määrittää kohdearvot suhteessa aloitusarvoon. Tällöin näitä arvoja ei tarvitse laskea tai arvioida etukäteen ja halutut arvot ovat myös selvempiä yllä esitettyyn tapaan.

Tämä yksinkertainen esimerkki näyttää, kuinka kuvan koon saa kasvamaan haluttuun tahtiin, kun osoittimen siirtää sen ylle. Rajoitan tämän toiminnallisuuden kuvakehyksien (fig) sisällä oleviin kuviin. Tämä toteutus tosin näyttää pienennysanimaation, kun kuvat ladataan näkyviin ensimmäisen kerran. Sen ympäri on keinoja, mutta käytän tätä toteutusta vain havainnollistuksena.

body {
    --FigImageWidth: 20vw;
    --FigImageWidthHover: calc(var(--FigImageWidth) * 3);
}

@keyframes FigImageHover {
    from {width: var(--FigImageWidth);}
    to {width: var(--FigImageWidthHover);}
}

@keyframes FigImageHoverLeave {
    from {width: var(--FigImageWidthHover);}
    to {width: var(--FigImageWidth);}
}

.dita-fig > p img {
    animation: FigImageHoverLeave 1s forwards;
    width: var(--FigImageWidth);
    height: auto;
}

.dita-fig > p img:hover {
    animation: FigImageHover 1s forwards;
}

Yhteenveto

CSS-muuttujat ja laskelmat ovat käytettävissäsi erilaisissa PDF– ja HTML-julkaisuissa. Myös DoX CMS:n päivitetty DocRaptor-julkaisuputki antaa nyt käyttää niitä. Niiden avulla saat määritettyä tyylitiedostojen käyttöön vakioituja ja keskenään koordinoituja arvoja sekä niiden johdannaisia.

Vakioitujen arvojen lisäksi käyttökeinot CSS-muuttujille kattavat näiden arvojen tilannekohtaiset sovitukset ilman tarvetta toistaa monimutkaisia valitsijoita tai niihin liittyviä sääntöjä. Voit kytkeä tällaiset sovitukset varsinkin elementtiluokkiin tai päätekohtaisiin eroihin. Ne myöskin antavat lisätä muutoin yksilähteistettyihin sisältöihin dokumenttien sisällä tilannekohtaisesti vaihtuvia ilmaisuja sekä eri osuuksien välillä koordinoituja arvoja eri sääntöjen osalta.

Laskelmien avulla saat lisättyä tyylitiedostoihin laskukaavoja. Nämä laskelmat voivat sisältää myös CSS-muuttujia ja tällöin niiden tulokset muuttuvat, jos mukana olevien muuttujien arvot vaihtuvat. Laskelmien avulla voit esittää niistä riippuvaisia arvoja niiden lopputuloksia selkeämmin, yhdistää eri yksiköitä käyttäviä arvoja, suhteuttaa eri arvoja toisiinsa sekä antaa CSS-animaatioiden avainarvot muutoksina erikseen määritettyyn pohja-arvoon.