OFBiz Tutorial – Introduction to OFBiz Widgets

Jacopo CappellatoPublished: Updated:

OFBiz is a broadly-scoped, powerful tool for open source ERP and e-commerce.  Whether your project is a simple e-commerce shopping cart or a complex ERP implementation that includes custom order management, multi-channel integrations, and accounting, ease-of-use for the developers implementing your system translates directly to your bottom line.

The following OFBiz tutorial is technical in nature.  If you are a developer, enjoy!  If you are a manager, suggest that your developers have a look.  The OFBiz Widget goes a long way in saving you time — and money — in your open source e-commerce and ERP projects.

And remember: HotWax Media provides a complete set of OFBiz services, from business analysis through system design, UI design, and complete implementation.  So feel free to contact us today and leave the heavy lifting to us!

The OFBiz Widget is one of the core components of the OFBiz framework, its main goal is the definition and rendering of the OFBiz user interfaces.

Each widget represents a reusable user interface element, that can be included and extended by different applications.

The widgets allow to define, using a simple xml language, user interfaces elements like screen, menus, forms, trees in a platform and output independent format; the widgets are also tightly integrated with other key components of the OFBiz framework, like the “content”, “service” and “entity” engines, so that data preparation logic programming is greatly simplified and consistent with the rest of the framework.

At runtime, when a widget is to be rendered, its widget definition (in xml) is passed to the proper widget renderer that transforms it in the right output format: an html document, a PDF document, a comma separated value file etc…

Various renderers are available in OFBiz including the html, pdf, xml, text and now the csv renderer. The html renderer is widely used to render each and every screen of the applications, the pdf renderer is used for PDF documents, bar codes and PDF email attachments, the xml renderer is used to generate Microsoft Excel compliant xml exports, the csv is for exporting comma separated values files.

In the past, each renderer was implemented by a complex set of Java classes and the output code was embedded in its methods; this layout had some relevant cons: the code was difficult to maintain and customize because html/xml/xsl-fo code was embedded in Java methods, building new renderers was a complex task.

As a consequence very few OFBiz  committers were able to fix and enhance the widget code in the framework and the html layout of the output was not very good because web designers had a hard time dealing with the html code embedded in Java classes.

For these reasons, recently, all the complex, difficult to maintain and customize code of the renderers in OFBiz has been refactored by HotWax Media, by introducing the concept of a generic Macro Widget Renderer: a unified renderer that delegates the actual implementation of the output to a set of Freemarker macro calls. Now all the output depended code is in easy to modify/extend/customize Freemarker templates: web designers can edit the templates for a given output and see the results real time without the need to recompile or even restart the OFBiz instance. It is also incredibly easy to implement new special purpose renderers, to get new types of output/export for the widgets: in fact we expect that in the future the set of output formats available for the widgets will grow.

The CSV renderer is a good example of the new breed of lightweight renderers: it took few hours to implement and with it now virtually any widget form that represents tabular data can be exported in CSV format.

In short, here are the few steps we followed to implement the new CSV output:

  1. add to framework/widget/config/widget.properties a new section for the renderer
  2. implement the Freemarker macros for the new renderer by copying and modifying the ones of an existing renderer in framework/widget/templates: csvScreenMacroLibrary.ftl, csvFormMacroLibrary.ftl,csvMenuMacroLibrary.ftl, csvTreeMacroLibrary.ftl
  3. add a new entry for the renderer in framework/common/webcommon/WEB-INF/common-controller.xml <handler name=”screencsv” type=”view” class=”org.ofbiz.widget.screen.MacroScreenViewHandler”/>

After this you are ready to use the new renderer by associating, in a controller.xml file, the screen definition with the renderer:

In one of my next posts we will illustrate an example of how the same form can be used to render html code and csv data.

– Jacopo

Jacopo Cappellato About Jacopo Cappellato
Jacopo Cappellato is VP of Technology at HotWax Media and has been involved with the OFBiz project since 2003. He is an OFBiz Project Committer and a member of both the OFBiz Project Management Committee and the Apache Software Foundation.

Comments 10

  1. Avatar for Jacopo Cappellato
  2. Avatar for Jacopo Cappellato

    Thank you Jacques, I am glad you’ve found this article useful!
    The feedback and help from committers and contributors is important to achieve the best results.
    In this specific effort, I would like to specially thank Guo Weizhan because he helped a lot in the implementation phase when he migrated most of the methods of the old Html Renderer to the new renderer’s format.

  3. Avatar for Jacopo Cappellato

    I found this link from ofbiz.apache.org unconsciously. It’s the effort of all contributors, and I just do what I should do. I’m too busy to maintain the problem cause by that change in those days, and thank you for your continuous effort.

  4. Avatar for Jacopo Cappellato
  5. Avatar for Jacopo Cappellato


    I am a student working on ofbiz.We have planned to create three features in ofbiz which i dono exists or not.
    1)Implementing autocomplete in some places like countrylist,statelist etc.
    2)Reducing width of table rows in catalog and other places.
    3)Impplementing iphone interface in ofbiz.

    Now we have created myinstitute component in ofbiz and now we are looking to implement above 3 ui features.Please need some valuable suggestions to implement autocomplete may be steps to modify existing code in ofbiz.

    Below are some of URLS where we need autocomplete:

    Look up Party – This comes in several places. Example URLs are

    I ll be glad see comments and suggestions as early as possible.

    1. Avatar for Jacopo Cappellato


      you will find some good examples of the autocomplete feature already implemented in OFBiz; for example, visit the main page of the “manufacturing” application and then click on the “Create Production Run” button at the top of the screen. You will see a form where the “product id” field is an autocomplete field (e.g. start typing P R O D…)
      Good luck with your studies.

  6. Avatar for Jacopo Cappellato

    Hi Jacopo,
    I am evaluating a variety of ecommerce engines like magento, spree, oscommerce & of cource ofbiz ecommerce.
    There would be variety of promotions as well as affiliate programs, for eg.

    Refer a friend. An email will be sent to the friend(s) and offer them a YY discount voucher off their first order.
    If they place an order, referrer account will be credited with £XX to use on next order.

    Please let me know if its possible to implement such scenario, if yes then please let me know as to how to configure the same in ofbiz ecommerce so that i can evaluate the user friendliness & ease of configuration.

    1. Avatar for Jacopo Cappellato

      Hi Varun,

      the basic components are already available in OFBiz (like promo code etc…) but you will still have to do some (small) customizations to complete the process you are describing.
      I would suggest you to discuss this in the OFBiz user list if you think you need some directions.

      Good luck,


  7. Avatar for Jacopo Cappellato

    Hi Jacopo,

    I would like to know if there’s a way to disable the submit with the key “enter” on XML forms..
    Is a feature that miss? Or I’m doing it wrong?


    1. Avatar for Jacopo Cappellato

      Hi Alessandro,

      I am really sorry for the late reply.
      I don’t think there is anything specific in OFBiz to prevent form submissions with the enter key; however, there are several hints on the web to implement this (just try a research like “how to disable form submit with the enter key”); you will most likely have to put some Javascript in your screen, or if you want this to happen in all the screens, you could simply add it to the screen decorator’s header.

      Kind regards,


Leave a Reply

Your email address will not be published. Required fields are marked *