Sablon:Kembox/Fejlesztői dokumentáció

Ez a szócikk a kémiai sablonok egységesítésének technikai részleteit írja le.

Kémiai sablonok:

• {{Chembox_new}}^(?)
• {{Chembox_új}}^(?)
• {{Vegyület_infobox}}^(?)
• {{Drugbox}}^(?)
• {{Drugbox_new}}^(?)
• {{Gyógyszeresdoboz}}^(?)

Az átalakítás első lépése a Chembox_new és Drugbox sablon összes paraméterének részletes dokumentációja volt. A dokumentálás eredménye egy összefoglaló táblázat, mely egymáshoz rendeli a sablonok azonos adatait, feltüntetve a sablononként különböző neveket. Ez a táblázat lett a legfontosabb információ a programozás során.

A második lépés az adatcsoportok sablonjainak átírása lua-modulokba. Az adatcsoport a Chembox-beli alsablonokkal azonos, de a lua-beli megvalósítás képessé tette a többi modul azonos tartalmú adatainak feldolgozására is. Más szóval: az alsablonok átírása almodulokká a két Chembox-sablon kivételével teljesítette az egységesítés követelményeit.

Ahhoz, hogy a két Chembox-sablonban is egységes legyen a paraméterek kezelése, azokat az alsablonokból át kellett csempészni a fő sablonba, és ott feldolgozni őket. Ez a harmadik lépés.

A negyedik lépés az infóboxok megjelenésének egységesítése.

Második lépés

A második lépés az adatcsoportok feldolgozása luában. A sablonhoz képest a legfontosabb eltérés a tartalmi és formai elemek teljes szétválasztása.

Az almodulok működése

Az alsablon-modul (röviden: almodul) két fő lépése:

1. egy lua-táblázat előállítása, mely a paraméter címkéjét és értékét tartalmazza, de nem tartalmaz semmilyen formázást (kivéve a HTML-betűformázást, pl. dőlt betűt).
2. formázás, vagyis a fenti lua-táblázat stringgé (wikitext táblázat-sorrá) alakítása. A konverzió paramétere a hívó kémiai infóbox neve. A konverter modul az infóboxtól függően többféle formát (pl. háttérszín) képes előállítani.

Az almodulok egyúttal megoldják a Drugbox, Drugbox_new, Gyógyszeresdoboz és Vegyület_infobox sablon átkódolását luába. Pl. a Drugbox sablon ilyen lett:

