2021 ensimmäinen iso päivitys lisäsi DoX CMS:ään WebDav-pohjaisen mahdollisuuden työstää sisältöjä ulkoisilla editoreilla. Verkkolevylle kirjautumisen ohjeet löytyvät käyttöoppaasta. DoX CMS kuitenkin sisältää myös monia ominaisuuksia kuten muuttujat, tagit ja elementtiluokat, joille ei ole sisäänrakennettua ulkoista tukea. Tässä artikkelissa käyn läpi perusteet oXygen XML-editorin ja DoX CMS:n yhteensovittamisen osalta. Asiakkaiden tarpeista riippuen tulen luultavasti käymään vastaavan prosessin läpi myös ainakin Adobe FrameMakerin osalta. Ominaisuuden jatkokehitys tosin helpottaa prosessia, koska tiedämme jo seuraavat askeleet integraation parantamiseksi.
Sekä tagit että elementtiluokat on mahdollista ottaa käyttöön tekstin profiloinnin ja ehdollistamisen luokkia lisäämällä. Muuttujat on mahdollista sijoitella kirjoittamalla niiden tunnisteet käsin. Tämä on ollut aina mahdollista myös DoX CMS:ssä. Myös sisäisten linkkien lisäämiseen liittyy selventämisen tarpeessa olevia rajoituksia oXygenin käyttöliittymän osalta. Näiden keinojen selventämisen jälkeen mainitsen vielä yhteensopivuuden rikkovista oXygenin toiminnoista sekä muutamasta ulkoisten editorien tuen kehitystarpeesta, joihin tulemme vastaamaan mahdollisimman pian.
Tagit ja Elementtiluokat
Toistaiseksi tuki sekä tageille että elementtiluokille täytyy lisätä käsin oXygenin asetuksissa. Tästä syystä suosittelemme, että tarvitut tagit ja elementtiluokat valmistellaan etukäteen. Näin vähennetään tarvetta niiden myöhemmälle yksitellen lisäämiselle ja riskiä unohtaa jonkun myöhemmin lisäämä luokka omista asetuksistasi. Toisin kuin selainpohjainen DoX CMS, kukin ulkoisen editorin instanssi vaatii omat säätönsä, jotka käyttäjien tulee koordinoida keskenään.
Kummankin toiminnon tapauksessa integraation peruste on ’Profiling Settings’, joka löytyy ylärivin valikosta DITA > Profiling/Conditioning Text. Vaihtoehtoisesti samaan valikkoon pääsee kautta Options > Preferences, minkä jälkeen tulee etsiytyä kohtaan Editor > Edit Modes > Author > Profiling/Conditional Text > Attributes and Condition Sets.
Kun olet oikeassa valikossa, valitse ’New’ kohdan ’Profiling Attributes’ alla. Saat näin lisättyä uusia luokituksia, jotka vastaavat DoX CMS:n logiikkaa tagien ja elementtiluokkien osalta.
Määritä dokumenttien tyypiksi (’Document type’) ’*DITA*’. Asteriskit ovat pakollinen osa tätä arvoa. Kun teet näin, kyseiset arvot on mahdollista valita käytettäviksi DITA-skeemoja käyttäville sisällöille. Tästä kerrotaan lisää alempana.
Arvoksi ’Attribute name’ tulee antaa DoX CMS:n käyttämä sisäinen tunniste halutulle luokalle. Kukin tagikategoria muodostaa oman luokkansa. Elementtiluokilla on oma tunnisteensa.
Tagikategorioiden tunniste on muotoa ’data-doxattribute-kategoria’, missä ’kategoria’ tulee korvata käytetyn tagikategorian (piilo)tunnisteella. Tagien ja niiden kategorioiden tunnisteet on mahdollista löytää Tagit-valikosta DoX CMS:ssä, kun valitset kyseisen tagin ja käytät Tiedot-komentoa. Esimerkiksi tagikategoria ’Manual’ olisi normaalisti koko tunnisteeltaan ’data-doxattribute-Manual’. Poikkeuksen muodostaa, jos sen (piilo)tunniste poikkea sen nimestä nimen muokkauksen tai luontivaiheessa tehdyn erottelun vuoksi. Tällöin sinun täytyy tarkistaa oikea tunniste yllä mainittuun tapaan.
Elementtiluokkien tunniste kohtaan ’Attribute name’ on aina sama: ’doxelementclass’. Niiden tapauksessa muu erottelu perustuu puhtaasti mahdollisiin arvoihin tälle luokalle.
Voit halutessasi nimetä arvon eri tavalla kuin DoX CMS:ssä kohtaan ’Display name’. Suosittelemme kuitenkin käyttämään yhdenmukaista nimeämismallia järjestelmien välillä ja asettamaan luokan nimeksi esimerkiksi ’Tagi: Kategoria’, missä ’kategoria’ korvataan kyseisen tagikategorian nimellä kuten ’Manual’.
Kun olet lisännyt luokan, sinun täytyy lisätä sen mahdolliset arvot samassa valikossa valitsemalla ’New’ taulukon mahdollisista arvoista alla. Kuten yllä, tulee kohtaan ’Value’ käyttää yksittäisen tagin tai elementtiluokan tunnistetta. Elementtiluokkien tapauksessa niiden nimi ja tunniste ovat aina täsmälleen samat. Voit siis käyttää suoraan järjestelmään lisätyn elementtiluokan nimeä. Tagin tunniste on mahdollista löytää sen Tiedot-valikosta yllä esitettyyn tapaan. Kohtaan ’Label’ on mahdollista laittaa vapaamuotoinen nimi, mutta on edelleen parasta käyttää samaa nimeämistapaa kummassakin järjestelmässä. Voit halutessasi lisätä kuvauksen kohtaan ’Description’.
Kun olet lisännyt kaikki tagikategorian tagit tai käytettävissä olevat elementtiluokat mahdollisiksi arvoiksi, voit hyväksyä valintasi tätä uutta attribuuttia koskien. Käytä useamman saman luokan arvon tapauksessa oletuksena ehdotettua valintaa ’Multiple values separated by <space>’, koska tämä vastaa DoX CMS:n toimintaa.
Toista yllä esitetyt askeleet kullekin yhtiönne DoX CMS:n instanssin tagikategorialle ja sen elementtiluokille. Kun olet tehnyt niin, lisää vielä uusi ehtojoukko, joka sisältää ne. Tätä varten, valitse ’New’ kohdan ’Profiling Condition Sets’ alla.
Nimeä uusi ehtojoukko haluamaasi tapaan ja valitse myös sen dokumenttityypiksi (’Document type’) ’*DITA*’. Ota sitten käyttöön halutut luokitukset napsauttamalla niiden nimien yhteydessä annettuja valintakenttiä. Kun napsautat luokituksen nimeä, valitset samalla käytettäviksi kaikki sen sisällä olevat arvot. Voit halutessasi ottaa käytöstä pois joitakin arvoista poistamalla niiden valinnan erikseen.
Kun tämä prosessi on tehty ja valitset käytettäväksi luomasi ehtojoukon, voit lisätä sen sisältämien luokkien arvoja elementeille tavalliseen tapaan. Toisin sanoen voit esimerkiksi napsauttaa dokumentin kohtaa hiiren oikealle painikkeella ja valita komennon ’Edit Profiling Attributes’. Valitsemalla silloin näytetystä joukosta haluamasi tagit tai elementtiluokat, ne lisätään kyseiselle elementille.
Muuttujat
Muuttujien käyttäminen on huomattavasti yksinkertaisempaa. Sinun tarvitsee vain kirjoittaa niiden tunnisteet suoraan tekstiin.
Muuttujan tunniste on sen nimi kahden parin aaltosulkeita sisällä. Esimerkiksi siis minkä tahansa tyypin muuttuja, jonka nimeksi on asetettu ’Product ID’ tulisi kirjoittaa tekstiin muodossa ’{{Product ID}}’. Sinun tulee tosin käyttää muuttujan tarkkaa nimeä: tämä sisältää sekä välilyönnit että isot kirjaimet.
Muista, että voit käyttää tähän tapaan myös DoX CMS:n järjestelmämuuttujia. Lisätietoja niistä löytyy käyttöoppaastamme. Kyseessä on joukko valmiiksi määritettyjä muuttujia, jotka lisäävät merkittyyn kohtaan jonkin järjestelmän tietokannasta haetun arvon kuten julkaisulle annetun nimen tai sen revisioarvon.
Sisäiset Linkit
Normaalisti oXygen sallii lisätä linkkejä ’Link’-toiminnon kautta. Kun tätä kautta yritetään lisätä sisäisiä linkkejä joko toisiin otsikkosisältöihin tai niiden elementteihin, käyttää linkin formaatti kuitenkin kyseisen otsikkosisällön tiedoston koko nimeä. Sen sijaan DoX CMS tunnistaa vain linkit, jotka hyödyntävät otsikkosisältöjen tunnisteita tiedostojen nimien sijaan.
Tämän ongelman kiertämiseksi sinun tulee sen sijaan lisätä sisältöön ensin tyhjä xref-elementti oXygenin elementtilistasta. Kun se on lisätty, voit muokata sen DITA-ominaisuuksia suoraan. Tällöin sinun on mahdollista kirjoittaa href-arvo itse. Voit toki myös ensin käyttää ’Link’-toimintoa ja sitten muokata lisätyn linkin href-arvoa tätä kautta. Jos teet niin, linkkien lisäämiseen liittyy tosin tarpeettomia lisäaskelia, koska joudut määrittämään ensin sopimattoman väliaikaisarvon.
Mitä Et Voi Tehdä
Ohjelmistona oXygen sisältää monia toimintoja, joille ei löydy täyttä vastaavuutta DoX CMS:n sisäisestä editorista. Kun sisältöjä yritetään avata DoX CMS:ssä ja ne sisältävät sen kannalta ymmärtämättömiä pätkiä, saat asiasta joko virheilmoituksen tai sisältö kieltäytyy avautumasta. Tämä osio on varoitus erinäisistä asioista, joita et voi tehdä oXygenissä DoX CMS:n sisällöille.
Kaikkein suurin ongelma ovat lisätoiminnot kuten osien sisällöstä korostaminen tai kommenttien lisääminen. Kumpikin näistä oXygenin toiminnoista estää sisällön avaamisen DoX CMS:ssä, koska ne jättävät tiedostoon täysin poikkeavia merkintöjä, joita sisäinen editori ei kykene lukemaan. Myös DoX CMS sisältää mahdollisuuden sekä sisällön sisäiseen että katselmointimuotoiseen kommentointiin, mutta se perustuu erilaiseen logiikkaan kuin oXygenin kautta lisätyt kommentit. Vastaavia toimintoja on varmasti useampia ja mikäli sisältö ei avaudu DoX CMS:ssä, tulee sinun käydä se läpi tarkistaaksesi, onko jokin tällainen toiminto käytössä sen osalta.
Seuraavaksi suurin ongelma ovat DoX CMS:n kanssa yhteensopimattomat elementit. Jos lisäät täyden DITA:n elementtejä, joita DoX CMS ei tue, saat sisällön avatessasi niiden osalta virheilmoituksen, joka korvaa kyseisen osuuden dokumentista. Jos tallennat tässä vaiheessa, on kyseinen muutos pysyvä. Joka tapauksessa näitä sisältöjä ei siis voi käyttää, jos kyseinen sisältö tullaan koskaan avaamaan muokattavaksi DoX CMS:ssä. Tästä syystä niitä ei tule käyttää, vaikka oXygen sallisi niiden lisäämisen. Jos tarvitsette välttämättä joitakin lisäelementtejä, joita DoX CMS ei jo tue, voi asiasta lähettää pyynnön tukeemme. Koska tulemme tekemään sisäisen editorin kattavan uudistuksen niin pian kuin siihen on mahdollisuus, on luultavaa, että lisäyksiä ei tehdä välittömästi. Pidämme kuitenkin kirjaa näistä toiveista ja pyrimme sisällyttämään asiakkaidemme tarpeita vastaavat toiminnot kuten kyvyn lisätä matemaattisia kaavoja päivitettyyn editoriin.
Viimeinen (pysyvä) ongelma ovat määreet, joita ei ole mahdollista käyttää DoX CMS:n valikoissa elementin DITA-ominaisuuksista. DoX CMS rajoittaa tietoisesti käytettävissä olevien ominaisuuksien määrää, koska esimerkiksi tekstinkorostuksille ei tulisi olla tarpeen lisätä suurinta osaa DITA:n sallimista lisäominaisuuksista. Tämä keventää käyttökokemusta merkittävästi. Se kuitenkin myös tarkoittaa, että järjestelmä ei rekisteröi annettuja lisämääreitä, jotka ylittävät sille määritetyn kapasiteetin. Näistä lisäpiirteistä ei seuraa sisällön menettämistä, mutta järjestelmä ohittaa ja pyyhkii ne, jos koskaan tallennat sisällön DoX CMS:ssä. Tähän on joitakin harvinaisia poikkeuksia. Jos esimerkiksi kyseinen määre on käytössä kyseisenlaisella elementillä, mutta sen mahdolliset arvot on rajattu DoX CMS.ssä, sallitaan myös muut arvot. Esimerkiksi huomioelementeille (note) on mahdollista antaa tyyppejä, joita DoX CMS:n valikko ei sisällä kuten vinkki (tip).
Verkkolevyn Jatkokehitys
Tämänhetkisessä muodossaan WebDav-verkkolevy ei ole vielä täysin kattava integraatioratkaisu. Esimerkiksi yllä esitetty tapa lisätä DoX CMS:n sisäiset tunnisteluokat on mahdollista automatisoida. Tämän toteuttaminen on kehityslistalla muutaman muun toiminnon lisäksi. Nämä työn alla olevat jatkokehityksen muodot selostetaan alla.
Lisämääreet on mahdollista hakea suoraan DITAVAL-tiedostosta, jollainen on mahdollista generoida yhtiönne DoX CMS:n instanssin senhetkisen tilan perusteella. Tämä tiedosto lisättäisiin osaksi WebDav-ympäristöä, jolloin sen voisi ladata suoraan oXygenin käyttöön ja päivityksien luokituksiin huomiointi olisi vain päivitetyn DITAVAL-tiedoston käyttöön ottamisesta kiinni. Yllä esitetty tapa tehdä tämä käsin on kuitenkin tarpeellista tietää toistaiseksi, jos käyttäjä haluaa käyttää editorinaan oXygen XML-editoria.
WebDav-verkkolevy ei toistaiseksi myöskään sisällä yhtiönne DoX CMS:n instanssin liitetiedostoja. Tästä syystä ulkoinen editori ei löydä niitä osaksi esikatselunäkymäänsä. Tämä asiantila tullaan korjaamaan mahdollisimman pian ja sen tulisi olla yksinkertainen muutos.
Jos käyttäjät kohtaavat muita yhteensopivuuteen liittyviä haasteita, tullaan niihin vastaamaan. Ottakaa näissä tilanteissa yhteyttä tukeemme asian selvittämiseksi.