Page History

...

This is a tutorial providing an introduction to OFBiz application development. It starts with the usual Hello World tutorial, then shows how to retrieve the names of the people stored in the OFBiz database and in a third example introduces entities and services. This example will store the names of guests and their hobbies in the database. Following that there are examples how to find, update and delete these persons in the database. Then it is demonstrated how to generate lists of these persons and export the data in various file formats. The first three examples are based on examples developed by Si Chen. These examples were modified for this tutorial and ported to run with OFBiz version 17.12.04. The tutorials are grouped here into one plugin called OI. These examples have been developed on a Windows PC. On Linux convert the backslashes to forward slashes in the path names.

...

<menu-item name="hello" title="${uiLabelMap.Hello}"><link target="hello"/></menu-item>

The "link target" element tag specifies the request-map name in the controller.xml file which will be discussed below.

...

The request-map entries define the URL of the screen for the browser. The uri=”hello” element attribute defines the last part of the URL, so the complete URL to call this is http://localhost:8443/OI/control/hello. The request-map entries must be listed before the view-map entries in the controller.xml file. The “security” element with the element attribute https=”true” sets OFBiz to offer the page using the https protocol. The auth=”true” element attribute makes sure that access is granted only to authenticated users. If the user is not authenticated, he will be redirected to the user login screen. The ”response-name” element tag will associate a request-map with the view-map specified in the value tag. In this example this is the view-map with the name ”hello”. Further details regarding this controller.xml file can be found here:
Control Servlet Guide

...

The first screen has an actions element where the the data retrieval logic is defined. The “entity-condition” command is used to retrieve all the records from the “HelloPerson” entity sorted by “helloPersonId”. The <set field="headerItem" value="guestbook"/> line is used to select the guestbook menu button after the screen is rendered.
The second screen shall display the hobbies linked with a particular person. In the actions element the helloPersonId of the person in question is moved from the parameters map or context to the field helloPersonId using the „from-field“ elementattribute. Then the „entity-and“ command is used to write all hobbies of the person with the selected helloPersonId into the allHobbies list. The „field-map“ element specifies the primary key as a filter for the allHobbies list. So the all Hobbies list will only contain entities matching the specified helloPersonId. Then the „order-by“ command sorts the entities in the allHobbies list to an ascending helloHobbyId field.

...

Here we use the engine "entity-auto" for updateguest as a simple way to create the required methods and use auto-attributes to generate the fields on our screen. We do not need to define a service script when we select "entity-auto". However, when we delete the record, we also have to remove the relations to the hobbies of the guest. Therefore we have to add the following Minilang script (engine=“simple“) to the OIServices.xml file, which removes the relations to the hobbies too:

...

The form FindGuestList is defined with the type list, because it shall display a list and the list-name listIt. This name is required to use the performFind script which is called in the form. The paginate-target="findguests" element attribute points to the screen which displays this form and is required to enable pagination for lists which are displayed on several pages. Then there are a number of elements attributes which define the features of the list. The element attribute odd-row-style="alternate-row" will provide a grey background for every second line, header-row-style="header-row-2" will provide a dark list header which allows to sort the columns FirstName and LastName, default-table-style="basic-table hover-bar" will draw a dark bar when the mouse is positioned over a line in the list. The separate-columns="true" element attribute will put the fields into separate columns. For fields defined as „display“ this is the default and this element attribute is not required.

Then the performFind service in the actions element of the form is called. The performFind service is defined in the $OFBIZ_HOME\framework\common\servicedef\services.xml file and the $OFBIZ_HOME\src\main\java\org\apache\ofbiz\common\FindServices.java file.

