Modulfejlesztés: Saját modul létrehozása

Hozzuk létre a modul könyvtárát

A Modulfejlesztés: Kezdeti lépések elolvasása után, egy feltelepített Xaraya „modules” könyvtárában hozzuk létre a saját modulunk könyvtárát a modul regisztrált nevével. A könyvtár legyen csupa kisbetű.

Másoljuk le az „example” modult

Az „example” modul könyvtárából másoljuk át az összes fájlt a saját modulunk könyvtárába (használjuk a modul legfrissebb változatát a letöltésekből vagy a Monotone forrásfából. Ez létrehozza a Xaraya modulokhoz alapvetően szükséges fájlokat, amelyekből nagyon könnyen kiindulhatunk.

Adjuk meg a modul definícióját

A „xarversion.php” fájlban frissítsük a modul nevét, leírását, adjuk meg a szerzőt, a modul regisztrált azonosítószámát és egy kellően alacsony verziószámot 3 digites formában, mint például: 0.0.1.

Programozzuk le az adatbázis táblákat

Az adatbázis táblákat a „xartables.php” fájlban határozhatjuk meg. Ez a fájl definiálja a modul által használt táblák struktúráját, de nem végez el semmilyen műveletet. A struktúra információ egy modulnév_xartables() függvénybe van beágyazva, amelyet így a Xaraya alaprendszer könnyen elérhet.

Ha a modulnak nincs szüksége adatbázisra, vagy más modul által már létrehozott táblákat használ, akkor a „xartables.php” fájlt törölhetjük, vagy a megfelelően elnevezett függvényből visszaadhatunk egy üres tömböt.

Ha olyan táblákat próbálunk meg definiálni, amelyet már más modulok vagy a Xaraya alaprendszer használ, a modulunk kiszámíthatatlan hibákra fog futni. A tábláknak adjunk egyedi nevet, lehetőleg a modul saját nevét alapul véve.

Írjuk meg az inicializálási funkciókat

A modul inicializáló függvények három csoportra oszthatóak:

• A modul telepítése, adatbázistáblák és konfigurációs változók létrehozása.
• A modul frissítése egy régebbi telepített verzióról.
• A modul törlése, adatainak és konfigurációs változóinak eltávolítása.

Ezek a funkciók tipikusan csak egyszer kerülnek meghívásra, de biztosítani kell a lehetőséget, hogy egy adminisztrátor tetszőlegesen telepíthesse és törölhesse a modult ahányszor kívánja.

Feltételezhetjük, hogy amikor a Xaraya rendszer ezeket a függvényeinket meghívja, a „xartables.php”-ben definiált adatbázis struktúra információk már elérhetőek a xarDBGetTables() függvényen keresztül.

Minden inicializálási fügvény a „xarinit.php” fájlba kerül. Az „example” modul fájljában találhatunk példákat a táblák létrehozására, jogosultsági maszkok definiálásra, új változatra való frissítésre, eltávolításra és a konfigurációs változók regisztrálására.

Teszteljük az inicializálási funkciókat

Amikor készen vagyunk az adatbázis struktúrákkal és az inicializálási rutinokkal, ezket a Modulok nevű modulból próbálhatjuk ki. Itt telepíthetjük majd eltávolíthatjuk a modult. Ellenőrizzük, hogy a szükséges táblák megfelelően jönnek e létre, és, hogy a modul eltávolítása minden ide vonatkozó táblát és konfigurációs változót töröl.

Ha mindent rendben találtunk, még egyszer telepítsük a modult, hogy rendelkezésre álljanak a szükséges adatbázis táblák a modul fejlesztéséhez.

Írjuk meg az adminisztrálási funkciókat

A modul telepítési rutinjai után elkezdhetjük megírni az adminisztrálási lehetőségeket. A szükséges funkciók modulról modulra változnak, de általában a modulok a következő általános lehetőségeket biztosítják:

• add új elem felvétele
• modify létező elem szerkesztése
• delete létező elem törlése

Minden funkciót általában három szintre bontunk szét. Az első a felhasználói felület (GUI) amely megjeleníti az adatbevitelhez szükséges űrlapokat (sablonfájlok). A második az API funkciók, amely az adatok - általában - adatbázisba való mentését vagy azok betöltését végzik. A harmadik a GUI-hoz tartozó üzleti logika, amely a GUI-ról beérkező adatokat továbbítja a megfelelő API hívásokhoz és továbbítja a visszakapott adatokat a GUI-hoz.

Nagyon fontos a GUI és API funkciók pontos szétválasztása. Ha bizonytalanok vagyunk, hogy egy funkció melyik területre tartozik, vizsgáljuk meg az elvégzett feladatot. Ha ez közvetlenül az adatok megjelenítésével vagy azok felhasználótól való bekérésével foglalkozik, ez egy GUI függvény. Ha az adatbázisból szerez be adatokat vagy az adatbázisban lévő adatok módosítását végzi, legyen API függvény.

A különböző jellegű feladatokat a Xaraya különböző könyvtárakba és fájlokba csoportosítja, így ezek feltétlenül élesen szétválnak. Vizsgáljuk meg az „example” modul „xaradmin” és „xaradminapi” könyvtárakban lévő fájljait.

Teszteljük az adminisztrálási funkciókat

Amikor készen vagyunk az adminisztrálási funkciók megírásával, alaposan próbáljuk ki azokat, és győződjünk meg róla, hogy az adatbázisba a megfelelő adatokat tárolja és tölti vissza.

Írjuk meg a felhasználói funkciókat

Amikor készen vannak az adatok kezelésére szolgáló adminisztrálási funkciók, elkészíthetjük azokat a programrészeket amelyek a bevitt adatokat a felhasználók számára megjelenítik. Hasonlóan az adminisztráláshoz, ezek is nagyban függnek a modul jellegétől, de a legtöbb modul tartalmaz:

• Áttekintő nézeteket az elérhető elemek listázáshoz
• Egy-egy elem adatainak részletes megjelenítését

A programnak ezt a részét is külön GUI és API rutinokra kell bontani, hasonlóan az adminisztráláshoz. Az „example” modulban található „xaruser” és „xaruserapi” fájljaiban mellékelt részletes leírások segíthetnek ennek elkészítésében.

Teszteljük a felhasználói funkciókat

Amikor készen vagyunk, alaposan teszteljük a felhasználó funkciókat, és győződjünk meg róla hogy az adatbázisban tárolt adatokat hibátlanul jelenítnik meg.

Írjuk meg a blokkjainkat

Szükség lehet arra, hogy a modulunkhoz blokkokat is készítsünk. A blokkok kisebb önálló egységek egy modulon belül, amelyek általában a weblapok szélén, tetején vagy alján, a tartalmi terület körül jelenítenek meg bizonyos információkat.

A blokkok nagyon egyszerű elemek, amelyek a modulok API függvényeit használják a megjelenítendő adatok beszerzésére. (A blokkok közvetlenül is tölthetnek be adatokat SQL parancsokkal, a xarModDBInfoLoad() függvényt használva a modul adatbázis tábláinak megkeresésére.)

Az „example” modulban elérhető „first.php” blokkban található leírás jó kiindulási alapot biztosíthat saját blokkok elkészítéséhez.

Teszteljük a blokkjainkat

A blokkok elkészítése után használjuk a Blokkok modul adminisztrálási felületét. hogy a blokk példányait elhelyezzük a weboldalon. Alaposan teszteljük, hogy a blokk a megfelelő adatokat jeleníti meg.

Dokumentáljuk a modulunkat

A modul dokumentálása létfontosságú. Minden modulhoz kétféle dokumentációra van szükség: felhasználói és API dokumentáció. A felhasználói dokumentációt a modul Áttekintés oldalán tehetjük elérhetővé, bővebb leírást pedig külön mellékelt dokumentációban. A modulok áttekintés oldala főként a modul adminisztrátorainak szól, amelyet az „admin-main.xd” fájlba írhatunk. Az elkészült leírást beküldhetjük a Xaraya weblapjára is.

A második dokumentálandó területet a modul API függvényei jelentik, azok funkciója, paraméterei, visszatérési értékei stb. A Xaraya a PHPDoc dokumentálási stílust követi, amely a dokumentáció automatikus feldolgozását teszi lehetővé és a dokumentációt közvetlenül a programfájlokban tárolja, a dokumentált függvény mellett.

Példa egy függvény dokumentációjára, közvetlenül a függvény felett:

(A hordozhatóság kedvéért meghagyjuk az angol szöveget. A közösségi együttműködés érdekében fontos lehet a programot angolul dokumentálni, angol nyelvű változóneveket használni, amennyiben a fejlesztő tud angolul. -szerk.)

/**
* Short description of the function
*
* A somewhat longer description of the function which may be
* multiple lines, can contain examples.
*
* @author  Author Name <author@email>
* @deprec  date since deprecated <(only if function is deprecated)>
* @access  public / private / protected
* @param   type param1 Description of parameter 1
* @param   type param2 Description of parameter 2
* @return  type to return description
* @throws  list of exception identifiers which can be thrown
* @todo    <devname> <#> todolist for module (RFC, wish or otherwise)
*/

Az aktuálisan használt fejlécek dokumentációja az RFC 44-ben található.

A dokumentáció tartalmazza a függvény tömör és bővebb leírását, szerzőt, fogadott paraméterek típusát és leírását és további fontos információkat. A lehetőségek pontos leírása a PHPDocumentor oldalán található.

Terjesszük a modult

Mostanra a modul készen áll a csomagolásra és terjesztésre. Xaraya moduloknál a két általánosan használt tömörítési frorma .zip és a .tar.gz, ha van lehetőségünk, mindkét formátumban párhuzamosan terjesszük az új modult.

A Xaraya.com oldal bővítményeket nyilvántartó moduljában jelentsük be a modulunk új kiadását, a minél nagyobb publicitás érdekében.