ofbiz入门教程（2）
Part 1
Create a Component
Create the sub-directory (folder) in hot-deploy/ and name it "practice"(hot-deploy/practice). The directory name should match the new components name that we are creating.
Note : Remember that all customized development is done at this place only.
Create the ofbiz-component.xml file on path hot-deploy/practice and place the following content in it (for reference you can check this file in any other component of OFBiz):
<?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>
Explanation of ofbiz-component.xml
The ofbiz-component.xml file is responsible for letting OFBiz know where resources are at as well as allowing you to add to the classpath.
The 'resource-loader name' can be any string. Here we are setting it as "main". The 'type' tells OFBiz that we will be loading a component.
<resource-loader name="main" type="component"/>
In <webapp> tag, we have different attributes and their purpose is as follows:
<webapp name="practice"
title="Practice"
server="default-server"
base-permission="OFBTOOLS"
location="webapp/practice"
mount-point="/practice"
app-bar-display="false"/>
name :- defines the name of our web application.
title :- This will be the title of the application which will be shown in the top navigation.
server :- This will let OFBiz know what server to use.
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.
location :- This will be the location that is the default base directory for the server.
mount-point :- This is the URL used to access this resource. in this case it would be localhost:8080/practice.
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
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.
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 webapps 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.
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.
Create a file named "web.xml"(web.xml follows j2ee webapp specs). Contents of this file can be copied from any of the existing component e.g. /framework/example component. The Important values to change are the <display-name>, the localDispatcherName, the mainDecoratorLocation and the 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/PracticeScreens.xml</param-value>
<!-- change the path to the following if the above doesn't work for you -->
<!-- <param-value>component://practice/webapp/practice/widget/PracticeScreens.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>
For now just put websiteId as "PRACTICE", you will explanation after some time in this tutorial only.
For now put the value: "component://practice/widget/CommonScreens.xml" in for the mainDecoratorLocation and you will see why in a while. This location is used in pointing to the main decorator location in screens like
${parameters.mainDecoratorLocation}
Which increases the code Independence from changing the path at many places when we need to change the main decorator location. At that time we just need to change the location there only and it will work for all the screens where it has been used. One more advantage of doing this in screens is the purpose of resuability of existing screens which we can use from other components, but it decorate that screen by your decorator only as the same pattern is used at all the places and in all the components to show the mainDecoratorLocation. Concentrate on this when you add decorators in your screens in not too distant future with the development of this application.
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-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"/>
<!-- change the path to the following if the above doesn't work for you -->
<!-- <view-map name="main" type="screen" page="component://practice/webapp/practice/widget/PracticeScreens.xml#main"/> -->
<!-- end of view mappings -->
</site-conf>
Move up one level and create a new directory named 'error'(hot-deploy/practice/webapp/practice/error).
Create a file error.jsp inside the "error" directory. Contents of this file can be copied 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.
Create a sub-directory inside your component directory "practice" named "widget"(hot-deploy/practice/widget). This directory will contain your forms, menus, and screens which will be created for UI.
Create a file inside the directory "widget" named "PracticeScreens.xml". Contents of this file can be copied from any 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.
<?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>
Now that we have the basic elements in place let's 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"
When OFBiz sees this request it will look at the /practice section first. This is 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.
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 request-map with the name 'main' it will use the associated view-map, as follows. 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.
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.
Now its the time to run you first practice application!
Start the server by typing the following at the command line : 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. Your browser should show "This is first practice" as seen below.
Output Screen :
Create a file in the webapp directory "practice" named index.jsp (Contents of this file can be copied from the "example" component). This file is responsible for redirecting the response to control/main if you give a url such as http://localhost:8080/practice/. If you give a url such as http://localhost:8080/practice/unknown/requestit will be redirected to the redirectPath specified in web.xml. In that case, ContextFilter will filter out the request and use the redirect path to redirect the request.
Create a Component
Create the sub-directory (folder) in hot-deploy/ and name it "practice"(hot-deploy/practice). The directory name should match the new components name that we are creating.
Note : Remember that all customized development is done at this place only.
Create the ofbiz-component.xml file on path hot-deploy/practice and place the following content in it (for reference you can check this file in any other component of OFBiz):
<?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>
Explanation of ofbiz-component.xml
The ofbiz-component.xml file is responsible for letting OFBiz know where resources are at as well as allowing you to add to the classpath.
The 'resource-loader name' can be any string. Here we are setting it as "main". The 'type' tells OFBiz that we will be loading a component.
<resource-loader name="main" type="component"/>
In <webapp> tag, we have different attributes and their purpose is as follows:
<webapp name="practice"
title="Practice"
server="default-server"
base-permission="OFBTOOLS"
location="webapp/practice"
mount-point="/practice"
app-bar-display="false"/>
name :- defines the name of our web application.
title :- This will be the title of the application which will be shown in the top navigation.
server :- This will let OFBiz know what server to use.
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.
location :- This will be the location that is the default base directory for the server.
mount-point :- This is the URL used to access this resource. in this case it would be localhost:8080/practice.
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
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.
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 webapps 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.
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.
Create a file named "web.xml"(web.xml follows j2ee webapp specs). Contents of this file can be copied from any of the existing component e.g. /framework/example component. The Important values to change are the <display-name>, the localDispatcherName, the mainDecoratorLocation and the 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/PracticeScreens.xml</param-value>
<!-- change the path to the following if the above doesn't work for you -->
<!-- <param-value>component://practice/webapp/practice/widget/PracticeScreens.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>
For now just put websiteId as "PRACTICE", you will explanation after some time in this tutorial only.
For now put the value: "component://practice/widget/CommonScreens.xml" in for the mainDecoratorLocation and you will see why in a while. This location is used in pointing to the main decorator location in screens like
${parameters.mainDecoratorLocation}
Which increases the code Independence from changing the path at many places when we need to change the main decorator location. At that time we just need to change the location there only and it will work for all the screens where it has been used. One more advantage of doing this in screens is the purpose of resuability of existing screens which we can use from other components, but it decorate that screen by your decorator only as the same pattern is used at all the places and in all the components to show the mainDecoratorLocation. Concentrate on this when you add decorators in your screens in not too distant future with the development of this application.
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-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"/>
<!-- change the path to the following if the above doesn't work for you -->
<!-- <view-map name="main" type="screen" page="component://practice/webapp/practice/widget/PracticeScreens.xml#main"/> -->
<!-- end of view mappings -->
</site-conf>
Move up one level and create a new directory named 'error'(hot-deploy/practice/webapp/practice/error).
Create a file error.jsp inside the "error" directory. Contents of this file can be copied 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.
Create a sub-directory inside your component directory "practice" named "widget"(hot-deploy/practice/widget). This directory will contain your forms, menus, and screens which will be created for UI.
Create a file inside the directory "widget" named "PracticeScreens.xml". Contents of this file can be copied from any 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.
<?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>
Now that we have the basic elements in place let's 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"
When OFBiz sees this request it will look at the /practice section first. This is 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.
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 request-map with the name 'main' it will use the associated view-map, as follows. 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.
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.
Now its the time to run you first practice application!
Start the server by typing the following at the command line : 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. Your browser should show "This is first practice" as seen below.
Output Screen :
Create a file in the webapp directory "practice" named index.jsp (Contents of this file can be copied from the "example" component). This file is responsible for redirecting the response to control/main if you give a url such as http://localhost:8080/practice/. If you give a url such as http://localhost:8080/practice/unknown/requestit will be redirected to the redirectPath specified in web.xml. In that case, ContextFilter will filter out the request and use the redirect path to redirect the request.