Předpokladem pro vývoj modulů pod Eclipse je nainstalovaný Eclipse s podporou vývoje Java EE aplikací
(např. Eclipse IDE for Java EE Developers). Celý tento návod platí pro situaci, kdy Eclipse i OpenCms jsou spuštěny na stejném stroji (tj. na localhost).
Přístup do VFS přes WebDAV (pro OpenCms 7)
Hodí se pro úpravy pod /sites/ adresářem ve VFS, který není přístupný formou modulu. Implicitně je WebDAV na OpenCms 7 zapnut, detaily pro přístup z Eclipse na http://opencms-wiki.org/WebDAV_access_to_the_OpenCms_VFS#Eclipse_WebDAV_plugin.
Stručná rekapitulace:
- z Eclipse 3.1 update site nainstalovat Eclipse FTP and WebDAV Support
- otevřít View "Target management - sites explorer", vytvořit nový WebDAV target namířený na URL OpenCms webdav servletu (např.
http://localhost:8080/opencms7/webdav/)
- na adresáři v projektu "Import" > source Other > vybrat vytvořený WebDAV target -- chvíli načítá VFS, pak ukáže strom co vše chceme importovat
- možno buď vzít některý vhodný adresář existujícího projektu, nebo vytvořit samostatný projekt pouze pro "front end" stránky z VFS
- po lokálních úpravách nutno udělat Export s podobnou procedurou jako při importu (ukazuje ikonkami u resources směr, který doporučuje pro synchronizaci)
Opencms Module Developer Eclipse plugin
Opencms moduly lze vyvíjet v Eclipsu pomocí pluginu Opencms Module Developer. Odkaz na jeho stažení a video tutorial, který vám pomůže s jeho nastavením a používáním najdete na Opencms-Wiki (!!!Pozor, nespleťte si jej s pluginem laughingpanda). Video tutorial si před dalším pokračováním projděte. Výhodou pluginu je, že pomocí kontextového menu je možnost editovaný obsah modulu do opencms nejen nakopírovat, ale rovnou i publikovat, což ušetří spoustu času.
Jeho nevýhodou je však nemožnost editace obsahových stránek mimo modul na frontendu, které mohou být uloženy ve VFS v podadresáři /sites/. K jejich editaci využijeme synchronizaci obsahu Opencms.
Nastavení synchronizace
- V opencms workplace se přepněte do
Administration view => Workplace Tools => Synchronization settings.
- Zaškrtněte políčko Enabled
- Jako Target folder zadejte adresář z RFS např.
C:\opencms_vfs
- Jako Resource vyberte adresář z VFS např.
/sites/default/test/
- Potvrďte a na horní liště Opencms Workplace stiskněte Reload.
- Na liště už se nyní objevila i možnost Synchronize folder - její stisknutí sesynchronizuje obsah mezi adresáři z RFS a VFS.
Eclipse projekt na synchronizovanou složku
- Vytvořte nový Dynamic Web projekt
File => New => Projekt => Dynamic Web Projekt
- V průvodci vytvoření nového projektu odškrtněte v části Project Contents políčko use default a Directory nastavte na synchronizovaný adresář z RFS.
- Nyní je třeba k vytvořenému projektu přiřadit knihovny z Opencms Properties projektu => Java Build Path => Libraries => Add External Jars
- Potřebné knihovny se nachází v
{TOMCAT_HOME}/webapps/opencms/WEB-INF/lib/ a jsou to opencms.jar popř. knihovny pro práci s JSTL jstl.jar a standard.jar.
- Nyní pokud změníme obsah v Eclipsu a změny uložíme, po stisknutí Synchronize folder se obsah překopíruje i do Opencms.
- !!! Sesynchronizovaný obsah je třeba v Opencms workplace publikovat.
Vývoj .java tříd pro Opencms pomocí eclipsu
- Vytvořte nový Dynamic Web projekt
File => New => Projekt => Dynamic Web Projekt
- Přiřaďte projektu opencms knihovny stejným způsobem popsaným v předchozím odstavci. (Nyní stačí pouze
opencms.jar)
- Nyní si vytvořte v projektu java package se třídou uvnitř.
- Java třídu zakomponujeme do Opencms modulu tak, že .jar archive s přeloženým balíkem umístíme ve VFS do
/system/modules/{MUJ_MODUL}/lib/ (viz návod?). V Eclipsu tedy bude stačit exportovat java package do podadresáře /lib/ adresáře modulu v RFS, na který máme napojený Eclipse Opencms Module Developer projekt.
- Před exportem do .jar je třeba provést Build editovaného projektu.
Export java package => Java - JAR File => Zaškrnout políčko v src {JMENO_PACKAGE} u Projektu s Java třídami => Export Path nastavte např. na {ECLIPSE_PROJECT_PATH}/lib/{JMENO_PACKAGE}.jar, kde {ECLIPSE_PROJECT} je právě projekt, který editujem pomocí Opencms Module Developeru.
- Podle tutoriálu z části Opencms Module Developer nyní překopírujem (i s publikací)
{ECLIPSE_PROJECT} do Opencms VFS.
- Aby se změny v Java třídě projevily, je třeba ještě restartovat opencms aplikaci na tomcatu.
Editace resource bundles (pro lokalizační řetězce)
Doporučuji použít ResourceBundle editor plugin, který vytvoří paralelní editační pole pro každou jazykovou variantu - properties soubor je jen potřeba otevřít přes Open With... -> ResourceBundle Editor
Debuging
V OpenCMS zapomeňte na postupy typu die("hokus"); a podobné. Získat z OpenCMS nějakou rozumnou odezvu ve chvíli kdy něco nefunguje je téměř nemožné. Naštěstí je díky vývojovému prostředí Eclipse možné zdrojový kód krokovat a sledovat hodnoty jednotlivých proměnných. Návod lze nalézt na wiki OpenCMS, ale pro jistotu ho zde přepíši.
- Nejdříve je potřeba spustit Tomcat s podporou JPDA. Toho dosáhnete tak, že spustíte script catalina.bat (windows), nebo catalina.sh (unix) s parametrem jpda. Výsledný kód, který musím napsat do příkazové řádky by tedy na linuxu mohl vypadat:
./bin/catalina.sh jpda start . Díky tomuto je možné se na tomcat vzdáleně připojit a tahat z něho informace potřebné k debugování. K Jetty se dá také vzdáleně připojit. Stačí spustit s parametry java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 -jar start.jar
- Otevřete si eclipse a zvolte
run -> debug configurations... -> remote java application -> pravoklik -> new.
- Zvolte si název
- Jako projekt vyberte ten, který chcete debugovat (absolventi, fav modul, ...)
- Connection type: Standard (Socket Attach)
- Host: localhost, Port: 8000
- Vše potvrďte, zavřete. Kamkoliv do *.java souborů v eclipse umístěte breakpoint. V eclipse si v hlavním menu rozklikněte ikonku broučka a zvolte vámi vytvořený debug běh.
- Nyní se již stačí pouze na webu doklikat ke stránce, která spustí daný kód. A v místě breakpointu se běh programu pozastaví. Takže pokud vidíte na webu pouze bílou stránku je pravděpodobné že jste se zastavili na nějakém breakpointu ;)
Poznámky k debugování
Stejně jako vše s těmito technologiemi, ani toto není stoprocentní. Pokud vám eclipse vrátí hlášku connection refused je možné že budete muset nastavit port / host / něco jiného přímo v souboru catalina.sh / catalina.bat. Nebo že bude pouze stačit restartovat eclipse a tomcat.
Z principů OpenCMS je logické, že krokovat .java soubor lze pouze tehdy, pokud se jedná o odraz .class souboru, který je ve VFS. Nezapomeňte přitom, že v OpenCMS je nutné na tyto soubory aplikovat deploy a následně ještě obvykle i restartovat Tomcat.
Příklady
Nejprve následující modul naimportujte do opencms (Nahrajte soubor do RFS ${opencms_home}/WEB-INF/packages/modules/ a poté v opencms workplace Administration view => Module management => Import module from server).
Následující modul naimportujte jako databázi (Nahrajte soubor do RFS ${opencms_home}/WEB-INF/packages/ a v opencms workplace Administration view => Database Management => Import file from Server).
Pozn. Tento adresář bude synchronizován s adresářem v RFS.
Pro názornou ukázku si stáhněte následující Eclipse projekty. Stačí je do Eclipsu naimportovat.
Vývoj pro alternativní strukturu modulu
Tato struktura je udělaná tak, aby usnadnila práci při vývoji modulu. Není optimalizovaná na vytvoření jeho produkční podoby. Základní shrnutí:
- modul je v Subversion jako jeden top-level adresář,
- tento obsahuje jak zdrojové
src/.java soubory, tak pages/.jsp stránky
- a dále obsahuje přeložené třídý v
classes/.class podobě -- tj. nikoli jako lib/modulname.jar archiv
Při úpravách v Eclipse se proto snadno vytvoří aktuální .class soubory, ty se snadno přes OpenCms Eclipse plugin nahrají do OpenCms, otestuje se přes zároveň nahrané JSP stránky, a celý proces se zrychlí (protože se nemusí dělat mezikrok s vytvořením .jar, jeho vložením do projektu modulu, a teprve pak publikování do OpenCms).
Nevýhodou je, že když je modul odladěný na lokálním vávojářském stroji, je potřeba výsledné třídy zabalit do lib/modulname.jar archivu a odstranit je z classes/ adresáře, aby produkční verze modulu nezahltila systém množstvím malých .class souborů.
Cíle návodu
- vývoj opencms modulu v Eclipse
- vytvořit nový projekt v Eclipse pro vyvíjený modul
- propojit projekt s lokálně běžícím OpenCms pro testování
- propojit projekt s SVN úložištěm
Předpoklady
Celý tento návod platí pro situaci, kdy Eclipse i OpenCms jsou spuštěny na stejném stroji (tj. na localhost). Dokument vychází z verzí opencms 7.5 a Eclipse 3.4. Pro jiné verze SW by postup mohl být obdobný. Celý příklad se bude týkat vzorového modulu cz.zcu.kiv.produkty.
- funkční přístup do SVN webkiv
- struktura modulu v svn podobné té, která bude dále popsána
- nainstalované Eclipse IDE s podporou J2EE? (např. Eclipse IDE for Java EE Developers)
- zprovozněné testovací prostředí OpenCms
- nahrané do opencms potřebné moduly z webkiv kolekce (také moduly, na kterých závisí náš modul)
- nahraný poslední build modulu, který budem vyvíjet, do opencms (pokud nevytváříme úplně nový modul)
Předpokládaná struktura modulu v SVN
Následující struktura SVN mi připadá přehlednější a dovoluje vytvořit projekt modulu s propojením na opencms i svn.
./produkty/trunk - odehrává se zde hlavní vývoj modulu a obsahuje adresáře
- build - vyexportované, funkční buildy modulu cz.zcu.kiv.produkty z opencms, vhodné hlavně pro testování dalšími lidmi
- frontend - většinou obsahuje html soubory, mapované a konkrétní jsp stránky daného modulu (často bývá obsah v žalostném stavu)
- module - adresář, který nás zajímá, sem se umísťují soubory, které mají být součástí daného modulu
./produkty/trunk/module (podle potřeby mohou být i jiné adresáře, jen ne adresář classes, který je součástí buildu modulu a obsahuje zkompilovaný obsah adresáře src)
- elements
- lib - knihovny, které modul potřebuje pro svůj běh
- pages - jsp stránky
- resources - další zdroje, které modul využívá (např. javascript kód, atd.)
- src - zdrojové kódy a property soubory s českým a anglickým překladem řetězců. Obsah tohoto adresáře bude v buildu modulu v adresáři classes
- templates - různé šablony a styly, které může modul nabízet
- test - umístění unit testů a dalších tříd pro testování funkčnosti modulu
Export buildu modulu z opencms - jen potřebné podadresáře
Pokud nastavíme, aby se při vytváření buildu exportoval obsah jen daných podadresářů, zajistí nám to, aby se nepotřebné soubory nezahrnuly do buildu modulu. Při nahrávání souborů z Eclipse se do OpenCms nahrávají skoro všechny soubory projektu.
Celá cesta k nastavení:
Administration View > Module Management > Edit Module > Module Resources
- Přihlásit se jako uživatel
Admin
- Přepnout se do administrátorského režimu
View => Administration
- V Administration View vybrat
Module Management
- klepnout na název modulu
cz.zcu.kiv.produkty
- V Edit Module vybrat
Module Resources
- Místo adresáře
/system/modules/cz.zcu.kiv.produkty/ nastavit podadresáře
/system/modules/cz.zcu.kiv.produkty/classes/
/system/modules/cz.zcu.kiv.produkty/elements/
/system/modules/cz.zcu.kiv.produkty/lib/
/system/modules/cz.zcu.kiv.produkty/pages/
/system/modules/cz.zcu.kiv.produkty/resources/
U jiného modulu mohou být jiné adresáře. Hlavně součástí být adresáře src a test.
Podpora SVN pro Eclipse
Podpora pro práci SVN úložišti není standardní součástí vývojového prostředí Eclipse a je nutno tuto podporu přidat. Pro přidání popdory je nutno doinstalovat Subclipse plugin. Je možno vyžít návody:
Přidat svn webkiv úložiště do Eclipse
- Přepnout se v Eclipse do SVN režimu
Window > Open Perspective > Other... > SVN Repository Exploring
- V části (okně)
SVN Repositories klepnout pravým tlačítkem a vybrat New > Repository Location...
- Do zobrzeného okna do políčka URL zadat url pro přístup k svn repozitáři
svn+ssh://forge.kiv.zcu.cz/home/svn/www-kiv
- Zadat své uživatelské jméno a heslo pro přístup k svn. (pokud bude vyžadováno)
- Klepnout na tlačítko Finish
- Nyní by mělo být už možno prohlížet strukturu SVN úložiště.
Integrace Eclipse s opencms - OpenCms Module Developer
Pro Eclipse existuje plugin OpenCms Module Developer. Tento plugin umožňuje z prostředí Eclipse nahrávat změny z vyvíjeného OpenCms modulu do běžícího OpenCms.
Nový Eclipse projekt (propojení s opencms a svn)
Vytvoříme nový Eclipse projekt. Při vytváření projektu nejdříve stáhneme soubory modulu z OpenCms a pak přesto nahrajeme novou verzi souborů ze SVN.
- Spustit průvodce stažením projektu z svn
File > New > Other... > SVN > Checkout Projects from SVN
- Klepnout na tlačítko Next
- Zaškrtnout Use existing repository location:
- Ze seznamu svn úložišť vybrat
svn+ssh://forge.kiv.zcu.cz/home/svn/www-kiv
- tlačítko Next
- Ze seznam adresářů vybereme ten, kde jsou soubory našeho modulu. V případě modulu produkty to je adresář
./produkty/trunk/module
- klepnout na Next
- zaškrtnout volbu Check out as a project configured using the New Project Wizard
- klepnout na Finish a zobrazí se dialog pro vytvoření nového projekt
- jako typ projektu vybereme
Other > OpenCms Module
- Na následném dialogu zaškrtnout volbu Import an existing module from OpenCms, stiskneme tlačítko Fetch
- Průvodce se spojí s OpenCms a zobrazí seznam modulů v OpenCms. V položce Module Name vybereme požadovaný modul, v našem případě cz.zcu.kiv.produkty
- klepneme na tlačítko Finish
- Potom se zobrazí dotaz, jestli chceme soubory, stažené z OpenCms, přepsat soubory z SVN. Tak potvrďte tlačítkem OK.
- Potom dojde ke stahování souborů z SVN.
- Až budou soubory ze SVN staženy, tak máme připravený k použití nový projekt, který je napojen jak na SVN tak i na OpenCms.#
Synchronizace s opencms
Opencms Eclipse plugin dovoluje nahrávat upravené soubory modulu z Eclipse přímo do opencms. Pokud se nám podařilo dobře vytnořit nový projekt, tak pro nahrání upravených souborů do OpenCms stačí:
- klepnout pravým tlačítkem v Project Explorer na název našeho vytvořeného projektu
- vybrat
Communicate with OpenCms server > Copy to OpenCms server
Testování
Není potřeba, aby unit testy a další třídy pro testování, byly součástí výsledného buildu modulu. To prakticky znamená, že testy je potřeba spravovad odděleně a zkompilované testy nesmí být součástí složky classes.
- vytvořit v projektu nový adresář pro umístění testů
test
- klepnout pravým tlačítkem na název projektu v Project Explorer a vybrat
Properties
- Pak v Java Build Path v panelu Source přidat složku
test, aby se testovací třídy při změně automaticky kompilovaly.
- ve vlastnostech složky test nastavit
Output folder na test-classes. Testovací třídy se pak nebudou kompilovat do složky classes, ale do složky test-classes.
