THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
<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"/>
...
c) server :- This will let ofbiz know what server to use
d) base-permission :- This line requires that the user should have the OFBTOOLS permission to be able to use the application. Since the 'admin' user has this permission we do not have to create any new users.
e d) location :- This will be the location that is the default base directory for the server
e f) mount-point :- This is the URL used to access this resource. in this case it would be localhost:8080/practice
f g) app-bar-display :- This will let ofbiz know if we want our component to show up in the main application tabs that are part of the common ofbiz decorator.
Creating the web app:
Step - 1 : Create a "webapp" directory in the practice component (hot-deploy/practice/webapp).
This directory contains all the webapp related files for the component we are creating.
Step - 2 : Create a sub-directory inside the webapp directory by the name of "practice" which is the name of the webapp which you are going to develop (hot-deploy/practice/webapp/practice). A component can have multiple webapp's attached to it. e.g. In the "marketing" component there are two webapps "marketing" and "sfa".
The webapp we are creating will follow the J2EE webapp standards.
Step - 3 : Create WEB-INF directory in your webapp (hot-deploy/practice/webapp/practice/WEB-INF).
An OFBiz web application requires two configuration files, a controller.xml and a web.xml. The controller.xml tells OFBiz what to do with various requests from visitors: what actions to take and what pages to render. web.xml tells OFBiz what resources (database and business logic access) are available for this web application and how to handle web-related issues, such as welcome pages, redirects, and error pages.
Step - 4 Create a file named "web.xml"(web.xml follows j2ee webapp specs). Contents of this file can be taken from any of the existing component e.g. example component. The Important values to change are the <display-name>, the localDispatcherName, and the mainDecoratorLocation.
For now put the value: "component://practice/widget/PracticeScreens.xml" in for the location and you will see why in a while.
Step - 5 Create a file named "controller.xml" (used by ofbiz webapp controller) This file will be small and simple at first but will grow as we add functionality later on. For now insert the following code:
<?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-2008 The Apache Software Foundation</owner>
<!-- 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 -->
Here we should understand why we have given the permission "OFBTOOLS" in base-permission. To understand this please read following carefully and perform steps as mentioned:
Confirm that user 'admin' has the 'OFBTOOLS' permission.
Step : 1 - Login into partymanager to confirm that the user admin has the required permission https://127.0.0.1:8443/partymgr/control/main
Step : 2 - Once your logged in search for the user by typing 'admin' in the User Login field and then clicking the Lookup Party button.
Step : 3 - This does a wild char* search and you should see multiple users returned.Click the 'Details' button for the admin user.
Note : Important point to note here is that the person 'Mr. THE PRIVILEGED ADMINISTRATOR' has a partyid admin has multiple logins as listed in the
User Name(s) form.
Step : 4 - We interested in the admin user login so click on the 'Security Groups' button and confirm that the use 'admin' is part of the 'FULLADMIN' group. The Groups that the user belongs to is shown in the bottom list form Drill down on the FULLADMIN.
Step : 5 - Click on the Permissions tab. This tab shows all the permissions for the FULLADMIN security group. Navigate between the permissions till you find the OFBTOOLS permissions.
'OFBTOOLS_VIEW Permission to access the Stock OFBiz Manager Applications.' This confirms that the userlogin 'admin' has the permission 'OFBTOOLS'
Step : 6 - Take a moment to review the entity model as it relates to users and permissions. The arrow represents the many side of the relationship.
Creating the web app:
Step - 1 : Create a "webapp" directory in the practice component (hot-deploy/practice/webapp).
This directory contains all the webapp related files for the component we are creating.
Step - 2 : Create a sub-directory inside the webapp directory by the name of "practice" which is the name of the webapp which you are going to develop (hot-deploy/practice/webapp/practice). A component can have multiple webapp's attached to it. e.g. In the "marketing" component there are two webapps "marketing" and "sfa".
The webapp we are creating will follow the J2EE webapp standards.
Step - 3 : Create WEB-INF directory in your webapp (hot-deploy/practice/webapp/practice/WEB-INF).
An OFBiz web application requires two configuration files, a controller.xml and a web.xml. The controller.xml tells OFBiz what to do with various requests from visitors: what actions to take and what pages to render. web.xml tells OFBiz what resources (database and business logic access) are available for this web application and how to handle web-related issues, such as welcome pages, redirects, and error pages.
Step - 4 Create a file named "web.xml"(web.xml follows j2ee webapp specs). Contents of this file can be taken from any of the existing component e.g. example component. The Important values to change are the <display-name>, the localDispatcherName, and the mainDecoratorLocation.
For now put the value: " <view-map name="main" type="screen" page="component://practice/widget/PracticeScreens.xml#main"/>
<!-- end of view mappings -->
</site-conf>
Step - 6 : Move up one level and create a new directory named 'error'(hot-deploy/practice/webapp/practice/error).
Step - 6.a : Create a file error.jsp inside the "error" directory. Contents of this file can be taken from any of the existing component e.g. example component.
The location of your error page will be specified in the beginning of your controller.xml file like <errorpage>/error/error.jsp</errorpage> . You will need to make or copy over a /webapp/practice/error/error.jsp page to show an error message to the user.
Step - 7 : Create a sub-directory inside your component directory "practice" named "widget"(hot-deploy/practice/widget).
This directory will contain your forms and screens which will be created for UI.
Step - 8 : Create a file inside the directory "widget" named "PracticeScreens.xml".
Contents of this file can be taken from any of the existing component e.g. example component.
As now onwards you will be able to create screens views so an important reading at this place will be Best Practices Guide . On this page there links to following:
- HTML and CSS Best Practices
- Managing Your Source Differences
- Methodology Recommendations
- User Interface Layout Best Practices
All these readings will be really of help.
Very first screen will be like :
<?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>
Step - 9 : Now that we have the basic elements in place lets review the basic flow no matter how large or complex your component gets. First a request will be made by a browser to see a specific resource. Take for example the request:
"localhost:8080/practice/control/main"
1- When ofbiz sees this request it will look at the /practice section first. Because in our ofbiz-component.xml file we said our webapps mount point would be /practice. Now ofbiz knows that our practice component will handle the rest of the request.
2- Ofbiz will then look at our controller.xml file. Inside our controller.xml file we have request-maps and view-maps. If it finds a view-map with the name 'main' it will go there. The request-map can either specify a view, or as we will see later an event or a service. If it specifies a view it will look further down in the controller.xml file and see if there is a view-map with the name specified by the value tag in the request-map.
3- For now we will keep it simple and assume that all the views go to a type=screen. If this is the case then the page tag will specify a path to a screen definition file as well as a screen name to display after the "#" sign.
xml" in for the location and you will see why in a while.
Step - 5 Create a file named "controller.xml" (used by ofbiz webapp controller) This file will be small and simple at first but will grow as we add functionality later on. For now insert the following code:
<?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-2008 The Apache Software Foundation</owner>
<!-- 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>
Step - 6 : Move up one level and create a new directory named 'error'(hot-deploy/practice/webapp/practice/error).
Step - 6.a : Create a file error.jsp inside the "error" directory. Contents of this file can be taken from any of the existing component e.g. example component.
The location of your error page will be specified in the beginning of your controller.xml file like <errorpage>/error/error.jsp</errorpage> . You will need to make or copy over a /webapp/practice/error/error.jsp page to show an error message to the user.
Step - 7 : Create a sub-directory inside your component directory "practice" named "widget"(hot-deploy/practice/widget).
This directory will contain your forms and screens which will be created for UI.
Step - 8 : Create a file inside the directory "widget" named "PracticeScreens.xml".
Contents of this file can be taken from any of the existing component e.g. example component.
As now onwards you will be able to create screens views so an important reading at this place will be Best Practices Guide . On this page there links to following:
- HTML and CSS Best Practices
- Managing Your Source Differences
- Methodology Recommendations
- User Interface Layout Best Practices
All these readings will be really of help.
Very first screen will be like :
<?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>
Step - 9 : Now that we have the basic elements in place lets review the basic flow no matter how large or complex your component gets. First a request will be made by a browser to see a specific resource. Take for example the request:
"localhost:8080/practice/control/main"
1- When ofbiz sees this request it will look at the /practice section first. Because in our ofbiz-component.xml file we said our webapps mount point would be /practice. Now ofbiz knows that our practice component will handle the rest of the request.
2- Ofbiz will then look at our controller.xml file. Inside our controller.xml file we have request-maps and view-maps. If it finds a view-map with the name 'main' it will go there. The request-map can either specify a view, or as we will see later an event or a service. If it specifies a view it will look further down in the controller.xml file and see if there is a view-map with the name specified by the value tag in the request-map.
3- For now we will keep it simple and assume that all the views go to a type=screen. If this is the case then the page tag will specify a path to a screen definition file as well as a screen name to display after the "#" sign.
*Step - 10 :*Now its the time to run you first practice application :
Start server by : java -Xmx256M -jar ofbiz.jar (the -Xmx256M command just ensures that the program has enough memory)
Then hit the url http://localhost:8080/practice/control/main in your browser.
Browser should show "This is first practice"
...
Step - 3 : Create new screen by name personForm and include this list form in it.
Step - 4 : Do the needful for showing this screen in controller.xml.
Now run the application again and observe the difference.
Till Now you have worked on controller requests mappings, Screen widget, form widget, Decorator, Menus, bsh, ftl.
Create main Decorator for decorating this application:
Step - 1 : Create screen by name "main-decorator" in CommonScreens.xml file.(Take reference from CommonScreens.xml file of Example component.)
Step - 2 : Now include this decorator in CommonPracticeDecorator screen which you are already having.
Now run it again and see the difference.
Now its the time to show practice application in the app bar :
Step - 1 : For this just make app-bar-display="true" in ofbiz-component.xml file.
Restart the server then run it again you will find practice application in app bar.
Create UI Labels:
Step - 1 : For this create directory by name "config" in your component directory i.e. "practice".
Note: -Here remember to create an entry for the config directory in your ofbiz-component.xml file.
which will be : <classpath type="dir" location="config"/> means you have to place the config directory on the classpath to access configuration files.
Step - 2: Now create a file by name PracticeUiLabels.xml and create some of the ui labels for practice applicaton. (take reference from ExampleUiLabels.xml). Here remember one thing whenever you make a change in UiLabels then you have to restart the server for having the changes in effect. At first create only 2 ui labels like
<property key="PracticeApplication">
<value xml:lang="en">This is first practice</value>
</property>
<property key="PracticeCompanyName">
<value xml:lang="en">OFBiz: Practice</value>
</property>
Step - 3: Include this Ui Label resource in your main decorator screen which you created earlier and use these one or two Ui labels which you are having now.
Step - 4 : Use those 2 ui labels at appropriate places.
Note : Always search first for any existing Ui label in ofbiz and if you don't find it there then only create new one.
Now its time to make this practice application secure by checking authentication (user login):
Step - 1 : Take reference from ExampleMenus.xml file for having login and logout options in your menu.
...
in it.
Step - 4 : Do the needful for showing this screen in controller.xml.
Now run the application again and observe the difference.
Till Now you have worked on controller requests mappings, Screen widget, form widget, Decorator, Menus, bsh, ftl.
Create main Decorator for decorating this application:
Step - 1 : Create screen by name "main-decorator" in CommonScreens.xml file.(Take reference from CommonScreens.xml file of Example component.)
Step - 2 : Now include this decorator in CommonPracticeDecorator screen which you are already having.
Now run it again and see the difference.
Now its the time to show practice application in the app bar :
Step - 1 : For this just make app-bar-display="true" in ofbiz-component.xml file.
Restart the server then run it again you will find practice application in app bar.
Create UI Labels:
Step - 1 : For this create directory by name "config" in your component directory i.e. "practice".
Note: -Here remember to create an entry for the config directory in your ofbiz-component.xml file.
which will be : <classpath type="dir" location="config"/> means you have to place the config directory on the classpath to access configuration files.
Step - 2: Now create a file by name PracticeUiLabels.xml and create some of the ui labels for practice applicaton. (take reference from ExampleUiLabels.xml). Here remember one thing whenever you make a change in UiLabels then you have to restart the server for having the changes in effect. At first create only 2 ui labels like
<property key="PracticeApplication">
<value xml:lang="en">This is first practice</value>
</property>
<property key="PracticeCompanyName">
<value xml:lang="en">OFBiz: Practice</value>
</property>
Step - 3: Include this Ui Label resource in your main decorator screen which you created earlier and use these one or two Ui labels which you are having now.
Step - 4 : Use those 2 ui labels at appropriate places.
Note : Always search first for any existing Ui label in ofbiz and if you don't find it there then only create new one.
Now its time to make this practice application secure by checking authentication (user login):
Step - 1 : Take reference from ExampleMenus.xml file for having login and logout options in your menu.
Targets for these options will be available from "component://common/webcommon/WEB-INF/common-controller.xml", which we have to include in our controller.xml.
or you can do these entries in your controller.xml file under <!- Request Mappings ->
| Code Block |
|---|
<!-- Security Mappings -->
<request-map uri="checkLogin" edit="false">
<description>Verify a user is logged in.</description>
<security https="true" auth="false"/>
<event type="java" path="org.ofbiz.webapp.control.LoginWorker" invoke="checkLogin" />
<response name="success" type="view" value="main"/>
<response name="error" type="view" value="login"/>
</request-map>
<request-map uri="login">
<security https="true" auth="false"/>
<event type="java" path="org.ofbiz.webapp.control.LoginWorker" invoke="login"/>
<response name="success" type="view" value="main"/>
<response name="error" type="view" value="login"/>
</request-map>
<request-map uri="logout">
<security https="true" auth="true"/>
<event type="java" path="org.ofbiz.webapp.control.LoginWorker" invoke="logout"/>
<response name="success" type="request" value="checkLogin"/>
<response name="error" type="view" value="main"/>
</request-map>
|
These requests are needed to add in your controller only when you have not included any of the other component controller which consist of these requests. So if you have already included common-controller.xml file then you don't need to explicitly do these entries in your controller.
and the same view we have in place can be used for which we have entry in common-controller.xml file we can also have our own:
| Code Block |
|---|
<view-map name="login" type="screen" page="component://common/widget/CommonScreens.xml#login"/>
|
Step - 2 : Make changes in requests in controller.xml file make auth="true" means now these requests needs authentication.
This is first security level which you have implemented.security level which you have implemented. you request should look like :
| Code Block |
|---|
<request-map uri="main">
<security https="true" auth="true"/>
<response name="success" type="view" value="main"/>
<response name="error" type="view" value="main"/>
</request-map>
|
Now run your application and observe the difference. you can login by user name : admin and pwd: ofbiz
Writing CRUD operations:
Create, Update and Delete operations for an entity will be done by services which we will be writing in minilang.
...
Note: At this place you must read http://www.nabble.com/The-fancy-new-entity-auto-service-execution-engine-td18674040.html
. This feature has been recently added against the traditional approach of writing CrUD operations for an entity.
This new feature enables you to just define the services by mentioning the operation you want to perform.Basically just set the engine attribute to "entity-auto" and the invoke attribute to "create", "update", or "delete".
like you can take a look in the following code from services.xml of example component:
| Code Block |
|---|
<service name="createExample" default-entity-name="Example" engine="entity-auto" invoke="create" auth="true"> <description>Create a Example</description> <permission-service service-name="exampleGenericPermission" main-action="CREATE"/> <auto-attributes include="pk" mode="OUT" optional="false"/> <auto-attributes include="nonpk" mode="IN" optional="true"/> <override name="exampleTypeId" optional="false"/> <override name="statusId" optional="false"/> <override name="exampleName" optional="false"/> </service> service> |
engine="entity-auto" invoke="create" play the role for creating the records for the default-entity "Example."
...
So create a file by name build.xml and then compile it. It will create a build directory in your component directory which will be containing all *.jar and class files after compilation. For the content of build.xml file you can refere example component.
For running the simple event don't forget to make an entry for <classpath type="dir" location="script"/> in ofbiz-component.xml file.
For running the java event make an entry <classpath type="jar" location="build/lib/*"/> in ofbiz-component.xml file.
...
Step - 2 : Now you have to create a file by name "eecas.xml" in "entitydef" directory, which will be in your component directory "practice". Eeca definition will come here. (Take reference from eecas.xml of "accounting" component). This will be :
<!-- To create party role whenever a party is created - ->
<eca entity="Party" operation="create" event="return">
<condition field-name="partyId" operator="is-not-empty"/>
<action service="createPartyRoleCustomer" mode="sync"/>
</eca>
...
Create a group service by name "partyGroup" like :
<!- - Group service - ->
<service name="partyGroup" engine="group" auth="true">
<description>Creates a party, person and party role Client</description>
<group>
<invoke name="createPracticePerson" result-to-context="true"/>
<invoke name="createPartyRoleClient"/>
</group>
</service>
...
Step - 2 : Create new screen, form and service for creating a person. Here service will implement the interface. (For creating interface take reference from services_fixedasset.xml of accounting component) it will be like :
| Code Block |
|---|
<!-- Peson Interface -->
<service name="createPersonInterface" engine="interface" location="" invoke="">
<attribute name="firstName" mode="IN" type="String" optional="false"/>
<attribute name="middleName" mode="IN" type="String" optional="true"/>
<attribute name="lastName" mode="IN" type="String" optional="false"/>
<attribute name="suffix" mode="IN" type="String" optional="true"/>
</service>
<service name="createPracticePersonInterfaceService" engine="simple"
location="org/hotwax/practice/PracticeServices.xml" invoke="createPracticePersonInterfaceService" auth="false">
<description>Creates a new Person</description>
<implements service="createPersonInterface"/>
<attribute name="partyId" mode="OUT" type="String" optional="false"/>
<override name="suffix" optional="false"/>
</service>
|
Here we are implementing an interface and overriding the behaviour of the attribute "suffix", which will have effect when this service will be in action.
Implementation of service createPracticePersonInterfaceService will be the same as createPracticePerson.
Don't forget to restart the server after this implementation.
...
That implies that when ever you do a change you need to restart the server to have those changes in effect.
At this place an important reading is at http://docs.ofbiz.org/display/OFBTECH/General+Entity+Overview.
You will rarely find this way to define new entity because you are already having entities there in OFBiz already defined which will be useful for the conduction of your business process. Though you may feel at some place to add more fields to an existing entity so how can you do that? The next step will show you the way how you can extend an entity for your customized needs.
...
This is the simplest form it can be more complex. This will add up one more field to the entity you already have. Now it depends which field you want for your custom needs. Here you can also defined relation of this field with other entities you want. But before doing this you should search extesively may be you will be adding a field for a purpose and there is already a field which will serve the purpose, so be concisous about this. Also go for a extensive study of data model then do this.
For entity engine configuration dont forget to read : Entity Engine Configuration Guide
Conclusion:
If you have followed all the steps and developed practice application from this application then this will really help you in understanding other implementations in OFBiz. These things are basic foundation of working in OFBiz. Now you know that how you can start the development in OFBiz. Don't leave the extra links provided in this tutorial as they will really help you a lot in understanding the things which are there. Parallaly with the development of this application you can watch OFBiz videos which are available at Framework Introduction Videos.
...