Chapter 1. Überblick

Table of Contents

Grundlegende Hinweise
Komponente anlegen
Erklärungen zu ofbiz-component.xml
Anlegen der web app

Anlegen und laden der eigenen Komponente
Anlegen einer fortgeschrittenen GUI Komponente, inkl. Datenbank und absichern der Anwendung
Weitere Datenbank Interaktionen (CRUD) und Valdierung von Feldparametern
Aufrufen von automatischen Diensten, mehrere Dienste als Gruppe aufrufen, Interfaces anlegen und Parameterübergaben zwischen Diensten
Eigene Entitäten, Erweiterung der OOTB (Out-Of-The-Box) Entitäten und XML Dateien für eigene Anwendung anpassen
Kommunikation zwischen Client und Server mit AJAX

Grundlegende Hinweise

Für zusätzliche Hinweise lohnt sich ein Blick in die Beispielkomponenten. Die in jeder OFBiz Version mitgelieferten Beispielkomponenten passen zur jeweiligen Version. Jede neue Funktion wird in OFBiz zuerst in den Beispielkomponenten aufgeführt. Ein Blick in die Beispiele lohnt sich also immer.
Bevor Sie mit der Entwicklung einer Komponente beginnen sollten Sie unbedingt folgendes gelesen haben: OFBiz Contributors Best Practices , Coding Conventions und Best Practices Guide
Kopieren Sie keine Dateien von anderen Komponenten wenn die Revisionsnummer mitkopiert wird. Legen Sie besser, falls notwendig, eine neue Datei an und kopieren dann den entsprechenden Inhalt. Kümmern Sie sich auch um den vermeintlich toten Code.
Der beste Ausgangspunkt für (englischsprachige) Hilfe ist OFBiz Documentation Index .
Widmen Sie den Ausgaben auf der Konsole vom Anfang an ihre Aufmerksamkeit.
Den Quellcode zu den Anwedungen finden sie unter: Quellcode laden

Komponente anlegen

Legen Sie im Verzeichnis hot-deploy ein neues Verzeichnis practice an. Der Name des Verzeichnisses sollte dem Namen der Anwendung entsprechen die entwickelt wird. Anmerkung: die Entwicklung findet ausschließlich in diesem Verzeichnis statt.

Legen Sie die Datei ofbiz-component.xml im Verzeichnis ( hot-deploy/practice ) mit folgendem Inhalt an.

<?xml version="1.0" encoding="UTF-8"?>
<ofbiz-component name="practice"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/ofbiz-component.xsd">
      <resource-loader 	name="main" type="component"/>
    <webapp name="practice"
       title="Practice"
       server="default-server"
       base-permission="OFBTOOLS"
       location="webapp/practice"
       mount-point="/practice"
       app-bar-display="false"/>
</ofbiz-component>

Erklärungen zu ofbiz-component.xml

Über die ofbiz-component.xml Datei wird OFBiz mitgeteilt wo die Ressourcen sind und welche Elemente zum Classpath hinzuzufügen sind.
Der 'resource-loader name' kann jeder beliebiger String sein. In diesem Beispiel verwenden wir " main ". Der " type " veranlasst OFBiz die Komponente zu laden.
```
<resource-loader name="main" type="component"/>
								
						
```
Die Bedeutung der Attribute am webapp Tag sind wie folgt:
```
<webapp name="practice"
       title="Practice"
       server="default-server"
       base-permission="OFBTOOLS"
       location="webapp/practice"
       mount-point="/practice"
       app-bar-display="false"/>

						
```
- name : legt den Namen der Web-Anwendung fest
- title : Dies ist der Titel der Anwendung welcher in der Haupt-/Top-Navigation angezeigt wird.
- server : Darüber wird OFBiz angezeigt, welcher Server zu verwenden ist.
- base-permission : Dieser Wert zeigt an, dass der Nutzer die Berechtigung OFBTOOLS benötigt um die Anwedung nutzen zu können. Da der Nutzer "Admin" diese Berechtigung hat muss kein Nutzer angelegt werden.
- location : Dies ist das Standardverzeichnis für den Server
- mouont-point : Dies ist die URL welche für die Anwendung genutzt wird um auf die Anwendung zuzugreifen. In diesem Fall wird es http://localhost:8080/practice sein.
- app-bar-display : Damit wird angezeigt ob die Anwendung in den Hauptanwendungsreitern ("main application tabs") erscheinen soll.

