How to use the opentaps Form Macros

Why Use Form Macros

Many of us are constantly creating forms for our users to enter and display data. Most of those forms share common elements: text input fields, date input fields, drop downs, etc. etc. Wouldn't it be nice to have a tool which helps you make and manage? At the same time, the tool should still give you control over the design of your form, so you don't end up with an ugly cookie-cutter look for all your forms. You should be able to add form elements in HTML when they are appropriate, or completely change the layout and design of your forms by just changing the HTML.

The opentaps Form Macros were created for this reason: to make writing forms easier, while still giving you control over the final layout. The macros help you design form elements such as input rows, select boxes, and date fields more efficiently but do not force you to use them--you can write some form elements with them, write others in HTML or anything else. It is completely written in Freemarker and can be accessed from any Freemarker page, so you can combine opentaps Form Macros, HTML, Freemarker in the same form. It is also easily extend or re-skin: you edit the form macros file and make your changes there, without updating XSD definitions or Java code.

How It Works

First, you must make sure that the opentaps form macro importing tool is loaded. This can be done by including the following code in your beanshell (.bsh) script for your page. They can be put in main-decorator.bsh so that the form macros would work for your entire webapp:

   loader = Thread.currentThread().getContextClassLoader();
   globalContext.put("import", loader.loadClass("org.opentaps.common.template.freemarker.transform.ImportTransform").newInstance());
   globalContext.put("include", loader.loadClass("org.opentaps.common.template.freemarker.transform.IncludeTransform").newInstance());

The form macros are located in an FTL file in your opentaps-common directory, hot-deploy/opentaps-common/webapp/common/includes/lib/opentapsFormMacros.ftl

To use it, simply include the form macros in your Freemarker (FTL) page, like this:

<@import location="component://opentaps-common/webapp/common/includes/lib/opentapsFormMacros.ftl"/>

<@import /> is an opentaps Freemarker extension which allows macros to be imported into the current context from any file in your opentaps applications.

IMPORTANT: There must be no spaces in your file path!

Now you are ready to use the form macros, like this:

   <#list inventoryProduced as inventoryItemProduced>
       <#assign inventoryItem = inventoryItemProduced.getRelatedOne("InventoryItem")/>
       <#if inventoryItem.inventoryItemTypeId == "SERIALIZED_INV_ITEM">

<@displayLink href="EditInventoryItem?inventoryItemId=${inventoryItem.inventoryItemId}" text="${inventoryItem.inventoryItemId}"/> <@display text="${inventoryItem.productId}"/> <@inputText name="serialNumber_o_${rowIndex}" default="${inventoryItem.serialNumber?if_exists}"/> <@inputHidden name="_rowSubmit_o_${rowIndex}" value="Y"/> <@inputHidden name="inventoryItemId_o_${rowIndex}" value="${inventoryItem.inventoryItemId}"/> In this example, we've mixed Freemarker directives (if, list, assign), HTML and CSS tags (tr, class), and opentaps forms macros (displayLink, display, inputText, inputHidden.) The form macros are just macros for generating the appropriate HTML around the parametrized fields nad values. The list of form macros and how to use them are given in the API below. That's all there is to it.

Form Macros API

To see what form macros are available, go to Form Macros API documentation for general overview, then look in hot-deploy/opentaps-common/webapp/common/includes/lib/opentapsFormMacros.ftl in your version of opentaps.