THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
This document explains how OFBiz handles screen estate. It will provide an overview of the OFBiz widget system. Understanding the custom widget system is a prerequisite if you want to chance the look and feel of screens in OFBiz. Not only the internal facing screens but also the eCommerce application (the Online store) uses the home-grown OFBiz widget system to render screens. As you probably don't want to run an online store with the default layout that OFBiz comes with, you will need to understand how the OFBiz widget system is designed in order to customize the look and feel of your shop.
There are a couple more scenarious where understanding the OFBiz widget system might be helpful, for example if:
- You intend to implement a different user interface technology for OFBiz, for example JSF, maybe in combination with AJAX.
- You want to adapt parts of the OFBiz UI for smaller screens, for example mobile phones.
OFBiz uses a custom widget system, partially based on the FreeMarker templating engine (http://freemarker.sourceforge.net/). But when trying to understand how to customize both the look and feel as well as the content of screens in OFBiz, FreeMarker essentially comes last. You will need to get your mind around a couple more things before templating comes to play.
Overview
The 'what' and the 'how'
There are two aspects to a screen:
- What data does it show.
- How does it present that data.
A screen is usually displayed as the result of a request. In a webapp this is going to be an HTTP request, for example:
http://www.yourserver.com/partymgr/control/main
Most OFBiz URLs follow that pattern. The first part after the server name selects the webapp which is supposed to process this request. In this case, the request is for the partymgr webapp. The next part, control, determines that this request should be processed by the Controller Servlet. (See the mapping in web.xml in each webapp.) The Controller Servlet uses the control.xml file in the webapp's WEB-INF folder to decide what content to serve in response to this request.
Hint: If you wanted to integrate any functionality into OFBiz which you don't want to base on the Controller Servlet, you can use any URL namespace expect control and map it to your custom servlet.
How the Controller Servlet handles a request
The Controller Servlet is configured using the control.xml file in the WEB-INF folder. That file has three kind of XML elements which are important now:
- handler
- request-map
- view-map
While this is the order in which they typically appear in the control.xml file, let's start with the request-map.
Element: request-map
- Attributes: uri
- Children: security, event, response
The uri attribute is used to match a request-map to the actual request. Kind in mind that the webapp name and control have already been matched by the servlet container to dispatch processing here. Therefore in our example, the remainder of the URL to match here is just main.
The request map for the URI main looks like this:
<request-map uri="main">
<security https="true" auth="true"/>
<response name="success" type="view" value="main"/>
</request-map>
The monspaced}}security{{monspaced element specifies that https is required (monspaced}}https="true"{{monspaced) and that this portion of the application requires proper user authentication and authorization (monspaced}}auth="true"{{monspaced). Parts of the application which do not require either one are the online store, for example.
The security element might intercept the processing of the request. If auth="true" and there is no valid OFBiz user attached to the current servlet session, processing will branch into rendering a login screen to obtain a valid OFBiz user, than return and check if the currently authenticated user has sufficient authorization for this request. (??? Is this really handled here), after that, processing will continue. If the user logged in before and there is a valid OFBiz user available in the session, processing will just continue. Should the request come in as plain HTTP and http="true" is set, the controller servlet will redirect the client browser to the corrsponding HTTPS URL.
In our example (partymgr/control/main) there is no event triggered by this request, so no processing happens in this case, as we do not have an event element. In case there is no processing, an outcome of success is the default.
The outcome of any processing (which is a string) determines which response to the request is rendered and sent back. In our example, there is only one response to choose from, which is:
<response name="success" type="view" value="main"/>
The type of response is a view (type="view") with name name of "main" (value="main"). Don't get confused by the view name being identical to the URI part that the request-map matched. This is just by chance in this case. The view could be named anything, as long as there will be a view-map element with that name.
Note: A view is not the only possible response to a request. We will discuss other potential responses later in this document. Right now, we're up to understanding how an HTML screen is rendered in a webapp in response to an HTTP(S) request.
Element: view-map
- Attributes: name, type, page
Let's look at the view-map entry for the view with the name main:
<view-map name="main" type="screen" page="component://party/widget/partymgr/PartyScreens.xml#findparty"/>
The type of the view is screen (type="screen") and the screen definition is read from the URI "component://party/widget/partymgr/PartyScreens.xml#findparty". The component: protocol is a OFBiz internal mechanism which retrieves just the screen definition for the findparty screen from the file PartyScreens.xml. That file may contain more than one screen definition. So this mechanism primarily serves the purpose of not having to have too many small XML files, which would be the case if a single XML file could contain only one screen definition. You can rather think of such an XML file as a library of screen definition. We will examine that file and its format later.
Element: handler
- Attributes: name, type, class
The information from the view-map element is resolved against the handlers defined by the elements of type handler, usually in the first section of the controller.xml document. As we are rendering a view, we're only interested in handlers of type view, so we do a lookup for a handler with type="view" and name="screen":
<handler name="screen" type="view" class="org.ofbiz.widget.screen.ScreenWidgetViewHandler"/>
The result of the lookup is a Java class - org.ofbiz.widget.screen.ScreenWidgetViewHandler in this case - which is supposed to implement the XYZ interface.
The control servlet will now pass on the processing to the specified view handler by calling the xyz method using the a, b and c as parameters. It's entirely up to the implementation of the view handler to generate the response and write it to the servlet response channel.
Hint: So if you wanted to implement a view handler which is not based on the OFBiz widgets toolkit but using whatever other view technology, as long as it's a servlet based technology, you would have to implement your own ViewHandler class and make it known to the controller servlet by adding a handler element to the controller.xml file. Then you could create one or more view-map elements with the type="yournewhandler" and have any response in a request-map dispatch processing to that view.