Anlegen der web app

Legen Sie das Verzeichnis webapp im Verzeichnis der Komponente practice an ( hot-deploy/practice/webapp ). Dieses Verzeichnis enthält alle webapp spezifischen Dateien der neuen Anwendung.
Legen Sie ein Unterverzeichnis practice im webapp Verzeichnis an, welches den gleichen Namen trägt wie das Verzeichnis für die neue Anwendung ( hot-deploy/practice/webapp/practice ). Eine Komponente kann mehrere Anwendungen haben. Z.B. hat die Komponente marketing die beiden webapps marketing und sfa . Die webapp, welche wir anlegen, wird weiterhin dem JEE Webapp Standard entsprechen.
Legen Sie das WEB-INF Verzeichnis an ( hot-deploy/practice/webapp/practice/WEB-INF ).

Eine OFBiz Web-Anwendung benötig zwei Konfigurationsdateien: controller.xml und web.xml

Über die controller.xml wird gesteuert wie mit den Anfragen der Besucher zu verfahren ist, d.h. welche Aktionen empfangen werden und welche Seite zu rendern sind. web.xml teilt OFBiz mit welche Ressourcen der Web-Anwendung zur Verfügung stehen (Datenbanken und Geschäftlogik) und wie Web-bezogene Vorgänge zu behandeln sind. Beispiele dafür sind Willkommensseite, Seitenumleitungen und Fehlerseiten.
Lege eine Datei mit dem Namen web.xml im Verzeichnis hot-deploy/practice/webapp/practice/WEB-INF/ (entspricht den JEE Spezifikationen) an. Der Inhalt der Datei kann von einer anderen Komponente kopiert werden (z.B. /framework/example). Die wichtigen Werte, die geändert werden müssen, sind <display-name> , localDispatcherName , mainDecoratorLocation und webSiteId .
```
<context-param>
    <param-name>webSiteId</param-name>
    <param-value>PRACTICE</param-value>
    <description>A unique ID used to look up the WebSite entity to get information about catalogs, etc.</description>
</context-param>
<context-param>
     <param-name>localDispatcherName</param-name>
     <param-value>practice</param-value>
     <description>A unique name used to identify/recognize the local dispatcher for the Service Engine</description>
</context-param>
<context-param>
     <param-name>mainDecoratorLocation</param-name>
     <param-value>component://practice/widget/CommonScreens.xml</param-value>
     <description>The location of the main-decorator screen to use for this webapp; referred to as a context variable in screen def XML files.</description>
</context-param>
						
```
- param-value für webSiteId sollte erstmal PRACTICE sein. Im späteren Verlauf werden wir darauf noch einmal genauer eingehen.
- Der param-value für mainDecoratorLocation erstmal component://practice/widget/CommonScreens.xml sein. Detailiertere Erläuterungen dafür folgen ebenfalls später. Dieser Wert wird genutzt um auaf die main decorator location in Anzeigen zu verweisen: ${parameters.mainDecoratorLocation} .
  
  Damit machen wir den Code unabhängiger gegenüber Pfadänderungen. Falls der main decorator auf einem anderen Pfad verschoben wird, so muss dies nur an dieser Stelle geändert werden. Damit wird es auch leichter bestehenden Code in anderen Komponenten ohne Änderungen wiederzuverwenden.

Legen Sie die Datei controller.xml an. Am Anfang wird diese Datei klein und einfach sein, aber mit den Anforderungen wachsen. Für's erst fügen Sie bitte folgendes ein:

<?xml version="1.0" encoding="UTF-8"?>
<site-conf xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/site-conf.xsd">
       <include location="component://common/webcommon/WEB-INF/common-controller.xml"/>
       <description>Practice Component Site Configuration File</description>
       <owner>Copyright 2001-2009 The Apache Software Foundation</owner>
       <handler name="screen" type="view" class="org.ofbiz.widget.screen.ScreenWidgetViewHandler"/>
       <!-- Request Mappings -->
       <request-map uri="main">
           <security https="false" auth="false"/>
           <response name="success" type="view" value="main"/>
       </request-map>
       <!-- end of request mappings -->
       <!-- View Mappings -->
       <view-map name="main" type="screen" page="component://practice/widget/PracticeScreens.xml#main"/>
       <!-- end of view mappings -->