{| id="drugInfoBox" style="float: right; clear: right; margin: 0 0 0 0; background: #ffffff;" class="toccolours" border="0" cellpadding="0" align="right" width="280"
<includeonly>
{{#invoke:Kembox/Chembox_Images|Chembox_Images|infobox=Drugbox|Name={{PAGENAME}}}}
{{#invoke:kembox/Chembox Identifiers|Chembox_Identifiers|infobox=Drugbox}}
{{#invoke:kembox/Chembox Properties|Chembox_Properties|infobox=Drugbox}}
{{#invoke:kembox/Chembox_Structure|Chembox_Structure|infobox=Drugbox}}
{{#invoke:kembox/Chembox_Thermochemistry|Chembox_Thermochemistry|infobox={{{infobox|Drugbox}}}}}
{{#invoke:Kembox/Drugbox Farmakokinetika|Drugbox_Farmakokinetika|infobox=Drugbox}} 
{{#invoke:Kembox/Drugbox Terápia|Drugbox_Terapia|infobox=Drugbox}}
{{#invoke:kembox/Chembox_explosive|Chembox_explosive|infobox={{{infobox|Drugbox}}}}}
{{#invoke:kembox/Chembox_Hazards|Chembox_Hazards|infobox=Drugbox}}
{{#invoke:kembox/Chembox_Related|Chembox_Related|infobox={{{infobox|Drugbox}}}}}
</includeonly>
|}

Az alsablonokat végrehajtó modulok értik az összes infóbox-paramétert. Ütközés esetén az infobox modul-paramétertből döntik el, melyik jelentés az érvényes adott esetben. Ugyanezt a paramétert használja a formázó modul, a modul:Kembox/kozos.

A lua-modul hozzá tud férni az őt hívó sablon paramétereihez (melyek a szócikkből származnak), és azokat meg tudja különböztetni a sablontól kapott paraméterektől. Ez azt jelenti, hogy a sablon nem kell továbbadja a szócikkből kapott paramétereit a modulnak.

A fenti modulok funkcionálisan azonosak a Chembox sablonok alsablonjaival. Pl. a Chembox_Related alsablon ilyen lett:

<includeonly>{{#invoke:kembox/Chembox_Related|Chembox_Related|infobox={{{infobox|Chembox_new}}}}}</includeonly>

Paraméterátvétel a sablonból

Egy paraméter átvétele előtt:

1. A paraméterbeli helyközök átkódolása aláhúzássá. A Vegyület_infobox miatt kell.
2. A sablononként különböző paraméternevek (szinonimák) átkódolása egységes névre. A szinonima-neveket a szintbl nevű asszociatív tömb tartalmazza. Egységes névnek a Chembox_new-belit vettük, ha ott van ilyen; ha nincs, valamelyik másik infobox-ból választott név. A modul a továbbiakban ezt tekinti a sablonból kapott paraméter nevének.

Előfordul, hogy egy infobox-beli adat több sablonparaméterből áll. Pl: az olvadáspont három paraméterből állhat: alsó érték, felső érték, megjegyzés. Ilyenkor a paraméter feldolgozásához két menet szükséges.

Az almodulok négy menetben dolgozzák fel a szócikkből kapott, és a fenti két lépéssel előkészített paramétereket:

1. Az első menet végigjárja a kapott paramétereket. Az egy menetben feldolgozhatókat azonnal a munka táblába írja (az infóbox-beli sorrendet megadó sorszámot a boxtbl táblából veszi). Azok a infobox-sorok, amelyek több paramétertől függenek, az utotbl táblába kerülnek.
2. A második menet az utotbl táblába került paramétereket is beleteszi a munka táblába.
3. A harmadik menet a munka táblát sorbarendezi (a sorrendet maga a tábla már tartalmazza), hogy az infoboxbeli sorrend ne függjön a paraméterek sorrendjétől. Az adatokat sorrendben átmásolja az eredm táblába, és az immár szükségtelen sorrendet elhagyja. A tábla az adatcsoport minden infobox-ba kerülő adatát tartalmazza, de vizuális információk nélkül. A lépés minden almodulban azonos, ezért a kembox/kozos modulbeli p.adatcsoport eljárás hajtja végre.
4. A negyedik menet állítja elő az infobox wiki-szövegét, immár az infobox-tól függő formázással együtt. A lépés minden almodulban azonos, ezért a kembox/kozos modulbeli p.kiir eljárás hajtja végre.

Az első menetet az egysor, a másodikat a menet2 eljárás hajtja végre. Az eljárásnév azonos mindegyik almodulban, de a kód különböző.

A modulok kiterjedten használják a lua-táblázat lehetőségeit, elsősorban az asszociatív tömböt, ezzel adatszerkezetté alakítva sok ciklust.

A munka tábla alakja:

{ { sorsz, címke }, string }
{ { sorsz, típus }, { érték1, érték2 } }

• sorsz: szám, az adat alcsoporton belüli helye (sorszáma)
• címke: string, az adatcsoport címkéje. Az érték string típusú.
• típus: szám, az infobox különleges sorait adja meg (pl. összecsukható, kétoszlopos, egy vagy két kép, stb.). Az egy vagy két érték típusa a sor típusától függ.

Az eredm tábla alakja:

{ címke, érték1, érték2, érték3 }
fejléc

A fejléc string: az adatcsoport fejléce. A többi azonos a munka-belivel a sorszám elhagyásával. A tábla a kiírás sorrendjében rendezett.

Chembox sablonok

A két Chembox sablon használata a szócikkekben

Chembox sablonokon a Chembox_new és Chembox_új sablont értjük.

A Chembox sablonok hívása:

{{Chembox_new
| Name = …
…
Section1 = {{Chembox Identifiers
     | CASNo = …
     …
     }}
Section2 = {{Chembox_Properties
     …
     }}
…
}}

…
Azonosítók
CAS-szám	[…]
Tulajdonságok
Kémiai képlet	…
Ha másként nem jelöljük, az adatok az anyag standardállapotára vonatkoznak. (25 °C, 100 kPa)

Az eredmény jobbra látható.

Vagyis a Chembox sablonnak vannak „saját”, és alsablonokban megadott alsablon-paraméterei.

Ezzel az a probléma, hogy bizonyos paraméterek megadhatók a fő- és alsablonban is, vagy két különböző alsablonban. Az ilyen paraméterek kétszer is megadhatók, akár különböző értékkel.

Hogy ez ne fordulhasson elő, a paramétereket egy helyen, a fő sablonban kell kezelni, azaz az alsablon-értékeket valahogyan át kell adni a fősablonnak. A másik cél az, hogy a használat módja ne változzék, azaz a szócikkeket ne kelljen átalakítani.

A korábbi Chembox sablonok működése

A fenti hívást a Chembox sablonok így fogadják:

{{#if:{{{Name|}}}|…}}
…
{{{Section1|}}}
{{{Section2|}}}
…

Vagyis a „saját” paramétereket a szokott módon dolgozzák fel, az alsablonok által visszaadott wiki nyelvű stringet pedig változtatás nélkül kiírják.

Mind a fő sablon, mind az alsablonok kiválogatják azokat a paramétereket, amelyeket értenek, és egy hosszú stringgé alakítják őket, melynek van egy alsablonra jellemző fejléce, és a sablon által felismert minden paraméter egy kétoszlopos Wiki-táblázat egy-egy sora lesz. A sor első oszlopa a címke (név), a második az érték. A sablon egyszerűen eldobja az általa nem ismert paramétereket.

Ha az alsablonok paramétereit a fő sablonban akarjuk kezelni, akkor,

• az alsablonokat megváltoztathatjuk úgy, hogy átalakítás nélkül adják vissza a paraméter = érték alakú paramétereket, mivel ezeket a sablonokat csak a Chembox-okon „belülről” hívják a szócikkek
• a paraméter nevéből (Sectionn ill. Szakaszn) lehet tudni, hogy az speciálisan kezelendő.

Most már csak a kétféle típusú/alakú paraméterek összefésülését kell megoldani. Ez luában nem probléma. Sőt, az is eldönthető, hogy a Sectionn átalakított-e vagy sem. Ennek az átállás alatt van jelentősége az átmeneti üzemzavar elkerülésében.

Alsablon-paraméterek feldolgozása a fősablonban

Az alsablonokat úgy kell átalakítani, hogy a nyers paraméterneveket és -értékeket adják vissza. Ezt a Chembox sablon/modul összefésüli a közvetlenül kapott paraméterekkel, és ezután dolgozza fel őket.

Mint korábban is említettük, valamennyi alsablon, köztük a fent már idézett Chembox_Related azonos lett:

<includeonly>{{#invoke:Kembox/kozos|alsablon}}</includeonly>

A sablonok által hívott függvény (Kembox/kozos modul):

function p.alsablon(frame)
    str = ''
    for n,v in frame:getParent():argumentPairs()
    do   str = str..n..'='..v..'\0'
    end
return str
end

Ez a név=érték\0 string kerül a Chembox sablon Sectionn változójába.

A kembox/Chembox_new modul asszociatív tömbben tárolja a speciális paramétereket, valamint az alsablon-funkciókat betöltő modulokat:

   local alsabtip = {   -- alsablonból jövő paraméterek
       Section1  = true,  Szakasz1  = true,
       Section2  = true,  Szakasz2  = true,
       …
       Section15 = true,  Szakasz15 = true,
   }

(Sectionn és Szakaszn szinonimák: előbbit Chembox_new, utóbbit Chembox_új használja.)

Összefésüléskor a Chembox sablonból és a fenti módon megváltoztatott alsablonokból kapott paraméterek a partbl nevű asszociatív tömbbe, míg az át nem alakított alsablonokból kapott paraméterek a regi stringbe kerülnek:

    local partbl = {}                                          -- átírt alsablonokból és a fő sablonból kapott paraméterek
    local regi = ''                                            -- át nem írt alsablonból kapott paraméterek
    for nev,ertek in szulo:argumentPairs()
    do    v = string.gsub(ertek,string.char(239,191,189),'\0') -- a modulhívás átkonvertálja \0-t a 239,191,189 karaktersorozatra. Visszacsináljuk.
          if alsabtip[nev]
          then         -- alsablonból jöhető paraméter
                if string.find(v,'\0',1,plain) ~= nil
                then   alsabfv(v)                              -- vannak benne \0-k: tényleg alsablonból jött
                else   regi = regi..'\n'..v                    -- át nem írt alsablonból jött
                end
          else         -- fősablon paraméter
                partbl[nev] = v
          end
    end

Az alsablon függvény a parnév=érték\0 alakú stringeket beteszi a partbl táblába.

Az almoduloknak két belépési pontjuk van. Az egyik, fent már említett a sablonok, míg a lua nevű a modulok számára. Mindkettő ugyanazt csinálja, csak a paraméterük más. Ezáltal ugyanaz a kód hajtódik végre, akárhonnan jön a paraméter. A fent összefésült paraméterek stringgé alakítása:

    local modlista = {     -- modulnév, függvénynév
        ['module:Kembox/Chembox_Images']          = 'Chembox_Images',
        ['module:kembox/Chembox_Identifiers']     = 'Chembox_Identifiers',
        …
        ['module:kembox/Chembox_Related']         = 'Chembox_Related',
    }
  
    local hivo  = frame.args['infobox']   -- hívó sablon
    local str = ''
    for nev, v in pairs(modlista)
    do    kozos = require(nev)
          str = str..kozos.lua(partbl,hivo)
    end
    return str..regi

(A modlista tábla értékeit nem használjuk semmire, csak azért kellenek, hogy a tömb asszociatív legyen.)

Harmadik lépés

Sablonnevek

A két Chembox sablon az átalakítás után három változatban létezik. A változatot az eredeti helyen átirányítás választja ki.

• {{Chembox_new}}^(?), {{Chembox_új}}^(?): átirányítás valamelyik alábbi változatra
• {{Kembox/Chembox_new}}^(?), {{Kembox/Chembox_új}}^(?): nagyon luás, végleges(nek szánt) sablonváltozat
• {{Chembox/Kembox_new}}, {{Chembox/Kembox_új}}: kicsit luás sablonváltozat (az alsablonok luásak, a fősablon nem)
• {{Chembox/Chembox_new}}, {{Chembox/Chembox_új}}: az átalakítás előtti, nem-luás változat.

Az alsablonok esetén csak kicsit luás változat létezik, mert a két Chembox sablon a nagyon luás átalakítás után már nem is hívja őket, csak a nekik megfelelő lua-modulokat. A nagyon luás változatban minden alsablon tartalma azonos (lásd alább). Például a Chembox_Identifiers korábbi változatai:

• {{Chembox_Identifiers}}^(?) átirányítás valamelyik alábbi változatra
• {{Kembox/Chembox Identifiers}}^(?): kicsit luás változat
• {{Chembox/Chembox Identifiers}}^(?): eredeti, wiki sablonos változat

A fő- és alsablonok ugyanabban a változatban kell legyenek a fenti háromból. Egy esetleges visszaálláskor azt is figyelembe kell venni, hogy elveszítjük az újabb változat többlet-lehetőségeit.

A jelenlegi sablonok archíválása

Egységes tartalomra módosítandó alsablonok

Chembox new	Chembox új
{{Chembox Identifiers}}(?)	{{Chembox Azonosítók}}(?)
{{Chembox_Properties}}(?)	{{Chembox_Tulajdonságok}}(?)
{{Chembox_Structure}}(?)	{{Chembox_Szerkezet}}(?)
{{Chembox_Thermochemistry}}(?)	{{Chembox_Termokémia}}(?)
{{Chembox_Pharmacology}}(?)
{{Chembox_Explosive}}(?)	{{Chembox_Robbanó}}(?)
{{Chembox_Hazards}}(?)	{{Chembox_Veszély}}(?)
{{Chembox_Related}}(?)	{{Chembox_Rokon}}(?)

• {{Chembox_new}}^(?) → {{Chembox/Kembox_new}}
• {{Chembox_új}}^(?) → {{Chembox/Kembox_új}}

Chembox/chembox az eredeti wiki-sablon. Kembox/chembox-ban a képek luásak (az alsablonok is, de az mindegy).

Az alsablonok eddig átirányítások voltak a luába átírt alsablonra. Most egységesen ez lesz a tartalmuk:

<includeonly>{{#invoke:Kembox/kozos|alsablon}}</includeonly>

A hívott függvény semmi mást nem tesz, mint visszaadja a kapott paramétereket lua-string formában a Chembox_new ill. Chembox_új sablon Sectionn paraméterében, amit module:Kembox/Chembox vesz át, és beilleszti a többi paraméter közé. Ettől kezdve már mindegy, hogy a paramétert közvetlenül a sablonból, vagy alsablonból kapta-e.

Áttérés

Először a két fősablont módosítjuk. Az alsablonok módosításának befejezéséig előfordulhat, hogy megváltozik az adatcsoportok sorrendje (pl. az azonosítók csoport az infóbox végére kerül).

A megjelenés egységesítése

Az összes kémiai sablonban nagyjából azonos adatok vannak, csak a paraméternevek különbözők. Az alsablonok értik a paraméterneveket: bármelyik régi alsablonbelit használhatjuk. Vagyis az első két lépés gondoskodott a paraméterek egységes kezeléséről mindegyik kémiai sablonban.

Mind az almodulok, mind a két Chembox modul a kembox/kozos modullal írják ki a lua-táblázatba gyűjtött paramétereiket. A modulnak átadják az almodult hívó sablon nevét, hogy a lua-táblázat wikiszöveggé alakításakor ennek megfelelő legyen a formázás.

Az átalakítás harmadik lépése a formai egységesítés. A kembox/kozos modulból egyszerűen törölni kell a sokféle formázást, és csak egyet kell megtartani. Ezzel mind a hat kémiai sablon vizuálisan ugyanolyan formájú lesz a szócikkben.

Az eredeti sablonokban van egy-egy paraméterütközés, ezért azok nem törölhetők le teljesen, viszont a két Chembox sablon által hívott rengeteg alsablon igen.

Az átalakítás eredményeképpen az angol Wikiből változtatás nélkül vehetjük át akár a Chembox_new, akár a Drugbox sablont. A meglevő szócikkeken sem kell változtatni, és akár a régi sablonokat is lehet tovább használni. Az új sablonok, ill. a mögöttük levő lua-modulok a sokféle bemenetből egységes tartalú és formájú kimenetet produkálnak.