Form Elements

standard/htmlForm.ftl

In the same fashion as the content elements, SCIPIO form elements are meant as a mean to standardize
the development of complexe forms. The elements follow standard html patterns, with the only difference
being the @field attribute replacing the input tag.

All elements come with additional options, that simplifies their use quite a bit. A good example are the
<@field definitions, where each element are wrapped in containing rows and cells, labels added when defined
and ids set automatically. The use of the SCIPIO elements largely simplify the creation of complexe forms and
standardize the html output for visualization.

Included by htmlTemplate.ftl.

NOTES:

  • May have implicit dependencies on other parts of Scipio API.

Definitions:

asmSelectScript,
dynamicSelectFieldScript,
field,
fields,
fieldset,
form,
getAutoValue,
getAutoValueCfg,
getAutoValueMap,
getDefaultFieldGridStyles,
input,
mapOfbizFieldTypeToScipioFieldType,
mapOfbizFieldTypeToStyleName,
mapScipioFieldTypeToStyleName,
progress,
progressScript,
setAutoValueCfg

Form

macro form

Defines a form. Analogous to <form> HTML element.

Usage Examples

    <@form name="myform">
      <@fields>
        <input type="hidden" ... />
        <@field ... />
        <@field ... />
      </@fields>
    </@form>

Parameters

type (input|display, default: input)
Form type
id Form ID
class ((css-class))
CSS classes on form element itself

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

attribs ((map))
Extra attributes for HTML <form> element

Needed for names containing dashes.

NOTE:
These are automatically HTML-escaped, but not escaped for javascript or other languages (caller responsible for these).

validate ((boolean), default: -implicit-)
If true, adds an explicit default validation script to the form (e.g. jQuery validate)

NOTE:
in many cases forms receive this automatically through submit button even if this is false (through global JS);
this is only needed in special cases.
NOTE:
only works if id or name present

Added 2017-09-29.

inlineAttribs... ((inline-args))
Extra attributes for HTML <form> element

NOTE:
camelCase names are automatically converted to dash-separated-lowercase-names.
NOTE:
These are automatically HTML-escaped, but not escaped for javascript or other languages (caller responsible for these).

name
open
close
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

History

Added explicit validate option (1.14.4).

Progress Script

macro progressScript

Generates script data and markup needed to make an instance to initialize upload progress
javascript anim for a form, with progress bar and/or text.

The server-side upload event for the form must register a Java FileUploadProgressListener in session
for getFileUploadProgressStatus controller AJAX calls.

Parameters

enabled ((boolean), default: true)
If true, disables whole macro

Occasionally needed in templates as FTL workaround.
progressOptions ((map))
Elem IDs and options passed to ScipioUploadProgress Javascript class

In addition, supports:

  • submitHook: one of:

    • formSubmit: The default
    • validate: Use jquery validate
    • none: Caller does manually
  • validateObjScript: If submitHook is "validate", add this script text to jquery validate({…}) object body

    WARN:
    this is NOT js-escaped by the macro – caller is responsible for escaping.

See ScipioUploadProgress javascript class for available options.

htmlwrap ((boolean), default: true)
If true, wrap in @script
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

Progress Bar

macro progress

A progress bar.

Can be animated using Javascript manually or by using progressOptions argument.
Presence of progressOptions activates use of ScipioUploadProgress script for this progress bar by linking it
to a form submit.

Usage Examples

    <@progress value=40/>

    Javascript animation (manual):
    $('#${id}_meter').css("width", "78%");

Parameters

value ((int))
Percentage done
id Custom ID; can also be specified as progressOptions.progBarId instead

The meter will get an id of "${id}_meter".
If omitted, no progress bar per se will be created, but script will still be generated for progressOptions.progTextBoxId.
type (alert|success|info, default: info)
class ((css-class))
CSS classes

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

containerClass ((css-class))
Classes added only on container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

showValue Display value inside bar
progressArgs ((map))
If present, attaches progress bar to an upload form with javascript-based progress

Attaches results to page using elem IDs and options specified via these arguments,
which are passed to @progress macro (see @progress macro for supported options)
progressOptions ((map))
Convenience parameter; same as passing:

progressArgs={"enabled":true, "progressOptions":progressOptions}
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

dynamicSelectFieldScript

macro dynamicSelectFieldScript

Special select field-generating script that dynamically fetches values based on related fields.

Based on the original component://common/webcommon/includes/setMultipleSelectJs.ftl Ofbiz code interface,
which was originally implemented with asmSelect.

IMPL NOTE:
This must support legacy Ofbiz parameters.

Parameters

General
enabled ((boolean), default: true)
If enabled, disables the whole macro

Sometimes needed in templates as FTL workaround.
id Select elem id
title Select title
sortable ((boolean), default: false)
Request for values to be sortable, IF applicable

NOTE:
2017-04-12: this currently does nothing in the standard markup,
but it may be left specified as a preference, for future use.

formId Form ID
formName Form name
relatedFieldId Related field ID (optional)
htmlwrap ((boolean), default: true)
If true, wrap in @script
useDefaults ((boolean), default: true)
If false, will not include any defaults and use explicit options only
Needed only if relatedFieldId specified
relatedTypeName Related type, name
relatedTypeFieldId Related type field ID
paramKey Param key
requestName Request name
responseName Response name
Other
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

History

Added for 1.14.3 to replace and provide some compatibility for code that used @asmSelectScript (2017-04-12).

asmSelectScript

macro asmSelectScript
(DEPRECATED)

Generates script data and markup needed to turn a multiple-select form field into dynamic jquery asmselect.
DEPRECATED: asmSelect came from older Ofbiz but was no longer maintained by the asmSelect authors; ca
use @dynamicSelectFieldScript instead, or <@field type="select" multiple=true> if you don't need
the related-field logic.

Parameters

args
inlineArgs...

Related

@dynamicSelectFieldScript

History

Deprecated for 1.14.3.