</site-conf>

Das Gerüst für die Fehlerbehandlung
1. Legen Sie ein neues Verzeichnis error in folgendem Pfad an: hot-deploy/practice/webapp/practice/ .
2. Legen Sie eine Datei error.jsp im error Verzeichnis an. Der Inhalt der Datei kann für den Anfang wieder von einer jeden anderen existierenden Komponente kopiert werden, z.B. von einer example Komponente.
  
  Der Ort für die Fehlerseite wird am Anfang der controller.xml Datei festgelegt. (!! fehlt im Beispiel !!). Sie werde eine error.jsp Datei anlegen müssen um Fehlermeldungen an den Nutzer ausgeben zu können.
Legen Sie das Verzeichnis widget im Verzeichnis hot-deploy/practice an. Dieses Verzeichnis wird Ihre Formulare, Menüs und Seiten enthalten welche für das UI verwendet werden.

Legen Sie eine Datei mit dem Namen PracticeScreens.xml im Verzeichnis widget an. Der Inhalt der Datei kann wieder von einer anderen Komponente kopiert werden (z.B. Example ).

<?xml version="1.0" encoding="UTF-8"?>
<screens xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/widget-screen.xsd">
    <screen name="main">
        <section>
            <widgets>
                <label text="This is first practice"/>
            </widgets>
        </section>
    </screen>
</screens>

Damit sind Sie dann in der Lage Bildschirmansichten zu erzeugen. Sehr hilfreich dafür ist der Best Practices Guide .

Jetzt sind alle grundlegenden Dinge an ihre Platz, egal wie groß oder komplex die Anwendung werden wird.

Eine Anfrage über den Browser geht immer an eine spezifische Ressoruce. Nehmen wir zum Beispiel die Anfrage http://localhost:8080/practice/control/main (GET).
1. Wenn OFBiz eine solche Anfrage erhält wird zuerst in /practice section nachgeschaut. Dies kommt daher, dass wir in der ofbiz-component.xml Datei den Mount-Punkt auf /practice gesetzt haben. Die Verarbeitung erfolgt also über unsere practice Komponente.
2. Anschließend wird in der controller.xml nachgeschaut. Innerhalb der controller.xml haben wir request-maps und view-maps definiert. Wenn eine request-map mit dem Name main gefunden wird, dann wird die entsprechende view-map herangezogen.
  
  Eine request-map kann entweder einen View oder, wie wir später sehen werden, ein Event oder Dienst definieren. Falls ein View definiert wird, so wird in der controller.xml nach einem view-map Einrag geschaut welcher als value den Namen trägt welcher in request-map gesetzt wurde.
3. Ab hier halten wir es einfach und nehmen an, dass alle Anfragen an den type=screen gehen. In diesem Fall spezifierziert der page Tag einen Pfad zur Datei für die Screen definition. Sowie eine Screen-Namen welcher nach dem # Zeichen angezeigt wird.
Nun wird es Zeit unsere erste practice-OFBiz-Anwendung zu starten.

Starten Sie den Server mit dem Kommando ./startofbiz.sh oder über java -Xmx256M -jar ofbiz.jar (-Xmx256M sorgt dafür, dass genügend Speicher zur Verfügung steht). Anschließend die URL http://localhost:8080/practice/control/main über den Browser aufrufen. Jetzt sollte der Browser folgende Seite zeigen.
Legen Sie im WebApp-Verzeichnis die Datei index.jsp an ( practice/webapp/practice ). Der Inhalt kann wieder von einem der Beispiele kopiert werden. Diese Datei ist dafür verantwortlich die Anfragen auf http://localhost:8080/practice/ auf control/main umzuleiten. Eine Anfrage der Form http://localhost:8080/practice/unknown/request wird auf den redirectPath umgeleitet welcher in der web.xml definiert ist. In solch einem Fall wird der ContextFilter die Anfrage herausfiltern und auf die entsprechende Seite umleiten.