• What is OFBiz?
• Roadmap
• Demos
• Tutorials
• Training Video
• Downloads
• Accounting/GL
• CRM/SFA
• Resources
• Mentoring
• opentaps CD

Extending your web app with screen-widget, decorator, and actions

by Si Chen

IMPORTANT: Please read about the recent changes before attempting this tutorial.

Now you've made your first web application. In the real world, though, you'd probably be creating applications with many, many pages which performed useful tasks. The OFBiz screen-widget allows you to create web apps which stitch together many pieces ("decorator pattern") and perform actions such as gathering and analyzing data ("actions.")

Throughout this tutorial, click on any image to enlarge it.

In this tutorial, we'll extend Hello World 1 to a second application, hello2. The first step is to copy hello1 into hello2 and change the names of the "hello1" webapp to "hello2", as well as references to it in ofbiz-component.xml:

Creating Screens

The OFBiz screen-widget is used to put together complex pages with many smaller pieces of display elements. (If you've used earlier versions of OFBiz, it replaces JPublish and the regions framework.)

The first step is to create an includes/ directory in your webapp and create the headers and footers there. If you want to use a common stylesheet and graphics, this is a good place to put it. You will also want to remove the same code from the main.ftl:

The second step is to stitch these pieces together using the screen-widget. Create a widget/ directory inside hello2/, next to webapp/. Inside widget/, create an XML file to define your screens:

sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello2> ls -l
total 4
-rw-------  1 sichen users 1747 2005-06-09 16:28 ofbiz-component.xml
drwxrwxr-x  3 sichen users   72 2005-06-09 16:07 webapp
drwxr-xr-x  2 sichen users   80 2005-06-09 17:02 widget
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello2> ls -l widget/
total 4
-rw-r--r--  1 sichen users 720 2005-06-09 17:02 HelloScreens.xml

The final step is to reference tour screen definition rather than the Freemarker template directly in your controller:

Now we're done! If you type in

http://localhost:8080/hello2/control/main

By allowing you to compose a page with many pieces, the screen-widget will help you as you build more complex applications.

Decorating Your Page

The decorator pattern allows you to piece a page together using many different sections, thus allowing you to reuse those sections across multiple pages. For example, you can have separate pages for your header, navigation bar, news panels, promotion offers, and footers.

For example, let's say that you wanted to create several pages with the same header and footer but different content. The screen-widget allows you to do this by creating multiple screens which re-use the same display element. To get started, first we create multiple requests and views in the controller.xml:

Next we create the additional pages and screens. In the screen-widget XML file, you can just copy each screen definition and change main.ftl to your page.

In the pages themselves, you no longer have to put in repetitive elements.

Note the <@ofbizUrl> tag in header.ftl (bottom.) This is used to generate your URL. These pages look like this.

As you build larger sites, however, repetitive layout commands can be a maintenance problem. Fortunately, the OFBiz screen-widget goes a step further by allowing you to define a template which is repeated for many screens. You do this by declaring a <decorator-section-include> inside a template screen (usually called a "CommonDecorator"). Then, in your other screens, you reference the template screen with a and declare their own content with a tag. This is what it would look like:

The web pages generated look the same as before. If, however, you got a request to, say, put a legal disclaimer on all the pages, it would be as simple as modifiying the layout of the CommonDecorator.

Adding Actions

Now you've seen the basics of building static sites with OFBiz. The next step is to mix in dynamic content. Typically, most web scripting languages allow you to put code on the page to do this. Freemarker allows you to do this as well, which is how I put in a date in the header. The creators of Freemarker, however, discourage this because they felt it would lead to pages which are overly complicated.

OFBiz avoids this problem by separating layout from actions or code, which gather and prepare data. By separating actions and presentation of a web page, you can allow separate people with different skills (programming vs design) to work on a web page. You can also reuse the same code for generating multiple views, such as a web page or a PDF of the same content.

To do this, you would first create an actions/ directory inside your WEB-INF directory. Then you would put in a beanshell script which would perform your actions. The beanshell script here is like a Java servlet, only it is dynamically typed and interpreted (rather than compiled.) Also, if you want to put objects back into the Freemarker pages to be displayed, you would put them into a Map (already created for you) called "context". Finally, you would need to declare this action for your screen, a new one that I've created here:

I also created an entry for it in controller.xml.

A lot is happening here. In HelloScreens.xml, you created a screen which uses people.ftl for presentation and people.bsh for actions related to the page, which in this case is data gathering. people.bsh is a simple script which got a delegator, looked up all the Person entities, and then put them into the context. (OFBiz puts this delegator into the request for you.) Finally, on the bottom, people.ftl displays all the names. (This is a good example of some of Freemarker's syntax.) And this is what you will see.

There is also a way to do basic lookups like this directly in the screen-wdiget using tags like <entity-one> instead of creating a separate script and writing Java code. I'll leave it for you to explore this.

Also, since there is a delegator object, can you just write to the database and do all your business logic in .bsh scripts? The answer is yes, but for larger applications this is not considered good practice. In fact, this is never done in any of the OFBiz applications.

Click to see the files created in this tutorial.

Summing Up

This should give you a basic idea on how to build web applications with OFBiz. There are many more tools available to help you, and I will leave it to you to explore the existing OFBiz applications to see what else you can do.

One tool that can be very helpful is the form widget, which allows you to generate standardized forms automatically based on the fields from your data model or from your business logic services. See this wiki page for more details.