Az új Drupal stabil kiadásához közeledve hasznos lehet, ha az ember újragondolja, átnézi a fejlesztéseit, hiszen a legtöbb esetben mindenképpen módosítani kell az általa kifejlesztett, egyedi funkcionalítást adó modulon, hogy használható legyen a Drupal 6 alatt is. Ilyenkor nagy segítséget jelent az api.drupal.org, ahol könnyen lehet keresni a használható függvények között, megnézni a paraméterezését, vagy a működését.
Viszont nem mindenkinek áll a rendelkezésére az Internet, mint ahogy jómagam is ebben a helyzetben voltam évekig, így szeretném bemutatni az ilyenkor használható hűséges segítőtársamat: az API modult, amelyet teljesen offline működésre fogunk bírni.
A megoldást Linux operációs rendszer alatt teszteltem, és ott is használom, így azokról az esetleges eltérésekről, amelyek a Microsoft Windows alatt jelentkezhetnek (pl. a fájlrendszer elérése), nem tudok nyilatkozni.
Amire szükségünk lesz:
- Egy feltelepített Drupal rendszerre, mivel erről a kézikönyv is hosszasan ír, ezért inkább itt nem taglalnám
- Az API modulra, ugyan a modul nem rendelkezik még magyar fordítással, de enélkül is könnyen érthető a felülete
- Kell még a PHP függvények rövid leírása, amelyet itt fogunk megtalálni, mentsük le funcsummary.txt néven (a download linkre kell kattintani)
- A minél teljesebb dokumentációhoz szükséges még néhány dokumentáció (pl. Form API), és egyéb példakódok, ezeket a következő paranccsal tudjuk kinyerni a Drupal tárolóból:
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-5 contributions/docs/developer
- Végül pedig szükséges még a PHP dokumentáció, itt fontos, hogy a több fájlból álló változatot válasszuk, amely innen tölthető le magyar nyelven.
Ha ezek megvannak, akkor minden szükséges dolgot letöltöttünk, vigyük haza, és lássunk munkához!
Először is, a webszerver által használt gyökérkönyvtárban hozzunk létre egy alkönyvtárat phpdoc néven, és oda tömörítsük ki a PHP dokumentációt, majd ebben a könyvtárban hozzunk létre egy fájlt .htaccess névvel, amelynek a tartalma legyen a következő:
<IfModule mod_rewrite.c> RewriteEngine on RewriteBase /phpdoc/html RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} ^(.*)_(.*)$ RewriteRule ^(.*)_(.*)$ $1-$2 RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^([0-9A-Za-z\-]*)$ function.$1.html [L] </IfModule>
Ezzel elértük azt, hogy a http://localhost/phpdoc/html/is_array címen megjelenik az is_array PHP függvény leírása, ez amúgy többféle módon is megoldható, érdemes elolvasni a Weblabor kapcsolódó cikkét. Szintén ebbe a phpdoc könyvtárba másoljuk be a korábban lementett funcsummary.txt állományt.
Az api modul bekapcsolása után az adminisztrációs oldal "webhely beállítása" részében megjelent egy új menüpont "API reference" néven, itt tudjuk a modul működését szabályozni.
Az első megadandó dolog a "Short name", ezt majd a címek generálásakor használja a Drupal, így nem tartalmazhat szóközt, vagy olyan karaktert, amely nem megengedett az internet-címekben.
A következő a "Long name", ez lesz a blokk látható neve, fontos szerepe van akkor, ha egyszerre több Drupal dokumentációját, mondjuk a stabil és a fejlesztői változatét kívánjuk elkészíteni.
A "Directory name" helyen kell megadnunk az indexelni kívánt Drupal abszolút elérési útvonalát, akár egyszerre többet is, kettősponttal elválasztva.
A "Maximun files to scan per cron run" helyen állíthatjuk be, hogy az időzített feladatok futása közben egy-egy alkalommal hány fájlt dolgozzon fel. Ezt érdemes az alapértelmezett 10 értéken hagyni, így nem futnak ki folyamatok az engedélyezett időből.
A "Save changes" gombra kattintva elmenthetjük az itt megadott adatokat, így lehetőség nyílik másik telepítés leindexelésére is, majd ha többet is beállítottunk, a "Default branch" rádiógomb alatt lehetséges az alapértelmezettet kiválasztani. Fontos, hogy miután megjelent a "Changes saved." felirat, akkor mégegyszer nyomjuk meg ezt a gombot, mert ekkor menti el a "Default branch" tartalmát, ennek hiánya esetlegesen galibát okozhat.
A "PHP Manual" résznél az első helyre írjuk be a funcsummary.txt elérési helyét: http://localhost/phpdoc/html/funcsummary.txt
A második résznél pedig megadhatjuk PHP dokumentáció helyét a gépünkön, a "!function" karaktersorozattal kiegészítve (ide kerül majd a függvény neve), tehát:
http://localhost/phpdoc/html/!function
Majd ha ezek megvannak, kattintás az "Index PHP manual pages" gombra, és egy kis várakozás. Ha végzett, és mindent helyesen állítottunk be, akkor a "Reindex" gombra kattintva megkezdődik a megadott Drupal rendszerek forrásának feldolgozása.
Most nincs más dolgunk, mint szorgosan futtatni az időzített feladatokat, akár böngészőből:
http://localhost/ahol_van_az_oldalunk/cron.php
,
akár konzolból a
wget -O - -q http://localhost/ahol_van_az_oldalunk/cron.php
parancsot futtatva.
Annyiszor kell ezt végrehajtani, amíg a hozzáférési naplóban az api modulhoz tartozóan a "Parsing" kezdetű üzenetek el nem fogynak.
Ezek után már csak egy lépés választ el minket a sikertől:
Az adminisztrációs oldal "Blokkok" részében kapcsoljuk be az "API navigation" és az "API search" blokkokat, majd a főoldalra lépve legyünk boldogok, és válljék egészségünkre a gépünkön üzemelő Drupal API dokumentációs rendszer.
Frissítve (2010.06.08):
Drupal 6 hoz a következő CVS paranccsal lehet kinyerni a dokumentációt:
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 contributions/docs/developer
Hozzászólások
Köszi
Nagyon jó írás! Mindig tanul valami újat az ember.
harmadik oldal
Szóval ez az a bizonyos "harmadik oldal", amelyet itt említettem.
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
php.ini bejegyzés
Létezik egy idevágó php.ini beállítás.
Nevezetesen a
A PHP hibaüzenetekben linkeké alakulnak a függvénynevek.
A cikkben leírtak kipróbálása közben, támadt egy nagyszerű ötletem. :-D
Mely így hangzik: ...
és mi az?
És mi az a nagyszerű ötlet?
Amúgy köszönöm, hogy leírtad, ezt az opciót nem ismertem. :)
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
Drupal API és PHP referencia egy helyen
...
A jobb fajta, programozásra tervezett szövegszerkesztők tudják kezelni a külső *.chm, vagy *.html formátumban elérhető referenciákat. De a függvény leírást csak egy helyről próbálja meg elérni a szövegszerkesztő.
Tehát nincsen az, hogy ha nem sikerült elérni a leírást a http://localhost/phpdoc/html/function.hook_menu.html oldalon, akkor megpróbálja a http://localhost/ahol_van_az_oldalunk/api/function/hook_menu oldalon.
A megoldást abban láttam, hogy az API modult futtató Drupal példányba bele kell integrálni a PHP kézikönyvet, az API Merger modul segítségével.
Ehhez szintén szükség lesz a PHP kézikönyv egy helyi másolatára. (Bár próbáltam úgy megírni a modult, hogy működjön online is, de nem jött össze.)
A modul bekapcsolása után ellátogatni az admin/settings/apimerger oldalra.
A "PHP manual location" mezőbe ez kerüljön: http://localhost/phpdoc/html/ (a cikk alapján)
beállítások mentése
Továbbá az igazi API modul beállítsain is változtatni kell.
admin/settings/api
A "PHP Manual" részhez tartozik 2 db szövegmező. Az első marad változatlan. De a második
http://localhost/ahol_van_az_oldalunk/api/function/!function
Elvileg a
http://localhost/ahol_van_az_oldalunk/api/function/is_array
http://localhost/ahol_van_az_oldalunk/api/function/is-array
http://localhost/ahol_van_az_oldalunk/api/function/function.is-array.html
http://localhost/ahol_van_az_oldalunk/api/function/hook_menu
linkek is működni fognak.
különböző branch -ek
Még nem próbáltam ki az általad vázolt megoldást (ígéretesnek tűnik, bár jó lenne ismerni pár ilyen szövegszerkesztőt is), viszont érdemes lenne kipróbálni több Drupal branch dokumentálása esetén.
Ugyanis a node_load () függvény leírása a api/function/node_load/5 címen lesz elérhető, az utolsó perjel utáni érték (itt "5") az API modulban beállított "Short name" értéke. Ennek a szerepe az, hogy több különböző verziójú Drupal feldolgozása esetén meg tudja különböztetni az egyes verziókban szereplő azonos nevű függvényeket egymástól.
Na ezt szép barokkosan írtam le. :)
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
Több branch - kipróbáltam
Ha az admin/settings/api oldalon megadsz több Drupal verziót, akkor be lehet állítani, hogy melyik legyen a Default Branch:
Figyelni kell, mert alaphelyzetben egyik rádió gomb sincsen benyomva. Csak a választás után lehet elhagyni az URL végéről a "Short name" -et.
Amúgy az apimerger modul mellőz mindenféle hibakezelést, és az eredményt sem kell mutogatni a HTML validátoroknak. :)
(Windows felasználó vagyok)
Én jEdite-et használok. Az tud ilyet
Dev-PHP IDE is kezeli a *.chm fájlokat
Vannak olyan szövegszerkesztők amik saját maguk értelmezik a forrás fájlokban lévő dokumentációt, és gépelés közben egy kis ablakban feldobják a kurzor alatti függvénynévhez tartozó leírást. Ezek többnyire fizetős programok.
valóban
Valóban, amikor már lefeküdtem aludni, akkor jöttem rá, hogy a default branch lesz a megoldás, ahogy a leírásban is írtam. Csak ezért már nem akartam vissza felkelni. :)
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
nem rossz, de vannak vele gondok
Nem rossz az általad vázolt megoldás, most nyílt módom kipróbálni. Én egy branch -et indexeltettem le az api modullal, így ezért is lehetséges némelyik hiba.
Szóval a http://localhost/oldal_cime/api/function/is_array oldalra ellátogatva valóban bejön az is_array() függvény dokumentációja, viszont minden link, ami egyéb PHP függvényekre mutat (ilyen az előző/következő link is) már a "hagyományos" http://localhost/oldal_cime/api/function/function.fuggveny.html módot használja, ami kissé zavaró lehet (nem konvertálja át a címet).
A PHP függvények oldalán szereplő "fel" link sehova sem vezet, hibát dob:
Egy adott függvénynél pedig a "List references" gombra kattintva "Az oldal nem található" hibaüzenetet ad.
További probléma, hogy ha a http://localhost/oldal_cime/api/function/is_array jó helyre mutat, akkor pl. a http://localhost/oldal_cime/api/function/node_load már nem, hibaüzenet ad:
csak akkor mőködik jól, ha http://localhost/oldal_cime/api/function/node_load/5 címen használom, vagyis a link végén ott van a "Short name" értéke. Ez a modul használata előtt teljesen jól működött, vagyis a "Short name" nélkül írt cím valóban a "default branch" adott függvényére vezetett.
Végül pedig a modulnak bár van adminisztrációs oldala, de nem helyezi el magát a menüben semmilyen módon, így csak a pontos link ismeretében lehet eljutni oda.
Mindenezek ellenére egy roppant hasznos és segítőkész modul, szeretném kérni a továbbfejlesztését. :)
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
Doxygen
Végigolvasva a leírást, nem biztos, hogy mindenkinek érthető az, hogy milyen módon készül el a dokumentáció, hiszen a Drupal maga nem tartalmaz olyan különálló szöveges állományokat, melyek ezeket a leírásokat tartalmaznák.
Nos a Drupal forráskódja "öndokumentálóan" készül, a Doxygen rendszer segítségével. Ez a segédprogram képes arra, hogy a forráskódban elhelyezett speciális megjegyzéseket értelmezze, és abból elkészítse az adott programrész leírását.
Ez a nagy varázslat! :)
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
phpDocumentor
A jó fejlesztői dokumentációnak az alapja a megfelelően kommentezett kód.
Én a phpDocumentort szeretem használni, pláne akkor ha egy ismeretlen kóddal ismerkedem. A forrásokat egy könyvtárba rakom, majd rászabadítom a "kicsikét", aminek az eredménye, hogy kapok egy sorszámozott keresztbe-kasul összelinkelt webes dokumentációt, így nem kell megnyitni az összes forrást, hogy követni tudjam az egyes függvények vagy osztályok implementációját.
Webappz - http://webappz.hu
Páldi Zoltán
ez most mitől "új"?
Ez most mitől kapott "új" jelzést, és került a tracker elejére?
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés
frissítünk pár dolgot
Frissítünk pár dolgot :)
Drupal 6
Drupal 6 hoz a következő CVS paranccsal lehet kinyerni a dokumentációt:
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 contributions/docs/developer
Választ szeretnél? - Új kérdés, új téma - Tesztoldal - Trollkezelés - Frissítés