Ofbiz Form Widget Cookbook

5/21/2018 Ofbiz Form Widget Cookbook

1/10

THE FORM-WIDGET COOKBOOK========================

This document is a series of HOWTOs on using the OFBIZ form-widget to create forms.

* Important warning about submit button names: Don't name your submit field "submit", because this will cause a bug "button.form.submit is not a function"


2/10

This generates a standard date input with dropdowns to select the hour, minutes, and AM/PM.

* How to display a date/time as text

Sometimes it will appear red, in which case do the following to stop that: Sometimes you want to truncate the hours, minutes and so on to show only the

date (watch out for bsh errors)

* How to default date time fields to now

In general, you can use the ${bsh: } directive to invoke bsh in the form widget to display values. This is one good example of it:

* How to change the style of a form widget

Form widget styles are CSS styles listed in /images/maincss.css and /images/tabstyles.css Two ways: block level and inline style block: equivalent to the styles you'd give to a

, or

inline: equivalent to the styles you'd give to a or

* How to tell the form what map or list to use

* How to pass a parameter on to the "success" view when a form is successfully processed

For example, suppose you have a "createNoteForm" form to create notes and whenit finishes, you want

to continue to "viewParty?partyId=${partyId}". How do you pass the partyId tothe next view-map (viewParty) when the form is submitted? There's a trick to do this:

And in controller.xml:


3/10

The "viewParty" view-map will then be invoked with the partyId in the parameters.

* How to call Java from within a display tag ex: For double quotes ("), use the xml directive "

* How to set the length and maxsize of a text field

* How to make a tooltip box appear above a field when hoving over it

* How to mark a field as required

Change the widget style to something that stands out and maybe add an asterix after the description.

* How to create a drop down

* How to specify default values for a drop down

current="selected" tells it to make the current key selected, so if you're refilling out a form, a selected field will be selected again no-current-key-selected= is used to specify a default value. It can be a literal value ("USD") or a variable ("${currencyUomId"})

* How to make multi column forms

... ...

* How to make a "multi" form to list and operate on many entities at once


4/10

use-row-submit "false" will invoke a multi service for every row. This is the default "true" will invoke a multi service only when the row is checkedsubmitButton

a single submit button at the bottom of the list targetspecify in controller.xml request-map controllerTarget

to invoke serviceName once for each row according to use-row-submit* How to then pass just one field back to the multi-form

What if you need to pass just one field to a multi-form, such as a facilityId?One way (maybe not the best way!) is to put into the form target URL, like this:target="BatchScheduleShipmentRouteSegments?facilityId=${facilityId}"

* How to have each row of a multi-form be selected by default

This is very tricky, but I saw Jacopo do it in commit r 448936, tried it, and itworked! You have to set it in thescreen-widget in the section like this:

* How to reference the description field from a related entity, such as displayingStatusItem.description when the field is statusId (and similar)me="statusId" title="Return Status" widget-style="selectBox">

by default this retrieves the description from the field named "description" - use description="" to format the output: the context will contain the entities fields and their values use key-field-name="primaryKeyId" if the field name is different from the entity's field name (e.g., the field is paymentStatusId but we're looking up StatusItem.statusId, so use key-field-name="statusId")

* Using the sub-hyperlink to put a link next to display entity

Here is an example where you can use display-entity to cross-reference data from a related entity,

then put a link as well:


5/10

* How to get a set of options from StatusItem table

NOTE: This will filter by date if a fromDate and thruDate are present. Make sure that these fields are of type="date-time" and not "date", otherwise you'll get a mysterious class cast exception with Date in the errorlog. If you want to avoid the filter, you can specify:

A good example of this is CustomTimePeriod which has fromDate and thruDate oftype "date", but will crash unless you stop the filter by date. It's good practice to specify filter-by-date if the entity has a fromDate andthruDate just to make it explicit.

* How to turn a field into a link

Use the tag inside of ... with description= for theanchor text on the form and target= for the link to use. Use the target-type="inter-app"when the hyperlink goes to a different webapp (ie, from marketing to party manager).

Ex:

IMPORTANT: use XML notation such as & when entering HTML tag with special

characters such as "&"

* How to disable display/execution of a field with a condition

use-when="true" will cause a field always to display. use-when="false" will cause a field never to display.

use-when is interpreted as beanshell using the current beanshell interpreter context. You can test for variables

from the screen widget that were defined with . You can also invoke Java methods that return a boolean true/false with something like use-when="com.mysite.MyClass.myStaticBooleanMethod(myParameter);"