The performFind service fetches the data from the HelloPerson entity using the parameters in the FindGuestCtx context which was defined in the screen definition. This data is put into the listIt list. As long as you have only one list, you can use the value „parameters“ for the field-name input-fields element directly. However, if you have multiple lists, pagination will only work when different contexts are used. The field-name orderBy element allows to specify the sort order of the list. Here it is used when the list is sorted by clicking on the column headings. Using the viewSize element field which is defined in the screen definition you can specify how many lines shall be displayed on a page. When there are more lines available, a bar will be displayed which lets you scroll through forward and backwards through the list. You e.g. set the value for viewSize to two and then you will see this bar with just a few guests entered in your database. The element field viewIndex specifies the first page to be displayed on the screen if this shall not be the first one.

...

In the FindGuestsList form, in the hyperlink element, the “description” attribute defines the text displayed as the hyperlink. The term ${helloPersonId}inserts the “helloPersonId” variable. The “target” attribute defines the request map in the controller file for the hyperlink. The “parameter” element passes helloPersonId as a parameter to the Updateguest2 screen.
For the firstname and lastname fields the element attribute sort-field="true" is specified. Therefore the list can be sorted by clicking on the column heading for these names.

...

At the very beginning of this tutorial we have removed the Chinese characters from the $OFBIZ_HOME\plugins\OI\config\OIUiLabels.xml file. Now we will extend this file to translate messages in the FindGuests form to German. This form contains e.g. the element value ${uiLabelMap.OIFirstName}. OFBiz will look into the OIUiLabels.xml file and use the specified translation in there. This can make sense for English as well, you can convert the fieldname into a more user-friendly text this way. Add the following lines to the OIUiLabels.xml file within the resource:

...

Generate lists of the guests and export the data in various file formats

With OFBiz allows you to can generate lists in various file formats, HTML, CSV, XLS and PDF for example. We will now see how you can write list definitions and output these in these file formats.

...

For the Listguest and Listguest2 screens we use the type „screen“. For generating a CSV file we use the elements attributes type="screencsv" content-type="text/csv", for the Excel file we use type="screenxls" content-type="application/vnd.ms-excel" and for a PDF file we use type="screenfop" content-type="application/pdf".

...

In the example above we have used the elementsattributes: type="screenfop" and content-type="application/pdf" in the controller.xml file. FOP specifies the Apache FOP (Formatting Objects Processor) extension. This extension is a print formatter driven by XSL formatting objects (XSL-FO) and an output independent formatter. It is a Java application that reads a formatting object (FO) tree and renders the resulting pages to a specified output. Details are described in this document: https://xmlgraphics.apache.org/fop/
So in the example above we have used screenfop to generate a PDF document and now we will use screenfop to generate a barcode.

First open the file framework\webapp\config\fop.xconf and modify the line 34 to: <base>http://localhost:8443> to use the current port number for our installation.

...

<#escape x as x?xml>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">

    <fo:layout-master-set>
        <fo:simple-page-master master-name="main" page-height="4in" page-width="8in"
                               margin-top="0.5in" margin-bottom="0.25in" margin-left="0.25in" margin-right="0.25in">
            <fo:region-body margin-top="0in"/>
            <fo:region-before extent="0in"/>
            <fo:region-after extent="0in"/>
        </fo:simple-page-master>
    </fo:layout-master-set>

    <fo:page-sequence master-reference="main">
        <fo:flow flow-name="xsl-region-body" font-family="Helvetica">
		<fo:block text-align="center">
		<#-- This text is displayed above the barcode -->
        ${firstname!} ${lastname!}
        </fo:block>
            <fo:block text-align="center" font-size="48pt">
			123
                <fo:instream-foreign-object>
                    <barcode:barcode xmlns:barcode="http://barcode4j.krysalis.org/ns"
						message="${helloPersonId!}">    
						<#-- message is the number in the barcode -->
                        <barcode:code128>
                            <barcode:height>0.5in</barcode:height>
                            <barcode:module-width>.375mm</barcode:module-width>
                        </barcode:code128>
                        <barcode:human-readable>
                            <barcode:placement>bottom</barcode:placement>
                            <barcode:font-name>Helvetica</barcode:font-name>
                            <barcode:font-size>18pt</barcode:font-size>
                            <barcode:display-start-stop>false</barcode:display-start-stop>
                            <barcode:display-checksum>false</barcode:display-checksum>
                        </barcode:human-readable>
                    </barcode:barcode>
                </fo:instream-foreign-object>
				456
            </fo:block>
            <fo:block><fo:leader/></fo:block>			
			<fo:block text-align="center">
				${comments!} ${firstname!} ${lastname!} in the helloPerson entity.
			</fo:block>
        </fo:flow>
    </fo:page-sequence>