Fieldset

macro fieldset

A visible fieldset, including the HTML element.

Usage Examples

    <@fieldset title="">
        Inner Content
    </@fieldset>

Parameters

class ((css-class))
CSS classes

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

containerClass ((css-class))
CSS classes for wrapper

Includes width in columns, or append only with "+".
Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

id Fieldset ID
title Fieldset title
collapsed Show/hide the fieldset
open
close
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

Fields

macro fields

Fields helper that helps modify a set of @field definitions, or group of fields.
Not associated with a visible element, as is @fieldset.
Can be omitted.
May sometimes need multiple of these per form (so @form insufficient for this purpose),
or even multiple per fieldset.

Usage Examples

    <@fields>
      <@field attr="" />
      <@field attr="" />
    </@field>

    <@fields type="default-nolabelarea">
      <@field attr="" />
      <@field attr="" />
    </@field>

    <@fields type="generic" labelArea=false>
      <@field attr="" />
      <@field attr="" />
    </@field>

    <@fields autoValue={"record": myEntity!{}, "defaults":{"field1": "some default value"}}>
      <@field name="field1" />
    </@fields>

Parameters

type (default|inherit|inherit-all|generic|..., default: inherit-all)
The type of fields arrangement.

Affects layout and styling of contained fields.
Scipio standard markup types:

  • default: default scipio field arrangement. This is the type assumed when no @fields element is present.
    Currently, it mostly influences the label area (present for all @field types except submit).
  • inherit:
    SPECIAL VALUE:
    causes the type value (only) to inherit from the current parent container.
    If there is no parent, the default is default.
    This does not affect the other parameters' fallback behaviors.
  • inherit-all:
    SPECIAL VALUE:
    Inherits all parameters (including type) from parent @fields element(s).
    With this, all unspecified args are inherited from parent @fields element if one exists.
    No global style lookups are performed.
    If there are no parents, the regular defaults are used, and the default type is default.
    This is currently the default when no type is specified or empty. If you want to prevent inheritance of other parameters,
    use "inherit", or to prevent inheritance completely, use any other type.
  • default-nolabelarea: default scipio field arrangement for common sets of fields with no label area.
    It expects that @field entries won't be passed any labels except for field types where they may trickle inline into the widget's inline label area.
  • default-compact: default scipio field arrangement for fields that are in limited space.
    By default, this means the labels will be arranged vertically with the fields.
  • default-manual: manual field arrangement. Means field arrangement is custom and field macro and theme should not impose
    Any layout, but may still apply minor low-level default styling choices and non-optional layout fallbacks. caller determines arrangement/layout/label type/etc.
  • default-manual-widgetonly: manual field arrangement without containers. Same as default-manual but with wrappers/containers omitted by default.
  • generic: generic field arrangement of no specific pattern and no specific styling. Means field arrangement is custom and field macro and theme should not
    Make any assumptions except where a default is required. Caller determines arrangement/layout/label type/etc.
NOTE:
For default-manual, generic and similar where styles hash does not specify a label area by default,
to show a label area for a field, it is NOT sufficient to specify label="xxx".
You must specify both labelArea=true and label="xxx". label arg does not influence presence of label area.
This is explicitly intended, as the label arg is general-purpose in nature and is not associated only with the label area (and anything else will break logic);
Generally, @field specifies label as pure data and theme decides where and how to display it.
In the majority of cases, this should rarely be used anyway; use another more appropriate @fields type instead.

labelType (horizontal|vertical|none, default: -type-specific-)
Override for type of the field labels themselves

  • horizontal: A label area added to the left (or potentially to the right) a field, horizontally.
    the implementation decides how to do this.
  • vertical: a label area added before (or potentially after) a field, vertically.
    the implementation decides how to do this.
  • none: no labels or label areas. Expects the @field macro won't be passed any.

labelPosition (left|right|top|bottom|none, default: -type-specific-)
Override for layout/positioning of the labels

Some values only make sense for some arrangements.
labelArea ((boolean), default: -from global styles-)
Overrides whether fields are expected to have a label area or not, mainly when label omitted

Logic is influenced by other arguments.

NOTE:
This does not determine label area type (horizontal, etc.); only labelType does that (in current code).
They are decoupled. This only controls presence of it.
NOTE:
This is weaker than labelArea arg of @field macro, but stronger than other args of this macro.

labelAreaExceptions ((string)|(list), default: -from global styles-)
String of space-delimited @field type names or list of names

NOTE:
radio and checkbox support special names: radio-single, radio-multi, checkbox-single, checkbox-multi

labelAreaRequireContent ((boolean))
If true, the label area will only be included if label or labelDetail have content

This is generally independent of labelArea boolean and other settings.

NOTE:
This will not affect the fallback logic of labels to inline labels (a.k.a. whether the label area "consumes" the label for itself);
otherwise that would mean labels would always be forced into the label area and never inline.

labelAreaConsumeExceptions ((string)|(list), default: -from global styles-)
String of space-delimited @field type names or list of names

List of field types that should never have their label appear in the main label area.
for these, the label will trickle down into the field's inline area, if it has any (otherwise no label).

NOTE:
radio and checkbox support special names: radio-single, radio-multi, checkbox-single, checkbox-multi

formName The form name the child fields should assume
formId The form ID the child fields should assume
inlineItems ((boolean))
Change default for @field inlineItems parameter
checkboxType Default checkbox type
radioType Default radio type
open, close ((boolean))
Advanced structure control, for esoteric cases
ignoreParentField ((boolean), default: false)
If true, causes all fields within to ignore their parent and behave as if no parent
fieldArgs A map of @field parameters that will be used as new defaults for each field call

This is an automated mechanism. The map will be blended over the standard @field defaults before the invocation.
In addition, contrary to the parameters, a map passed directly to @fields will be blended over both the @field defaults
AND over any defaults set in the styles for the given @fields type:
{@field regular defaults} + {fieldargs from styles hash} + {@fields fieldArgs direct arg}

