Best Practices Guide

Written By: David E. Jones, jonesde@apache.org

Table of Contents

• Introduction
• General Concepts
• Data Layer
• Logic Layer
• Presentation Layer

...

• HTML and CSS Best Practices
• Managing Your Source Differences
• Methodology Recommendations
• User Interface Layout Best Practices

Introduction

This documents presents best-practices for development and architecture related to The Open For Business Project.

...

Always implement your service using the easiest and most appropriate language or tool. You can implement services with many different languages including Java, BeanShell Groovy, Beanshell or any BSF compliant scripting language (Jython, Jacl, JavaScript, etc), OFBiz Workflow Engine processes, OFBiz MiniLang simple-methods, and various others. Additional languages can be supported by writing simple adapters.

Most services are oriented around data mapping and handling and the simple-method is the best way to implement them. Writing a service with a simple-method is the primary best practice for writing a service. There are some cases where simple-method scripts are too restrictive or cumbersome, and in those cases a more general purpose language should be used. The two recommended secondary best practice tools for this case are Groovy and Java, with Groovy being preferred because of flexibility/extensibility features, no recompilation needed to test changes, and various other benefits.

Always call remote logic through the Service Engine. You can call remote services through various mechanisms including HTTP, SOAP, JMS, and others. You can also add remote service invocation mechanisms by creating a simple adapter.

...

Always let the Control Servlet configuration handle decisions about the appropriate response to take for a request given the result string from an event. In most cases the response will be the generation of a view, but sometimes it will make sense to chain requests together to acheive achieve logic reuse or more advanced flow control.

...

View data preparation logic should be specified as actions in the XML screen definition or if necessary implemented in a dynamic scripting language such as Groovy, JavaScript, BeanShell, Jython or Jacl to make it easy to modify the user interface on the fly. Generic data retreival retrieval should be implemented as services which should be called from these dynamic action scripts. This makes it easier to share and reuse this functionality in multiple pages and in other types of user interfaces.

The best practice in OFBiz for data preparation is to use one of these tools:

1. for simple data retrieval: the entity* tags in the screen action section
2. for more complex data preparation and manipulation: simple-method or Groovy
3. for larger data preparation and more reusability: implement a service and call in a screen action tag

When preparing data in view actions you should make the data available to the view template by putting it in the "context" object. All attributes in the context object will be made avilable available in the context of the template, if the template languge language supports that.

While the use of JSP is not recommended in OFBiz, it is supported. Note that when using JSP for a view template you cannot use JPublish the Screen Widget so the actions facility will not be available. Our recommendation for JSPs is to have a single scriplet scriptlet at the top of the page that prepares the data. In this case try to call worker services or worker Java methods to do most of the work and to keep as much logic as possible out of the page.

...

The best-practice template engine that we recommend for HTML and other text generation is FreeMarker. It is like Velocity from Jakarta, but much more flexible and fits in nicely with other OFBiz Core Framework tools. Rather than running FreeMarker templates directly we strongly recommend using the OFBiz Screen Widget so that actions can be associated with screens and they can be decorated with common templates. We'll describe how to best use this below.

The view presenation presentation templates should always be kept as simple as possible and common content such as headers, footers, sidebars, and so on should be added at run-time using the decoration pattern. The template file that should be used to decorate each page is specified in the screen definition XML file.

...