* Martin Žibrický má [[jiný postup když se použije jednodušší přístup ke struktuře modulu -> #alt-struktura]].

* 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@@.

# 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*.

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

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@@


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

!!! Integrace Eclipse s opencms - OpenCms Module Developer

Pro Eclipse existuje plugin [[http://www.redstardevelopment.nl/opencms/opencms/en/opencms/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/
* [[http://www.redstardevelopment.nl/opencms/opencms/en/opencms/plugin/userinstructions.html | 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.*

# 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ě.

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ř.%newwin% [[http://www.eclipse.org/downloads/ | 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@@

# 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@@.

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.

# 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 @]

----

[[#alt-struktura]]

* Martin Žibrický má jiný postup když se použije jednodušší přístup ke struktuře modulu -- viz [[#alt-struktura | 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 [[http://www.opencms-wiki.org/Debugging|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í.
# 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 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.

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

# 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

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:
# z Eclipse 3.1 update site nainstalovat _Eclipse FTP and WebDAV Support_
# otevřít View "Target sites", vytvořit nový WebDAV target namířený na URL OpenCms webdav servletu (např. @@http://localhost:8080/opencms7/webdav/@@)
# 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
# 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 -> http://sourceforge.net/projects/eclipse-rbe/]], 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ř.%newwin% [[http://www.eclipse.org/downloads/ | 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 %newwin% [[http://opencms-wiki.org/Eclipse_integration | 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 [[jar v modulech | 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.

!! 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@@).
* [[Attach:cz.zcu.kiv.aktuality_0.6.zip | 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@@).
* [[Attach:testovaci_v3.1.zip | 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.
* [[Attach:eprj-aktuality_omd.zip | Opencms Module Developer aktuality]]
* [[Attach:eprj-opencms_vfs_synch.zip | Projekt synchronizovaného adresáře s obsahem aktualit]]
* [[Attach:eprj-aktuality_java.zip | Projekt s .java třídou pro aktuality]]