NOTES:

  • This may overlap with some of the existing parameters above. Covers other cases not made explicit above.
  • If set to boolean false, will prevent all custom default field args and prevent using those set in styles hash. Probably never needed.

e.g.

<@fields type="default" fieldArgs={"labelArea":false}>
autoValue ((map)|(boolean), default: -empty/disabled-)
Auto value configuration to be set as globals for children @field and #getAutoValue calls

WARN:
NOT FULLY IMPLEMENTED (2016-07-15)

This enables children @field and #getAutoValue calls to use automatic value lookups using parameters, record and defaults maps, which
are set in globals using this parameter. Disabled by default.
Possible values:

  • as map: if set to a map, all contents are passed as arguments to the #setAutoValueCfg function (setAutoValueCfg(autoValue)), with the exception that if
    the autoValue.autoValue boolean is omitted, @fields assumes and sets it to true (only explicit false will disable auto value; this case is rare).
    See #setAutoValueCfg for available configuration arguments.
  • as boolean: if set to a boolean, it is equivalent to calling setAutoValueCfg({"autoValue":true}), where only defaults are used.

In all cases, the previous global auto value configuration is saved before setting these and is restored after @fields is closed.

NOTE:
Unlike other @fields parameters, this parameter is always inherited unless specifically overridden.
NOTE:
Unlike other @fields parameters, this parameter does not survive screen @render boundaries (only has page/template scope, not request scope).

collapse
collapsePostfix
collapsedInlineLabel
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

mapScipioFieldTypeToStyleName

function mapScipioFieldTypeToStyleName

Maps a scipio field type to a style name representing the type.

Should be coordinated with mapOfbizFieldTypeToStyleName to produce common field type style names.

Parameters

fieldType

mapOfbizFieldTypeToStyleName

function mapOfbizFieldTypeToStyleName

Maps an Ofbiz field type to a style name representing the type.

Should be coordinated with mapScipioFieldTypeToStyleName to produce common field type style names.

Parameters

fieldType

mapOfbizFieldTypeToScipioFieldType

function mapOfbizFieldTypeToScipioFieldType

Maps an Ofbiz field type to a Scipio field type.

Parameters

fieldType

Field

macro field

A form field input widget with optional label and post-input (postfix) content.

@field can be used as a low-level field control (similar to original Ofbiz
form widget macros, but with friendlier parameters) and for high-level declarations
of fields (similar to the actual <field> elements in Ofbiz form widget definitions, but friendlier
and more configurable). This versatility is the main reason for its implementation complexity.

In the high-level role, the macro takes care of label area logic and alignment
such that you will not get fields looking out of place even if they have no label,
giving all the fields in a given form a default uniform look, which can be customized globally.

@field's behavior can be customized for a set of fields using a parent @fields macro invocation
as well as using the global styles hash (preferred where possible). A set of fields may be grouped under a @fields
call with a @fields "type" selected, which will give all fields within it a predefined look
and behavior. This behavior can be set in the global styles hash (preferred) or overridden directly
in the @fields element.

If no @fields element is used, by default @field will behave the same as if it
were surrounded by a @fields element with "default" type, which gives all fields a default
look out of the box.

To use @field as a low-level control, it should be given a parent @fields with "generic" type.

This system can accodomate custom @fields types, but a default set are provided in the scipio
standard markup.

NOTE:
All @field arg defaults can be overridden by the @fields fieldArgs argument.

Usage Examples

    <@field attr="" /> <#- single field using default look ->

    <@fields type="default"> <#- single field using default look, same as previous ->
      <@field attr="" />
    </@fields>

    <@fields type="default-nolabelarea"> <#- specific arrangement needed ->
      <@field attr="" />
    </@fields>

    <@fields type="default-compact"> <#- compactified arrangement ->
      <@field attr="" />
    </@fields>

    <@fields type="default-manual"> <#- use @field as low-level control (also possible: type="generic") ->
      <@field attr="" labelArea=true label="My Label" />
    </@fields>

    <@row> <#- widget-only field: no containers, label area or postfix area, and label automatically inlines as widget label (checkbox label); do everything yourself ->
      <@cell columns=3>My Text</@cell>
      <@cell columns=9>
        <@field type="checkbox" widgetOnly=true label="My Checkbox" name="check1" />
      </@cell>
    </@row>

    <p>My <@field type="input" inline=true name="check1" value="inlined" /> field</p> <#- inlined field: no containers, label area or postfix area, display:inline, no width spanning ->

    <@field attr="" label="My Label" class="+${styles.field_inline!}" /> <#- special form of regular field where the widget element alone is inlined and no spanning, but still has label area and container; widget element receives an inlining class ->

Parameters

General
type (|generic|..., default: generic)
Form element type

Supported values and their parameters are listed in this documentation as
parameter sections (groups of parameters), as there are type-specific field parameters.

  • generic: Means input defined manually with nested content. Mostly for grouping multiple sub-fields, but can be used anywhere.

    Specific field types should be preferred to manually defining content, where possible.
fieldsType (|default|..., default: -empty-)
CONVENIENCE fields type override

By default, this is empty and inherited from parent @fields element.
Specifying fieldsType="xxx" as in:

<@field type="generic" fieldsType="xxx" .../>

is the same as doing:

<@fields type="xxx">
  <@field type="generic .../>
</@fields>
label Field label

For top-level @field elements and and parent fields, normally the label will get consumed
by the label area and shown there. for child fields and some other circumstances, or whenever there is
no label area, the label will instead be passed down as an "inline label" to the input
widget implementation. in some cases, this "inline label" is
re-implemented using the label area – see collapsedInlineLabel parameter.