IMPORTANT: Due to the way beanshell works, testing "foo==null" will return true if foo has not been defined yet! This is because beanshell considers undefined parameters as "void", and void is not consiered to be null. You can see this behavior for yourself by executing this bsh: print("Is foo null? " + (foo==null) + ". I


6/10

s foo void? " + (foo==void));

What if you have a list form and need to access a field from each member of the list? After some (rather blind) trial and error, we found that the magic word is "context", as in: .... this will test "myField" in each element of myList in your use-when

IMPORTANT: Also note that most other form-widget fields that accept ${} notati

on uses FTL markup language, not beanshell. This leads to situations where you have use-when="parameters.get("fieldName")" and later on, description="${parameters.fieldName}"

* How to set the default styles of a form

- headers/titles: - text: - tooltip: (tooltip is the textnext to the input or display fields)

* How to show a list of valid status changes

OFBIZ uses the StatusValidChange entity to control valid status transitions.You can use the StatusValidChangeToDetail and your currentstatusId to control the list of status in a drop down, so the user doesn't try to make an illegal status change:

This is from applications/marketing/webapp/marketing/contact/ContactListForms.xml

Note that current-description tag here needs to be something like ${uiLabelMap.CommonSelectOne} - trying to lookup${currentStatus.description} would just return the current statusId.

* How to fill-in default values on a form

will pre-fill an input form with the values from displayValue. Note that displayValue can either be a Java Map oran OFBIZ GenericValue. This allows you to add new fields to your display form from an OFBIZ GenericValue. Here is a neattrick you can do in beanshell (.bsh):


7/10

value = delegator.findByPrimaryKey("SomeGenericValue", UtilMisc.toMap("keyField", keyFieldId)); displayValue = new HashMap(); displayValue.putAll(value.getAllFields()); displayValue.put("another Field", anotherValue); // etc. etc.

context.put("displayValue", displayValue);

* How to add some descriptive text in the middle of a form

This is a hack, pure and simple. Let's say you want some text in the middle of the same form so there areseparate sections to your form. You can create a "dummy" field with a description of your text and use CSSto make it look like a section divider:

What if you need several lines of this spread throughout your form? Each fieldname is only displayed by theform widget once, so you'll need several slightly different field names, like this:

* How to use the same field or value more than once on the form

Let's say you need to display productId twice on your form, once as productIdand once as the product description.The form widget will only display each field name="" once. You can explicitly set the 'entry-name' attribute (by default the'entry-name' attribute is equals to the 'name' attribute) to make it display the

same field twice.

(Thanks to Jacopo for this tip.)

* How to put in a lookup form with a widget button

In the form widget, use the for the field:

This will put a link to


8/10

The screen appears to be just a regular OFBIZ screen widget definition. The typical lookup screen has two sections: a lookup fields form and a list-of-results form.

The lookup field form is just a regular form, except the entry fields may use instead of to generate the Begins With/Contains/Ignore Case etc. etc. options next to the text entry box The target of this form should be the same as before, ie "LookupProduct"

The list-of-results form is also just a regular list form with the display fields, except for the field which should cause a value to be set back on the original form, you need a tag with target="" attribute to call javascript:set_values()with the values to set, as in:

or:

Note that target-type is very important. It tells OFBIZ not to put the tag in front of it.* How to control how the lookups work

has a default-option attribute and an ignore-case attribute. defa

ult-option is set by default to "like" but can be set to "contains", "equals", and "empty" ignore-case is by default set to "true" but can be turned off and set to "false".

* How to reuse list form for both lookup and list

1. use the use-when directive to check if a field has been set (not just check for null, but actually for its value) 2. do a in the top-level decorator of both your LookupScreens.xml and your CommonScreens.xml

* What if you have a list-name and list-iterator-name for list form?

The list-iterator-name takes precedence over the list-name. (see ModelForm.java renderItemRows method.)

* How to use FTL with form-widget

Right now the best way is to tell the form not to generate the form header ortrailer, and then use the screen widget to piece it together with some FTL. This can be done with a skip-start="true"and skip-end="true" attributes of


9/10

* A word about error messages

Sometimes you'll get a message like:org.xml.sax.SAXParseException: Attribute "widget-style" was already specified for element "field". (Error rendering included form named [MyForm] at location [component://.../MyForms.xml]

BE CAREFUL! It may or may not be that particular form in that Forms.xml file.

* How to select only the fields required for our target service from the input m

ap

If we get our data from a map other than the default, specify it with map-name="otherMap"

* How to select only the fields in a given entity from the input map

* Fancy formatting of list forms: see http://jira.undersunconsulting.com/browse/OFBIZ-655 for some examples of fancy formatting for list forms. Here's a quic example,

* Paginated forms - for when your list is too large and you need [Previous] and[Next] to page through results.Note that pagination is automatic if you set viewSize and viewIndex in your scre

en and set the paginate-target in the form. The rest of these settings are for"customizing" your pagination:


10/10

parameter names for each. If you don't, then all lists will use the VIEW_SIZE and VIEW_INDEX parametersto paginate. This will have the undesired effect of advancing all lists by one page if you click on[Next] for any list!

And while you're at it, give each list a different -target-anchor. This will appendthe anchor, say "bigListForm" to the UR. The result will be,

URL?parameters=foobar#bigLisForm

Then you can use in your ftl to make the [Previous] and [Next] buttons jump to thatpart of the document rather than the top of the page.

If you want a name other than Previous or Next, say for localization, or you'd rather use ""instead, you can specify the text and the CSS style for the buttons with the -label and -style attributes.

* How to select null values

Sometimes you need to do a query like "SELECT ... WHERE value IS NULL". You can

do this with entity-constraintin the form (or screen) widget by using a "null" which is already in the environment, like this:

* List iterator and list

Beginning with OFBiz r 7451 (after opentaps 0.9), the list-iterator-name attribute for is deprecated.list-name="" will now accept either List or EntityListIterator. If you are usin

g the performFind name, thelist-name must equal "listIt".

* How to set the alignment for the content of a column in a list form*

Use the field's attribute widget-area-style.For example, to right align a field:

* You can add a special html characters pretty easily, like this: d

Ofbiz Form Widget Cookbook

Documents

Transcript of Ofbiz Form Widget Cookbook