opentaps Form Macros Documentation

Important Note to all Developers: Please keep this document up to date! If you make changes to the form macros, please also change this document.

Why It Exists

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:

opentaps/opentaps-common/webapp/common/includes/lib/opentapsFormMacros.ftl

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

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">
        <tr class="${tableRowClass(rowIndex)}">
            <@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}"/>

That's all there is to it.

Notation:

@inputHidden name value=""

<@inputHidden name="facilityId">

<@inputHidden name="facilityId" value="${facilityId}">

By convention, these are standard fields for all macros which may use them:

• name: name of the field.
• title: descriptive title of this field, used for rows (ie, "Charge Tax?")
• form: name of the current form, for javascript such as lookup widgets
• list: used for dropdowns. The list of maps or GenericValue entities where the information for the select option elements will be retrieved
• key: used for dropdowns. For each map in "list", a select "option" element is generated, and its value (the "value" attribute) comes from map or GenericValue's entry under the key in "key"; if the value of "key" is empty, then the value of "name" is used as the lookup key instead.
• displayField: used for dropdowns. The value of lookup key used to retrieve (from each map in "list") the display text of the generated option. Note that if "displayField" is empty, then the macro expects a nested string that contains the FTL string that will be used as the option display text.
• default: the default value for the field. For dropdowns, which is the option that will be initially selected by the browser (optional).
• index: used for multi-row submit forms. By default, index is set to -1, which means nothing happens. If set to a different value, then"_o_${index}" is appended to the field name. For example, if you call a macro with name="productId" and index="5", you will get "product_o_5" for the name of the field.
• required: for dropdowns, whether the user is required to select an option from the select box or not (if not, then a "default" option element with an empty value is generated, in addition to the other ones).

The form macros can be divided into two sub-groups: element and row macros. Element macros are for creating a single cell or form element. Row macros use the element macros for creating an entire input row. For example, an element macro might be used to create a date entry field, which can be used in a multi-row or single submit form. A date entry row macro might then use the date entry field element macro to create a row with a title ("Start Date") and the elemnt macro, all wrapped in TR and TD tags.

NOTE: There are many more form macros available. Please look in your opentaps/opentaps-commons/webapp/common/includes/lib/opentapsFormMacros.ftl file for details.

Row Macros

Element Tags

Header and Menu Tags

Other Macros