• Martin Žibrický má jiný postup když se použije jednodušší přístup ke struktuře modulu.

• 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

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 "projekt",

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ů.

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.

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.

1. vytvořit v projektu nový adresář pro umístění testů test
2. klepnout pravým tlačítkem na název projektu v Project Explorer a vybrat Properties
3. Pak v Java Build Path v panelu Source přidat složku test, aby se testovací třídy při změně automaticky kompilovaly.
4. 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.

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.

1. Spustit průvodce stažením projektu z svn File > New > Other... > SVN > Checkout Projects from SVN
2. Klepnout na tlačítko Next
3. Zaškrtnout Use existing repository location:
4. Ze seznamu svn úložišť vybrat svn+ssh://forge.kiv.zcu.cz/home/svn/www-kiv
5. tlačítko Next
6. Ze seznam adresářů vybereme ten, kde jsou soubory našeho modulu. V případě modulu produkty to je adresář ./produkty/trunk/module
7. klepnout na Next
8. zaškrtnout volbu Check out as a project configured using the New Project Wizard
9. klepnout na Finish a zobrazí se dialog pro vytvoření nového projekt
10. jako typ projektu vybereme Other > OpenCms Module
11. Na následném dialogu zaškrtnout volbu Import an existing module from OpenCms, stiskneme tlačítko Fetch
12. 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
13. klepneme na tlačítko Finish
14. Potom se zobrazí dotaz, jestli chceme soubory, stažené z OpenCms, přepsat soubory z SVN. Tak potvrďte tlačítkem OK.
15. Potom dojde ke stahování souborů z SVN.
16. 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.#

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čí:

1. klepnout pravým tlačítkem v Project Explorer na název našeho vytvořeného projektu
2. vybrat Communicate with OpenCms server > Copy to OpenCms server

Kompilace testů to jiného adresáře než classes

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.

• Stažení a popis instalace modulu lze najít na http://www.redstardevelopment.nl/opencms/opencms/en/opencms/plugin/
• Video tutoriál pro nastavení modulu názorně popisuje, jak v Eclipse tento plugin rozchodit.
• Tento video návod také zahrnuje instrukce pro vytvoření nového projektu v Eclipse, kdy se stáhnou soubory z lokálního OpenCms. Toho využijeme ale až později, kdy vytvoříme projekt is napojením na svn.

1. Přepnout se v Eclipse do SVN režimu Window > Open Perspective > Other... > SVN Repository Exploring
2. V části (okně) SVN Repositories klepnout pravým tlačítkem a vybrat New > Repository Location...
3. 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
4. Zadat své uživatelské jméno a heslo pro přístup k svn. (pokud bude vyžadováno)
5. Klepnout na tlačítko Finish
6. Nyní by mělo být už možno prohlížet strukturu SVN úložiště.

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:

• http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA
• http://wheelersoftware.com/articles/install-subclipse-eclipse-svn.html

• propojit projekt s lokálně běžícím OpenCms pro testování

• 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)

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

1. Přihlásit se jako uživatel Admin
2. Přepnout se do administrátorského režimu View => Administration
3. V Administration View vybrat Module Management
4. klepnout na název modulu cz.zcu.kiv.produkty
5. V Edit Module vybrat Module Resources
6. 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.

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

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

• 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?
• zprovozněné testovací prostředí prostředí opencms
• nahrané do opencms potřebné moduly z webkiv kolekce
• nahraný poslední build modulu, který budem vyvíjet, do opencms

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

Podpora SVN pro Eclipse

Přidat svn webkiv úložiště do Eclipse

Integrace Eclipse s opencms - openCms Module Developer

• stažení a instalace http://www.redstardevelopment.nl/opencms/opencms/en/opencms/plugin/
• nastavení v Eclipse http://www.redstardevelopment.nl/opencms/opencms/en/opencms/plugin/userinstructions.html

Nový Eclipse projekt (propojení s opencms a svn)

Kompilace testů to jiného adresáře než classes

Synchronizace s opencms

Opencms Eclipse plugin dovoluje nahrávat upravené soubory modulu z Eclipse přímo do opencms.

1. 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

• Martin Žibrický má jiný postup když se použije jednodušší přístup ke struktuře modulu -- viz níže.

Vývoj pro alternativní strukturu modulu

TBD MŽ

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.

Debuging

Degugging

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.

1. 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í.
2. Otevřete si eclipse a zvolte run -> debug configurations... -> remote java application -> pravoklik -> new.
3. Zvolte si název
4. Jako projekt vyberte ten, který chcete debugovat (absolventi, fav modul, ...)
5. Connection type: Standard (Socket Attach)
6. Host: localhost, Port: 8000
7. 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.
8. 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 logiky 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.

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.

1. 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/)
2. 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

Implicitně je zapnut, detaily pro přístup z Eclipse na http://opencms-wiki.org/WebDAV_access_to_the_OpenCms_VFS#Eclipse_WebDAV_plugin.

Stručná rekapitulace:

1. z Eclipse 3.1 update site nainstalovat Eclipse FTP and WebDAV Support
2. otevřít View "Target sites", vytvořit nový WebDAV target namířený na URL OpenCms webdav servletu (např. http://localhost:8080/opencms7/webdav/)
3. buďto vytvořit samostatný nový "simple" projekt, nebo adresář ve stávajícím projektu, a na něm "Import" > source Other > vybrat vytvořený WebDAV target -- chvíli načítá VFS, pak ukáže strom co vše chceme importovat
4. po lokálních úpravách nutno udělat Export s podobnou procedurou jako při importu (ukazuje ikonkamu i resources směr, který doporučuje pro synchronizaci)

Přístup do VFS přes WebDAV (pro OpenCms 7)

Implicitně je zapnut, detaily pro přístup z Eclipse na http://opencms-wiki.org/WebDAV_access_to_the_OpenCms_VFS#Eclipse_WebDAV_plugin .

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

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).

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

1. V opencms workplace se přepněte do Administration view => Workplace Tools => Synchronization settings.
2. Zaškrtněte políčko Enabled
3. Jako Target folder zadejte adresář z RFS např. C:\opencms_vfs
4. Jako Resource vyberte adresář z VFS např. /sites/default/test/
5. Potvrďte a na horní liště Opencms Workplace stiskněte Reload.
6. 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

1. Vytvořte nový Dynamic Web projekt File => New => Projekt => Dynamic Web Projekt
2. 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.
3. Nyní je třeba k vytvořenému projektu přiřadit knihovny z Opencms Properties projektu => Java Build Path => Libraries => Add External Jars
4. 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.
5. 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.
6. !!! Sesynchronizovaný obsah je třeba v Opencms workplace publikovat.

Vývoj .java tříd pro Opencms pomocí eclipsu

1. Vytvořte nový Dynamic Web projekt File => New => Projekt => Dynamic Web Projekt
2. Přiřaďte projektu opencms knihovny stejným způsobem popsaným v předchozím odstavci. (Nyní stačí pouze opencms.jar)
3. Nyní si vytvořte v projektu java package se třídou uvnitř.
4. 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.
5. 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.
6. Podle tutoriálu z části Opencms Module Developer nyní překopírujem (i s publikací) {ECLIPSE_PROJECT} do Opencms VFS.
7. Aby se změny v Java třídě projevily, je třeba ještě restartovat opencms aplikaci na tomcatu.

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).

• Opencms modul aktuality Δ

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).

• Opencms obsah k aktualitám Δ

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.

• Opencms Module Developer aktuality Δ
• Projekt synchronizovaného adresáře s obsahem aktualit Δ
• Projekt s .java třídou pro aktuality Δ