</fo:root>
</#escape>

The elementtag fo:instream-foreign-object defines the barcode to print. In there there is the message variable into which you move the value of the barcode. The size of the barcode is defined with the elementstags:

<barcode:height>0.5in</barcode:height>

...

Text that shall be printed to the left or right of the barcode has to be put into the same block the element tag fo:instream-foreign-object is in. Text above or below the barcode has to be specified in separate blocks above or below this block. When you click on the barcode menu button, the following PDF document will be generated:

...

In the controller.xml file we have defined the request-maps with this elementtag: <security https="true" auth="true"/> This defines that the application can only be accessed using the HTTPS protocol and you need to login to use the requested application. The controller.xml file includes the component://common/webcommon/WEB-INF/common-controller.xml file. This file contains definitions for the request-maps uri="checkLogin", "login", "logout", "forgotPassword", and "passwordChange" to handle these processes.

The permissions required to use the OI plugin are set in the $OFBIZ_HOME\plugins\OI\ofbiz-component.xml file. In the webapp name="OI" element tag you find the definition: base-permission="OFBTOOLS,OI". So the user has to have the permissions for OFBTOOLS or OI to use the OI plugin. You usually log in as "admin" and this user has the permissions for OFBTOOLS. So you have no problem using your plugin. To edit the user access rights, you select the party application from the top menu. Then you click find to get a list of the registered users and click on the Party Id to edit the party. The profile of the selected party will be presented and you can see how many and what User Ids are defined for this party.

...

The Eclipse IDE provides excellent support for developing OFBiz XML files. These files have a xsi:schemaLocation tag attribute which points to an XSD file. There is an XSD file for e.g. widget-screen, widget-form or Minilang/simple-methods. This file contains the commands and their descriptions relevant for the particular file you are editing. Eclipse will e.g. display a tooltip window when you move your mouse on an element tag in your source file and provide autocompletion.

...

c) run gradlew.bat:
gradlew cleanAll loadAll (=gradlew.bat cleanAll loadAll)
Allow this batch file to download files when queried by Windows

If you do not want to include the demo data use this command instead:
gradlew cleanAll
gradlew "ofbiz --load-data readers=seed,seed-initial" loadAdminUserLogin -PuserLoginId=admin
This command will build OFBiz and load the seed data and create the admin user that you can use to login.

d) Finally start OFBiz by entering:
gradlew ofbiz
You can make a startofbiz.bat file with this command and generate a link to that from your desktop to start it conveniantly when required.

...

Get into the ofbiz directory in your home directory and execute the following scripts:
./gradlew init-gradle-wrapper
./gradlew cleanAll loadAll

If you do not want to include the demo data use the commands below instead of ./gradlew cleanAll loadAll:
./gradlew cleanAll
./gradlew "ofbiz --load-data readers=seed,seed-initial" loadAdminUserLogin -PuserLoginId=admin
This command will build OFBiz and load the seed data and create the admin user that you can use to login.

This will install OFBiz.

5. Finally start OFBiz by entering:

./gradlew ofbiz

OFBiz will compile and start. After the message "OFBiz is started and ready" appears, followed by several further messages, it will stop with the prompt :ofbiz. This means you can use OFBiz now.
Ignore the % progress indicator because this task does not end as long as OFBiz is running.

...

You may use Ctrl+C in the terminal command window where you started OFBiz.