Opentaps Form Macros API Reference
This document provides a reference for each of the available macros
and functions available in opentapsFormMacros.ftl. There are various
kinds of macros available:
| Building Blocks |
Macros that generate basic display and input elements. Those
that generate plain HTML are called display macros. Those that
generate <input> elements are called input macros.
For convenience, these macros also come with Cell and Row flavors.
A Cell macro will wrap the display or input in <td>.
All Cell macros allow you to specify the class of this <td>
using a parameter blockClass. (Some don't yet.. this is TODO)
A Row macro will have a title argument and it will
generate a two column row with the title in the first column and
the display or input in the second column. The title class is
titleCell by default, but can be overridden with the
titleClass parameter.
|
| Input Macros |
The Building Block input macros have a number of convenience
features built into them.
The name parameter refers to the name of the input.
All input macros accept an index parameter. If this parameter
is greater than or equal to 0, then the input will be treated as a
multi sumbit input element. That is, the field name will have a
_o_${index} suffix.
Input macros that have a default parameter have a special
behavior with regards to default values. If the default value
is specified, then it will use that value as the default instead
of rendering an empty field. If it is not specified, it will
attempt to look for an existing value in the parameters map.
|
| Larger Building Blocks |
These macros generate more complicated form inputs or display HTML.
For example, there is a macro to generate a state and country
dropdown which has the ability to change the states when the country
is changed. These macros may be composed of other Building Blocks.
|
| Global Functions |
Functions in FTL are a lot like macros, but they can be invoked from
with the ${} substitution notation.
|
| Convenience Macros |
There are a variety of convenience macros to perfom common things,
such as rendering text in a tooltip style.
|
Each of these macros also have Cell and Row versions. For example,
the <inputText> macro is also available as <inputTextCell> and
<inputTextRow>. The Row version has
an additional required parameter named title.
<@display text="" class="tabletext" style="">
Displays the given text in a <span> with default class tabletext. It
also accepts a CSS style specification. This macro is generally not
that useful, but it is used by other macros to generate content.
The Row and Cell versions are somewhat more useful.
<@displayLink href text class="buttontext">
Generates a hypertext link with the given href. The link text is
specified by text argument. It will transform the href depending
on what the string starts with:
- String starts with "javascript:" - No wrapping
- String starts with "/" - Wraps in <@ofbizUrl> and passes externalLoginKey. (e.g., "/warehouse/control/main")
- All other cases: Wraps in <@ofbizUrl>
<@displayCurrency currencyUomId="" amount=0 class="tabletext">
Renders currency in the current locale. If the amount is negative
the result will be red. If a different class is specified,
negative amounts will still be red.
The Cell and Row versions of this always right align the currency
via the css class currencyCell.
<@displayDate date="" format="DATE_TIME" class="tabletext" style="">
Renders date in locale specific way. The concrete format depends on opentaps settings.
The Cell and Row versions of this have the same meaning as in other macros. The list
of possible values of format is described in the description of the function getLocalizedDate.
<@inputHidden name value index=-1>
Renders a hidden input with the given name and value. This is mostly
useful for making multi-submit hidden inputs, which would otherwise
be clunky to write by hand.
<@inputText name size=30 maxlength="" default="" index=-1>
Renders a text input field with the given name.
<@inputTextarea name rows=5 cols=60 default="" index=-1>
Renders a textarea with the given name.
<@inputSelect name list key="" displayField="" default="" defaultOptionText="" required=true index=-1>
Renders a dropdown. The list is generated from the parameter 'list'.
If this list contains the display field you want to render, then you can
do the following,
<@inputSelect name="statusId" list=statusItems key="statusId" displayField="description" />
If you need to do additional processing of the list to get the text for each field, you can do the following,
<@inputSelect name="statusTypeId" list=statusItems key="statusTypeId" ; option>
<#assign statusType = option.getRelatedOneCache("StatusType")>
${statusType.description}
</@inputSelect>
This macro can generate an empty first row. To do this, set
required to false. If you want to put some text in this empty row,
such as 'please select something', you can specify it with
defaultOptionText.
<@inputLookup name lookup form default="" size=20 maxlength=20 index=-1>
Like <@inputText> but also renders a lookup button next to it.
The name of the lookup, such as LookupPartyName, should be specified
with the lookup parameter. The name of the form must also be
supplied with form.
<@inputCurrency name list currencyName="currencyUomId" default="" defaultCurrency="USD" index=-1>
Renders a small text input and a dropdown of currencies for entering a
currency amount. Pass in a list of Uom entities of type
CURRENCY_MEASURE. Since this macro generates two separate inputs,
the name parameter refers to the text input, where the amount is
entered, and the currencyName refers to the name of the currency
dropdown. This macro might be simplified in the future since it's
rare that such flexibility is required.
<@inputSubmit title onClick="submitFormWithSingleClick(this)">
Renders a form submit button whose default onClick action is to prevent
doubleposting. The title parameter is the button text.
You may want to override onClick to do something fancy.
Note that onClick is case sensitive.
<@inputButton title onClick="">
Renders a button with text from the title parameter.
This is useful when you want a form control with an onClick handler.
Note that onClick is case sensitive.
<@inputIndicator name required=true default="" index=-1>
Renders a Y or N dropdown for indicator fields. Set required
to false if you want to allow a null value.
<@inputDateTime name default="" popup=true weekNumbers=false onUpdate="" onDateStatusFunc="" linkedName="" delta=0>
Renders a date time input with separate fields for hours, minutes, and AM/PM.
<@inputDate name default="" size=10 index=-1 popup=true weekNumbers=false onUpdate="" onDateStatusFunc="" linkedName="" delta=0>
Renders a date input.
<@inputSelectTaxAuthority list defaultGeoId="" defaultPartyId="" required=false>
Renders a special tax authority dropdown. This is rarely used, mostly
for generating invoice items and tax authority lists.
<@inputState name="stateProvinceGeoId" countryInputName="countryGeoId" address=<>>
Renders a dropdown of states for the default application country. This
dropdown is AJAX enhanced and will change to match the states or
provinces of the selected country from the dropdown specified
by
countryInputName. This macro comes in Cell and Row flavors.
If you want, you can pass in an address Map or GenericValue. The
state of this address will be used to select the default value.
<@inputCountry name="countryGeoId" stateInputName="stateProvinceGeoId" address=<>>
Renders a dropdown of countries. The default country is determined
from the application properties
defaultCountryGeoId.
This dropdown is AJAX enhanced and will cause the state dropdown
specified by
stateInputName to change to match the selected
country. This macro comes in Cell and Row flavors.
If you want, you can pass in an address Map or GenericValue. The
country of this address will be used to select the default value.
<@inputStateCountry stateInputName="stateProvinceGeoId" countryInputName="countryGeoId" address=<>>
Renders the <@inputState> and <@inputCountry> dropdowns together. Not
really that useful, but it's here for legacy support. This macro
comes in Cell and Row flavors.
<@inputConfirm title href="" form="" confirmText=uiLabelMap.OpentapsAreyouSure class="buttonDangerous">
Renders a special link that will bring up a confirmation dialogue. If the user confirms the dialgoue, then the action will proceed.
This macro may be linked to a form or it can be standalone. If the
form is speficied, then a form.submit() action will take place
when the user confirms. If a href is supplied, then the user
will be sent to that link.
<@inputHiddenRowSubmit index submit=true>
Renders the special hidden variable that controls whether a given
row will be processed in a multi form. If you are making a multi
input form, you must call this macro for each row. If for some
reason you want to disable the row with the macro, you can
specify submit to false, and the row will not be procesed.
tableRowClass( rowIndex, rowClassOdd="rowWhite", rowClassEven="rowLightGray" )
This function returns the value of rowClassOdd if the index is
even, otherwise rowClassEven. Yes, this is a little backwards
and will probably be fixed. It is used as follows,
<#list fooList as foo>
<tr class="${tableRowClass(foo_index)}"></tr>
</#list>
getLocalizedDate( date, format="DATE_TIME", encode=false )
Function returns string representation of date and/or time in the localized format.
The concrete format depends on opentaps settings.
Arguments:
date - Timestamp or Date (Caution: variable of type Date may be only used jointly with DATE_ONLY format)
format - one of the DATE(e.g. 02/15/08), DATE_TIME(e.g. 02/15/08 01:15 PM), TIME(e.g. 01:15 PM) and DATE_ONLY(like DATE for Date objects).
encode - boolean argument that tells the function encode whitespaces, e.g. 02/15/08%2013:15. Should be true if result of function is embed in URL.
getLocalizedDate is internally used in <@displayDate/> macro.
Snippets:
getLocalizedDate(Static["org.ofbiz.base.util.UtilDateTime"].nowTimestamp())
Output: 02/15/08 01:15 PM
getLocalizedDate(fromDate, "DATE")
Output: 02/15/08
<a href="https://localhost:8443/app/control/request?fromDate=${getLocalizedDate(fromDate, "DATE_TIME", true)}>...
Output:<a href="https://localhost:8443/app/control/request?fromDate=02/15/08%2001:15%20PM>...</a>
<@tooltip text="" class="tooltip">
Renders a tooltip. This message stands out and can be used for
notifying the user of important things.
Example of a tooltip.
<@displayError name index=-1>
Renders a message if there is an error for the given field name
(and index if a multi-form). The css class is errortooltip.
This is used with the
UtilMessage.addFieldError() methods. A form field is not required,
this can be used to render messages anywhere on the screen. Sample
use case:
// in a bsh file called before the FTL
UtilMessage.addFieldError(request, "foo", "OpentapsError_PermissionDenied");
<!-- in the FTL file -->
<@displayError name="foo" />
The output will be:
Sorry, you do not have permission to perform this action.