NOTE:
Presence of label arg does not guarantee a label area will be shown; this is controlled
by labelArea (and labelType) and its defaults, optionally coming from @fields container.
label arg is mainly to provide data; theme and other flags decide what to do with it.
For generic parent fields, label type must be specified explicitly, e.g.
<@fields type="generic"><@field labelType="horizontal" label="mylabel">...</@fields>
NOTE:
label area behavior may also be influenced by containing macros such as @fields

labelContent ((string)|(macro))
Alternative to label arg which may be a macro and allows manually overriding the basic label markup

WARN:
Currently (2016-04-12), unlike the label arg, labelContent will not follow any label inlining logic and
is only used by the label area markup.
NOTE:
Not escaped by macro.

labelDetail ((string)|(macro))
Extra content markup inserted with label (normally after label, but theme may decide)

2016-04-12: This may also be a macro used to generate the label, which must accept a single args map parameter.

NOTE:
If need to guarantee post-markup label content, may also use postLabelContent (lower-level control).
NOTE:
Not escaped by macro.

labelContentArgs ((map))
Optional map of args to be passed to labelContent and labelDetail in cases where they are macros

NOTE:
In addition to these values, all the parameters of the theme-implementing @field_markup_labelarea macros
are also passed.

labelType Explicit label type (see @fields)
labelPosition Explicit label layout (see @fields)
labelArea ((boolean), default: -from global styles-)
If true, forces a label area; if false, prevents a label area

NOTE:
This does not determine label area type (horizontal, etc.); only labelType does that (in current code).
They are decoupled. This only controls presence of it.

labelAreaRequireContent ((boolean), default: false)
If true, the label area will only be included if label or labelDetail have content

By default, this is empty string (use @fields type default), and if no styles defaults,
labelAreaConsume ((boolean), default: true)
If set to false, will prevent the label area from consuming (displaying) the label

The label will trickle down into an inline area if one exists for the field type.
inlineLabelArea ((boolean), default: -from global styles-, fallback default: false)
Manual override for inline label logic

In general can be left to macro.
inlineLabel ((string))
Manual override for inline label logic

In general can be left to macro.

NOTE:
Often if you specify this it means you might want to set inlineLabelArea=true as well.

tooltip Small field description – to be displayed to the customer

May be set to boolean false to manually prevent tooltip defaults.
description Field description

NOTE:
currently this is treated as an alternative arg for tooltip

name Field name
value Field value
gridArgs ((map))
Grid size and configuration arguments roughly equivalent to #getDefaultFieldGridStyles arguments
widgetPostfixCombined ((boolean), default: -markup decision, usually true-)
CONVENIENCE alias for gridArgs.widgetPostfixCombined – Overridable setting to force or prevent widget and postfix having their own sub-container

It is strongly encouraged to leave this alone in most cases. In Scipio standard markup,
the default is usually true unless prevented by other settings.
totalColumns ((int))
CONVENIENCE alias for gridArgs.totalColumns – Total number of columns spanned by the outer container, including label area, widget and postfix
labelColumns ((int))
CONVENIENCE alias for gridArgs.labelColumns – Number of grid columns to use as size for label area, IF one is to be rendered

If totalColumns is kept the same, any space removed from this value is removed from widget and postfix (combined).
labelSmallDiffColumns ((int), fallback default: 1)
CONVENIENCE alias for gridArgs.labelSmallDiffColumns – Difference between large and small columns of the label area (added to label area columns for "small" container)

By default, this setting is set to 1 so that on small screens the label area gets a slightly larger size.
Sometimes it is needed to set this to zero for custom markup.
class ((css-class))
CSS classes for the field element (NOT the cell container!)

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

containerClass ((css-class))
CSS classes, optional class for outer container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

widgetAreaClass ((css-class))
CSS classes, optional class for widget area container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

labelAreaClass ((css-class))
CSS classes, optional class for label area container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

postfixAreaClass ((css-class))
CSS classes, optional class for postfix area container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

widgetPostfixAreaClass ((css-class))
CSS classes, optional class for combined widget and postfix parent container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

style Legacy HTML style string for compatibility

WARN:
This is currently only implemented on a few field types and sub-types.

maxlength ((int))
Max allowed length

e.g. For text inputs, max number of characters.
id ((string), default: -auto-generated-)
ID for the widget itself

If none specified, one may be auto-generated by the macro.
containerId ((string), default: -auto-generated-)
ID for the outer container

This defaults to "${id}_container".
containerStyle ((string))
Legacy HTML style attribute for outer container
events ((map))
Map of JS event names to script actions

event names can be specified with or without the "on" prefix ("click" or "onclick").
onClick Shortcut for: events={"click": onClick}

WARN:
Beware of character case (due to Freemarker). It's onClick, not onclick!

onChange Shortcut for: events={"change": onChange}
onFocus Shortcut for: events={"focus": onChange}
disabled ((boolean), default: false)
Whether field is disabled
placeholder Field placeholder
alert ((css-class))
CSS classes, additional alert class
mask ((boolean))
Toggles jQuery mask plugin
size ((int), default: 20)
Size attribute
collapse ((boolean), default: false)
Should the whole field (including label and postfix) be collapsing?
collapsePostfix ((boolean), default: true)
Should the postfix collapse with the field input?

this will not affect label unless collapse is also true (in which case this setting is ignored
and the whole field is collapse)
collapsedInlineLabel ((boolean))
Special collapsed inline label control

Special function that will only apply in some cases.
if this is set to true and the label does not get consumed
by the label area and becomes an inline label, this will cause an auto-implementation
of an inlined label using collapsing (instead of passing the inline label
down to the individual field type widget).
this may be needed for some field types.
widgetOnly ((boolean), default: false)
If true, renders only the widget element by default (no containers)

Implies container false and labelArea false by default.

NOTE:
When there is no label area, the label arg trickles down into the widget's inline label area IF it supports one.

inline ((boolean), default: false)
If true, forces container=false, marks the field with styles.field_inline, and forces inline labels (by disabling label area)

