Page History

...

Which one is right? It depends on on how much changes you are making. Modifying the following files will allow you to "customize" an application, whereas starting from scratch using an existing application as a template is better for a "custom application."

The Five Files

• application\...\webapp\...\WEB-INF\controller.xml
  • <web-app>
    • change the <display-name>
    • change the <description>

• application\...\webapp\...\index.jsp
  • change nothing

• applicaton\build.xml
  • <project>
    • change the name
  • <target name="init">
    • change value of property "desc"
    • change value of property "name"
  • <target name="classpath">
    • ensure all fileset dir are correctly relative to the location of your app

• application\ofbiz-component.xml
  • <ofbiz-component>
    • change the name
  • <webapp>
    • change the name
    • change the title
    • change the location
    • change the mount point

Now if you were to start OFBIZ and point your browser to mydomain.com/myapp you would see an exact duplicate of the application that you were modeling.

...

From there you need to understand how a page is rendered. It is more detailed than this, but this explanation will suffice for the majority of simple customizations.

1. Client makes a request
2. request (among other things) calls a view (controller.xml)
3. view calls a screen (controller.xml)
4. screen (*Screens.xml) calls some actions and widgets (*.bsh, *Forms.xml, *.ftl, etc)
5. the page is rendered to the client.

The goal with the differences app is to create all of the customizations that you need without touching original OFBIZ code. That way when you update to more current versions, you're less likely to encounter significant conflicts. It makes your application close to being "turn-key".

The Decorator

Most likely the first thing your're going to want to customize is the decoration (the header, which screens are in the leftbar if you want to display a right bar, how the body is displayed, which UILabels you use, etc). For this you need to do two things. (As of revision 5539 you can only do this if your views are using the ecommerce application, it shouldn't be long before all of the applications support this)

• Change the location of the mainDecoratorLocation in web.xml <context-param>
  <param-name>mainDecoratorLocation</param-name>
  **<param-value>component://ecommerce/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>
• Create a screen with name="main-decorator" in the file you specified in the mainDecoratorLocation property (I imagine you'll want to copy an existing decorator screen and modify it rather than start from scratch)

Now your application is an exact copy of the model application with your customized decoration. The reason it's an exact copy is because you have essentially the same controller.xml files in both applications. All of the requests call the same views, which call the same screens, which in turn call the same actions and widgets. So now you want to make some more changes.

Customize Screens

• controller.xml
  • <view-map>
    • change the name if necessary
    • change the location to a *Screens.xml file inside custom application
• *Screens.xml
  • create a new screen
  • remember they can call .bsh, .ftl, and forms from other applications
  • if you want to use a custom .ftl or .bsh be sure to us a similar directory structure as the original file so you can make easy comparisons when you update.

...

That's really all there is to it. If you call new services from the requests, make sure you create your file in component://myapp/servicedef/services.xml and make sure it gets loaded in the ofbiz-component.xml file. Same with ECAs. Need new classes, create them in your src directory and don't forget to build them with ant. Keep in mind two things and maintanence of your custom application will be easier and less error prone.

1. REUSE REUSE REUSE. (If you don't change it, you don't have to maintain it, so don't change things just to change them)
2. Only change copies of the OFBIZ files that are in your custom application

A David Jones's tip