In other words, turns it into a logically inline element (traditionally, CSS "display: inline;").
Theme should act on this style to prevent taking up all the width.
In addition, this will force labelArea false and any label specified will use the inlined label (area).

NOTE:
If you want to have a widget-only containerless field without inlining, use widgetOnly=true.
If you want a regular field with containers where only the widget element is inlined (i.e. not full-width-spanning),
use class="+${styles.field_inline}".

norows ((boolean), default: false)
If true, render without the rows-container

NOTE:
This is a low-level control for advanced markup cases and global style presets (@fields).

nocells ((boolean), default: false)
If true, render without the cells-container

NOTE:
This is a low-level control for advanced markup cases and global style presets (@fields).

container ((boolean), default: true)
If false, sets norows=true and nocells=true

NOTE:
This is a low-level control for advanced markup cases and global style presets (@fields).
In most cases you should use widgetOnly parameter in templates if you want to omit container.

ignoreParentField ((boolean), default: false)
If true causes a child field to act as if it had no parent field. Rarely needed
required ((boolean), default: false)
Marks a required input
requiredClass ((css-class))
CSS classes, default required class name

Does not support extended class +/= syntax.
requiredTooltip tooltip to use when field is required. this is overridden by regular tooltip

for this, can prefix with "#LABEL:" string which indicates to take the named label from uiLabelMap.
postfix ((boolean), default: false)
Controls whether an extra area is appended after widget area
postfixColumns ((int), default: 1)
Manual postfix size, in (large) grid columns
postfixContent ((string)|(macro))
Manual postfix markup/content – set to boolean false to prevent any content (but not area container)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Not escaped by macro.

postfixContentArgs ((map))
Optional map of arguments to pass to postfixContent macro, if macro
preWidgetContent ((string)|(macro))
Text or text-generating macro that will be inserted in the widget area before widget content (low-level control)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Currently, the args map will be empty by default – pass using prePostContentArgs.
NOTE:
Not escaped by macro.

postWidgetContent ((string)|(macro))
Text or text-generating macro that will be inserted in the widget area after widget content (low-level control)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Currently, the args map will be empty by default – pass using prePostContentArgs.
NOTE:
Not escaped by macro.

preLabelContent ((string)|(macro))
Text or text-generating macro that will be inserted in the label area before label content (low-level control)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Currently, the args map will be empty by default – pass using prePostContentArgs.
NOTE:
Not escaped by macro.

postLabelContent ((string)|(macro))
Text or text-generating macro that will be inserted in the label area after label content (low-level control)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Currently, the args map will be empty by default – pass using prePostContentArgs.
NOTE:
This is almost the same as labelDetail, except postLabelContent is lower level and will always occur at the specified position.
NOTE:
Not escaped by macro.

prePostfixContent ((string)|(macro))
Text or text-generating macro that will be inserted in the postfix area before postfix content (low-level control)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Currently, the args map will be empty by default – pass using prePostContentArgs.
NOTE:
Not escaped by macro.

postPostfixContent ((string)|(macro))
Text or text-generating macro that will be inserted in the postfix area after postfix content (low-level control)

If macro, the macro must accept a single argument, args, a map of arguments.

NOTE:
Currently, the args map will be empty by default by default – pass using prePostContentArgs.
NOTE:
Not escaped by macro.

prePostContentArgs ((map))
Optional map of extra user-supplied args to be passed to the prePostXxx content macros as the args parameter.
inverted ((boolean), default: false)
If true, invert the widget and label area content and user-supplied and identifying classes

If this is set to true, the widget area content is swapped with the label area content and the user-supplied
classes and identifying classes are also swapped – labelAreaClass and widgetAreaClass.
In addition, the top-level container gets a class to mark it as inverted.
However, the calculated default grid area classes are NOT swapped by default; this allows swapping content while
preserving grid alignment. Mostly useful for small field widgets such as checkboxes and radios.

NOTE:
You may want to use labelContent arg to specify content.

standardClass ((css-class))
CSS classes, default standard (non-inverted) class name, added to outer container

Does not support extended class +/= syntax.
Added for non-inverted fields.
invertedClass ((css-class))
CSS classes, default inverted class name, added to outer container

Does not support extended class +/= syntax.
autoValue ((boolean), default: -from globals-, fallback default: false)
Fine-grained control to turn auto value lookups on or off

WARN:
NOT FULLY IMPLEMENTED (2016-07-15)

@field has the ability to automatically lookup values from parameter, record and defaults maps,
through implicit calls to the #getAutoValue function.
By default, this auto value enabling is determined by the current globals as set by @fields
or #setAutoValueCfg. This boolean allows to disable per-field as a quick fix.

NOTE:
This does not support the extensive arguments supported by @fields. It only supports
explicit boolean on/off to toggle for individual fields.

autoValueArgs ((map))
Extra arguments that will be passed to #getAutoValue when auto values enabled.

Note that basics such as name, value, and type are already covered.
Some extras that may be specified are: overrideName, paramName, recordName, defaultName.

NOTE:
suffix is reserved for use and should never be specified.

See #getAutoValue for a comprehensive list.

attribs ((map))
map of extra/custom HTML attributes for the main input element (input, select, etc.)

NOTE:
In some cases, these could conflict with attributes defined in themes
or in the default theme markup, or with other parameters.
NOTE:
Unlike some other macros, @field does not support inline attributes;
only this attribs parameter will work.

input (alias: text)
autoCompleteUrl If autocomplete function exists, specification of url will make it available
postfix ((boolean), default: false)
If set to true, attach submit button
textarea
readonly ((boolean) Read-only
rows ((int))
Number of rows
cols ((int))
Number of columns
wrap HTML5 wrap attribute
text, value Text/value, alternative to nested content
datetime
dateType (date-time|timestamp|date|time|month, default: date-time)
Type of datetime

"date-time" and "timestamp" are synonymous.
dateDisplayType (default|date|..., default: -same as dateType-)
. The visual display format of the date. Optional

If dateType is "date-time" (timestamp), it is possible to specify dateDisplayType="date" here.
This means the user will be presented with a short date only, but the data sent to the server
will be a full timestamp.
datePostfix ((boolean), default: true)
Override for date-widget-specific postfix
datePostfixColumns ((int), default: 1)
Size of date-widget-specific postfix
manualInput ((boolean), default: true)
Whether to allow manual input; if false, selection only through date picker
title Title

If empty, markup/theme decides what to show.
Can also be a special value in format "#PROP:resource#propname" (if no resource, taken from CommonUiLabels).

NOTE:
tooltip has priority over title.

datefind
dateType (-same as datetime, except does not support month-)
dateDisplayType (-same as datetime, except does not support month-)
opValue The selected operator (value)
textfind
opValue The selected operator (value)
ignoreCaseValue ((boolean), default: true)
The ignore case checkbox current value

The default should be same as form widget default (text-find's "ignore-case" in widget-form.xsd).
hideOptions ((boolean), default: false)
If true, don't show select options
hideIgnoreCase ((boolean), default: false)
If true, hide case sensitivity boolean
titleClass ((css-class))
CSS classes, extra classes for title
rangefind
opFromValue The selected "from" operator (value)
opThruValue The selected "thru" operator (value)
titleClass ((css-class))
CSS classes, extra classes for title
select
multiple ((boolean), default: false)
Allow multiple select
items ((list))
List of maps; if specified, generates options from list of maps

List of {"value": (value), "description": (label), "selected": (true/false), "attribs":(html attributes map)} maps
If items list not specified, manual nested content options can be specified instead.

NOTE:
selected is currently ignored for non-multiple (uses currentValue instead).

allowEmpty ((boolean), default: false)
If true, will add an empty option
currentValue currently selected value/key (only for non-multiple)
currentFirst ((boolean), default: false)
If true (and multiple false), will add a "first" item with current value selected, if there is one
currentDescription If currentFirst true, this is used as first's description if specified
defaultValue Optional selected option value for when none otherwise selected

NOTE:
When auto-value is being used (#getAutoValue), this should be omitted.

manualItemsOnly ((boolean))
Optional hint to say this select should contain exclusively manually generated items

By default, this is determined based on whether the items arg is specified or not.
manualItems ((boolean))
Optional hint to say that nested content contains manual options (but not necessarily exclusively)

By default, this is determined based on whether the items arg is specified or not (NOT whether
there is any nested content or not).
If specifying both items arg AND nested content (discouraged), this should be manually set to true.
dynSelectArgs ((map))
Optional map of args to pass to @dynamicSelectFieldScript to transform a multiple type select into a dynamic select

Usually only valid if multiple is true.
asmSelectArgs ((map))
(deprecated) Old alias for dynSelectArgs
formName Name of form containing the field
formId ID of form containing the field
title Title attribute of <select> element
option
text Option label

May also be specified as nested.
value Value, sent to server upon submit
selected ((boolean))
lookup
formName The name of the form that contains the lookup field
fieldFormName Contains the lookup window form name
checkbox (single mode)
value Value to submit with form when checkbox is selected
currentValue Current value, used to check if should be checked
useHidden ((boolean), default: false)
If true, submits using a hidden field rather than checkbox itself

WARN:
This affects javascript lookups, field name and id.

If this is true, the name of the checkbox itself receives the suffix _visible,
such that the hidden input receives the passed name. Any javascript must adapt appropriately.
On the other hand, the id of the checkbox is unchanged, and the hidden field
receives an id with a _hidden suffix.

NOTE:
2017-04-20: An explicit true or false value for useHidden now overrides the automatic-enabling
by the presence of altValue, so that useHidden=false guarantees no hidden even if you
set an altValue; however, in this case altValue is ignored. This is to simplify some caller
code language.

altValue Value to submit with form when checkbox is unselected

WARN:
This affects javascript lookups, field name and id; see useHidden parameter.

If this is specified (non-boolean, non-false), it automatically turns on useHidden
(without which implementation is impossible).

checked ((boolean)|, default: -empty-)
Override checked state

If set to boolean, overrides currentValue logic
checkboxType (default|..., default: default)

Generic:

  • default: default theme checkbox

Scipio standard theme:

  • simple: guarantees a minimalistic checkbox

valueType (|indicator, default: -empty-)
Special and predefined value types

indicator: Same as passing value="Y" altValue="N" useHidden=true.
checkbox (multi mode)
items ((list))
List of maps, if specified, multiple-items checkbox field generated

List of {"value": (value), "altValue": (value), "useHidden": (boolean),
"description": (label), "tooltip": (tooltip), "events": (js event map), "checked": (true/false), "attribs":(html attributes map)} maps

NOTE:
use of "checked" attrib is discouraged; is a manual override (both true and false override); prefer setting currentValue on macro

inlineItems ((boolean), default: -from global styles-, fallback default: true)
If true, radio items are many per line; if false, one per line

NOTE:
this takes effect whether single-item or multiple-item radio.

the default can be overridden on a parent @field or @fields element.

currentValue Current value, determines checked; this can be single-value string or sequence of value strings
defaultValue Default value, determines checked (convenience parameter; used when currentValue empty; can also be sequence)

NOTE:
When auto-value is being used (#getAutoValue), this should be omitted.

allChecked ((boolean|), default: -empty-)
Explicit false sets all to unchecked; leave empty "" for no setting (convenience parameter)
value Default value for any items which do not specify their own
altValue Default alt (off) value for any items which do not specify their own
useHidden ((boolean), default: false)
Default useHidden for any items which do not specify their own
radio (single mode)
value Y/N, only used if single radio item mode (items not specified)
currentValue Current value, used to check if should be checked
checked ((boolean)|, default: -empty-)
Override checked state

If set to boolean, overrides currentValue logic
radioType (default|..., default: default)

Generic:

  • default: default theme radio

Scipio standard theme:

  • See global styles.

radio (multi mode)
items ((list))
List of maps, if specified, multiple-items radio generated with map entries in provided list as arguments

List of {"value": (value), "description": (label), "tooltip": (tooltip), "events": (js event map), "checked": (true/false), "attribs":(html attributes map)} maps

NOTE:
use of "checked" attrib is discouraged; is a manual override (both true and false override); prefer setting currentValue on macro

inlineItems ((boolean), default: -from global styles-, fallback default: true)
If true, radio items are many per line; if false, one per line

NOTE:
This takes effect whether single-item or multiple-item radio.

The default can be overridden on a parent @field or @fields element.

currentValue Current value, determines checked
defaultValue Default value, determines checked (convenience option; used when currentValue empty)

NOTE:
When auto-value is being used (#getAutoValue), this should be omitted.

file
autocomplete ((boolean), default: true)
If false, prevents autocomplete
password
autocomplete ((boolean), default: true)
If false, prevents autocomplete
submitarea
(nested) ((markup))
Button(s) to include

The buttons may be generated with <@field type="submit"> or manual <input>, <a>, <button> elements.
progressArgs ((map))
If this is an upload form, arguments to pass to @progress macro

See @progress and @progressScript macros. Should specify formSel, at least one of progBarId and progTextBoxId, and others.
progressOptions ((map))
Progress options (convenience parameter)

Same as passing:

progressArgs={"enabled":true, "progressOptions":progressOptions}
submit
submitType (submit|link|button|image|input-button, default: submit)
Submit element type

  • submit: <input type="submit" ... />
  • input-button: <input type="button" ... />
  • link: <a href="..." ...>...</a>

    NOTE:
    href should usually be specified for this, or explicitly set to boolean false if using onClick.
    If not specified, generated href will cause form submit with form name (if found and not disabled).
  • button: <input type="button" ... />

    WARN:
    FIXME?: Currently this is same as input-button: <input type="button" ... />
    This could change to <button...>...</button> without notice…
  • image: <input type="image" src="..." .../>

text ((string), default: -from global styles-)
Display text, for text-link and button submits

If omitted, a default "Submit" text is used from global styles.

NOTE:
Reserved values: If set to empty space " " or "_NO_BTN_MARKUP_",
button markup is not rendered (shows progress only) (the empty space is from a stock form widget convention).
NOTE:
value arg is also accepted instead of text.

href href for submitType "link"

NOTE:
This parameter is automatically (re-)escaped for HTML and javascript (using #escapeFullUrl or equivalent)
to help prevent injection, as it is high-risk. It accepts pre-escaped query string delimiters for compatibility,
but other characters should not be manually escaped (apart from URL parameter encoding).

src Image url for submitType "image"
confirmMsg Confirmation message
progressArgs Same as for submitarea, but only works if this is a top-level submit
progressOptions Same as for submitarea, but only works if this is a top-level submit
reset
text Label to show on reset button
display
valueType (image|text|currency|date|date-time|timestamp|accounting-number|generic, default: generic)

"date-time" and "timestamp" are synonymous.

  • generic: treated as arbitrary content, but text may still be interpreted

value Display value or image URL
description For image type: image alt
tooltip Tooltip text

May result in extra wrapping container.
formatText ((boolean), default: true)
If true, translates newlines to HTML linebreaks (and potentially other transformations)

NOTE:
2017-08-03: The default for @field macro is currently true, which is the same as the Ofbiz form widget default, which is true.
Prior to 2017-08-03, this formatText parameter documentation had been mistakenly changed
to suggest the default was false for generic (default) valueType for ftl templates (only).
However, the actual code was not completely changed and the effective default remained true.
Thus, currently, for compatibility reasons, the default is currently left to true
for all cases including generic valueType for ftl templates.

generic
tooltip Tooltip text

May result in extra wrapping container.
Other
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

History

Modified for 1.14.4 (fixed documentation for "display" type "formatText" parameter, added "attribs" parameter).

input

macro input

A form field input widget with optional label and post-input (postfix) content. Alias for @field.

Parameters

Related

@field

History

Added for for 2.1.0.

getDefaultFieldGridStyles

function getDefaultFieldGridStyles

Returns the classes that @field would put on the label, widget and postfix area containers, given the requirements.
Caller may override any.

NOTE:
This is used both internally by @field and in some cases is also needed in templates.

Parameters

fieldsType ((string), default: default)
The @fields type

Used for calculating the defaults of some of the other parameters.
widgetPostfixCombined ((boolean), default: false)
Whether the calculation should consider widget and postfix having an extra container around them together

NOTE:
The hardcoded default for this is false and must always be false.
The hardcoding is part of this function's interface. This is because structure depends highly
on what the caller decides is appropriate and there is not enough information to decide it here.
NOTE:
Even though the default for this is false, in many cases generally we end up using true.

totalColumns ((int), default: -from global styles-)
The logical total columns for a field row

NOTE:
This does not have to be 12.

totalLarge ((int), default: -value of totalColumns-)
Total columns override for large
totalSmall ((int), default: -value of totalColumns-)
Total columns override for small
labelColumns ((int), default: -from global styles-)
The columns size of label area, if labelArea and labelInRow are true
labelLarge ((int), default: -value of labelColumns-)
Label area columns override for large
labelSmallLarge ((int), default: -value of labelColumns-)
Label area columns override for small
postfixColumns ((int), default: -from global styles-)
Postfix columns
postfixLarge ((int), default: -value of postfixColumns-)
Postfix columns override for large
postfixSmall ((int), default: -value of postfixColumns-)
Postfix columns override for small
labelArea
labelInRow
postfix
isLargeParent
labelSmallDiffColumns
labelSmall

NOTE: This function implements an advanced arguments interface emulating named
parameters using maps, and the parameters above may not be positional. See standard/htmlTemplate for details.

getAutoValue

function getAutoValue

Returns an appropriate field value (typically for use with @field) based on current values in request
and context, following a certain scheme type specified directly or previously through globals.

WARN:
NOT FULLY IMPLEMENTED (2016-07-15) – EXPERIMENTAL

Typically the value is looked up in a set of global maps (parameters, a record or entity, defaults, etc.)
following some predefined priority.

The schema type may be specified directly, but in most cases it should have been specified for a group of
getAutoValue calls using @fields, where the specific maps to use when looking up the value may also be specified.
It is also possible to manually call #setAutoValueCfg to set them, which should rarely be needed.

NOTE:
This method conditionally acts on the isError boolean context field. Usually it is
set depending on the result of the last controller event. In non-standard cases you may have
to set it manually.

Parameters

type (standard|..., default: -from globals-, fallback default: standard)
The value scheme type

  • params: looks for value in overrides map, then parameters map, then defaults map
  • record: looks for value in overrides map, then record map, then defaults map
  • defaults-only: looks for value in overrides map, then defaults map
  • params-record: looks for value in overrides map, then parameters map, then record, then defaults map.
    This may be
  • params-or-record: looks for value in overrides map, then EITHER parameters map OR record map, then defaults map
    At current time (2016-07-08), the selection of parameters or record map default behavior is based on whether an event
    error occurred (isError boolean context field).
  • standard: In scipio standard API, currently (2016-07-08), this is the same params-or-record, currently considered the standard behavior.

name Main field name, used for all maps that does not have more specific names (overrideName, paramName, etc.)

NOTE:
As a convenience, name can be passed as single parameter instead of the args map.

overrideName Field name for overrides map
paramName Field name for parameters map
recordName Field name for record map
defaultName Field name for defaults map
suffix Optional suffix added to each of the name parameters
overrideValue An override values, which takes priority over all
paramValue A param value, which takes immediate priority over the params map
value A value, which takes immediate priority over the record values

It is ignored in all cases where the record map is also ignored (such as type="params").
defaultValue A default value, which takes immediate priority over the default map values
submitDetectMethod (default|flag|post|none, default: default)
Submit detection method

  • default: use flag if submitFlagParam, otherwise use post
  • flag: use submitFlagParam
  • post: use POST request check
  • none: none

submitFlagParam Optional name of a parameter from params map whose presence determines if a form was submitted or not.

Automatically implies submitDetectMethod="flag".
This parameter is checked using ?? operator, by simple presence.
This is needed for parameters whose HTML inputs don't always submit a value.
If a submit happened and the field is missing, then the field is given the value specified in submitDefaultParamValue.
By default, submission is detected using presence of POST request, but in most cases,
it is better to have submitFlagParam specified, easiest using @fields.
submitDefaultParamValue ((string), default: ""/[]/{})
Default param value to use if submitFlagParam checks out
submitError ((boolean)|"", default: "")
Explicit success/error flag

If not specified as boolean (empty string), uses isError context variable.

NOTE: This function implements an advanced arguments interface emulating named
parameters using maps, and the parameters above may not be positional. See standard/htmlTemplate for details.

Related

@fields,
#setAutoValueCfg

setAutoValueCfg

function setAutoValueCfg

Sets the current global value configuration (maps and settings) used by #getAutoValue, and can also be used
to disable auto value lookups for @field.

NOTE:
Any parameters not specified leave the existing corresponding globals unchanged.
NOTE:
The globals specified by this function currently do not survive screen render boundaries; they
have page/template scope, not request scope.

Parameters

autoValue ((boolean))
Determines if auto value lookups are enabled for macros such as @field

NOTE:
Unlike some other macros and functions (such as @fields), for this function, if this
parameter is omitted, the function will not turn on auto values. It is a manual
call and requires explicit true.

type ((string))
The value scheme type

See #getAutoValue for possible values.
overrides ((map))
Map to use as overrides map for lookups
params ((map)|(boolean))
Map to use as parameters map for lookups

Normally, if this is not specified anywhere, the Ofbiz parameters map is used.
If this is set to boolean false (special value), no parameters map will be used.
record ((map))
Map to use as record map for lookups

Usually this is something like an entity value.
defaults ((map))
Map to use as defaults map for lookups
submitDetectMethod ((string))
Submit detection method

See #getAutoValue for possible values.
submitFlagParam Name of a parameter from params map whose presence can be used to detect whether a form submit occurred

See #getAutoValue for info.
submitError ((boolean)|"", default: "")
Explicit success/error flag

If not specified as boolean (empty string), uses isError context variable.

NOTE: This function implements an advanced arguments interface emulating named
parameters using maps, and the parameters above may not be positional. See standard/htmlTemplate for details.

Related

#getAutoValueCfg,
#getAutoValue

getAutoValueCfg

function getAutoValueCfg

Returns the current global auto value configuration (settings and maps).

Parameters

dummy

NOTE: This function implements an advanced arguments interface emulating named
parameters using maps, and the parameters above may not be positional. See standard/htmlTemplate for details.

Related

#setAutoValueCfg,
#getAutoValue

getAutoValueMap

function getAutoValueMap

Returns a field value autodetermining helper map.

Parameters

type (standard|..., default: -from globals-, fallback default: standard)
The value scheme type

  • params: looks for value in overrides map, then parameters map, then defaults map
  • record: looks for value in overrides map, then record map, then defaults map
  • defaults-only: looks for value in overrides map, then defaults map
  • params-record: looks for value in overrides map, then parameters map, then record, then defaults map.
    This may be
  • params-or-record: looks for value in overrides map, then EITHER parameters map OR record map, then defaults map
    At current time (2016-07-08), the selection of parameters or record map default behavior is based on whether an event
    error occurred (isError boolean context field).
  • standard: In scipio standard API, currently (2016-07-08), this is the same params-or-record, currently considered the standard behavior.

NOTE: This function implements an advanced arguments interface emulating named
parameters using maps, and the parameters above may not be positional. See standard/htmlTemplate for details.