Utility Functions

Furthermore, while ?interpret returns a directive as wrapper (evaluated using <@value/> syntax),
by default, #interpretStd returns a scalar (string)-implementing wrapper,
so that it can be evaluated using the same syntax used for regular string variables,
and thus can substitute more easily.

Unlike ?interpret, variables from the FTL environment are NOT available
from #interpretStd invocations; only variables from the widget renderer
context (MapStack) are available. This is closer to @render and is an explicit feature
intended to prevent interfering with FTL environment of parent templates.
Furthermore, by default, the context MapStack is pushed (see pushCtx parameter).

This function accepts one parameter which is a map of parameters, described below.
If a single string is supplied instead, it is taken as the inline string template
to interpret, and all other parameters get defaults.

Currently, this method only support file locations, and is basic for low overhead. For interpreted/inline scripts, see #interpretStd.

This is useful to avoid bloating templates with heavy <#assign...><@pageUrl.../></#assign> captures
and instead passing results directly to other macros and functions.

This function's default escaping behavior is different from the default behavior of its macro counterpart, @pageUrl;
unlike @pageUrl this function was primarily intended to manipulate unescaped strings at input. See @pageUrl for details.

This calls @pageUrl with absPath=false, interWebapp=false, controller=false by default.

This calls @pageUrl with interWebapp=true and optional webSiteId; absPath is left to interpretation
by the implementation or can be overridden; controller is left to interpretation or can be specified.

This function is enhanced to support more value types and the special value scpNull
to indicate the value null.

This function is enhanced to support more value types and the special value scpNull
to indicate the value null.

This function is enhanced to support more value types and the special value scpNull
to indicate the value null.

By default this function tries to maintain the same behavior as uiLabelMap with respect to locale
selection and the context map used for label substitutions/arguments.

However, unlike stock uiLabelMap, this supports explicit message arguments using the msgArgs parameter.

The locale is determined by uiLabelMap. If you must

Shorthand for raw(getLabel(...)). See #getLabel for more information.

than #getPropertyMsg, which always returns a string, for legacy and consistency reasons (UtilProperties method design).

in other words not expected to be printed as HTML.

than #getPropertyMsg, which always returns a string, for legacy and consistency reasons (UtilProperties method design).

in other words not expected to be printed as HTML.

to read *.properties files, use #getPropertyValue instead. This function is only a bare wrapper around the
UtilProperties#getMessage class method and does not consult the global label map (uiLabelMap) and is not meant
to read *.properties files.

If the name does not exist in the resource, by default this returns the property name, unless true for optional
is passed in which case it returns empty string (NOT void/missing). The default value operator ("!") is effectively useless if used
with this function (unlike #getPropertyValue).

The default value behavior differs from #getPropertyValue for legacy reasons (UtilProperties method design
and the template code it was menat to replace), and because for label messages (as opposed to #getPropertyValue,
which reads .properties files) it is very rare to need a label fallback in templates.

which it did not (it always returned the property name, like UtilProperties#getMessage, which it was intended
to replace in templates).

to read *.properties files, use #getPropertyValue instead. This function is only a bare wrapper around the
UtilProperties#getMessage class method and does not consult the global label map (uiLabelMap) and is not meant
to read *.properties files.

See #getPropertyMsg for more information; this is nearly the same as #getPropertyMsg but with extra support for a
resource expression.

which it did not (it always returned the property name, like UtilProperties#getMessage, which it was intended
to replace in templates).

Can be seen as the reverse operation of #rewrapString.

Can be seen as the reverse operation of #rewrapString.

The function can remove the html auto-escaping behavior of entire maps coming from the data model.
Simply doing rewrapObject(someScreenMap, 'raw') or rewrapObject(someScreenMap, 'raw-simple') (to
further simplify the map for iteration).

Using wrapper and mode parameters, different object wrappers such as simple-type-producing
ones can be used, and some unnecessary rewrapping can be avoided.

If the object is not a complex map but already another type of map, returns it as-is. Other types throw errors.

WARN (2016-12-02): Do not rely on this for keying back the values out of the original

map; you should still call #toSimpleMap on the original map
before getting the values out of it. This is because BeansWrapper-mapped maps
treat some key values such as the "class" key as special.

Using "+" on screen context bean maps causes problems such as "hiding" of the bean map type underneath
an FTL wrapper, which wrecks all subsequent type checks. And others.

gets included as
a raw string bypassing html, js or other language escaping.
This include @objectAsScript and macros that escape values using #escapeVal or #escapeFull.

For more information about escaping in general, see standard/htmlTemplate.ftl.

Essentially this is a wrapper around #rawString and language encoders. It abstracts the encoder selection.
It first performs a #rawString call to bypass the screen auto-escaping on the value.

In addition, this function accepts values produced by #wrapAsRaw. These can be used to bypass the escaping in part or in full.
If the value was wrapped using the same language as specified in this call, the wrapped value will be used as-is.

For more information about escaping in general, see standard/htmlTemplate.ftl.

Single languages

HTML: Two language identifiers are supported: "html" and "htmlmarkup".
Callers of #escapeVal should usually use "html" on html attributes, and "htmlmarkup" on text placed within element body.
By default, this function escapes all markup delimiters for both.
The difference is that callers upstream using #wrapAsRaw will then able to override markup specifically using:

#wrapAsRaw(xxx, 'htmlmarkup')

or for all html (only if careful to escape for attributes safely) using:

#wrapAsRaw(xxx, 'html')

"html" is also a special case because it also fills in for "htmlmarkup" (if not included in the #wrapAsRaw call),
but not vice-versa since markup cannot be used in attributes.

Javascript, JSON: Only simple single string parts are supported via "js" and "json" (and some variants).
This can ONLY encode strings between "" or ''.
It is impossible to safely encode javascript outside string literals (see OWASP).

Composed languages

Javascript and HTML: For Javascript strings placed within HTML attributes (e.g. events such as onchange),
typically "js-html" is needed.

Validation and allowed code

This function is scheduled to support some language-specific code validation/filters, to provide
a middle ground between allowing no code (full escaping – default behavior) and allowing all code (no escaping – #rawString alone).
See the opts.allow parameter below.

It is usually logical to perform such validation nearest to point-of-use as possible using this function.
However, note that, in addition, it is usually either a very good idea or simply required to validate input
such as code markup before storage in database (server-side, or even client-side yet in addition), long before
and elsewhere from a template containing this function call is rendered.
Thus, the safest solution is to do both; validate markup in content from actors server-side, and apply
the equivalent filter using this function in templates. This guards against errors and stale content spanning security policy
and filter implementation changes.

Related

#escapeVal
#escapeFullUrl

Essentially this is a wrapper around #rawString and language encoders. It abstracts the encoder selection.
It first performs a #rawString call to bypass the screen auto-escaping on the value.

For compability reasons, this function when not in strict mode (default is not strict) accepts param delimiters
in either the escaped & form or unescaped & form.
Ideally, such escaped delimiters would not be received, but they are very prevalent in Ofbiz due
to early escaping.

In addition, this function accepts values produced by #wrapAsRaw. These can be used to bypass the escaping in part or in full.
If the value was wrapped using the same language as specified in this call, the wrapped value will be used as-is.
Note that most times, this is not nearly as useful as it is for #escapeVal.

For more information about escaping in general, see standard/htmlTemplate.ftl.

This function is largely a point-of-use compatibility version of stock ofbiz behavior
often used on description fields, event messages, etc.

Currently, this attempts to support the legacy ofbiz behavior of line-break translation
for errorMessage, errorMessageList, eventMessage and eventMessageList when lang=="htmlmarkup".
Traditionally this was done obscurely in ofbiz by the ScreenRenderer.java class, but that was
a design error (not point-of-use escaping) and caused several issues, so this is being
improved for Scipio.

<#macro name args={} inlineArgs...>

pattern, whereby inlineArgs map is merged over the args map, over defaults.

It cannot be used for the 'attribs={} inlineAttribs...' pattern (see mergeAttribMaps).
Instead, it can help in implementing that pattern within the 'args={} inlineArgs...' pattern.

This is specific to scipio macro patterns and may contain extra handling besides concatenating maps.

For one, this currently records the macro's static named args as passed in the defaultArgs and overrideArgs maps
in a list of names with the key "localArgNames" in the resulting map.
It will also append the names to a list read back from the incoming "args" map with
key name "allArgNames", append to it, and return it again as "allArgNames".
allArgNames allows arg names to be automatically accumulated
between delegating/overriding macro calls that make use of mergeArgMaps without
having to recreate new intermediate maps. allArgNames keep track of all the explicit
args used by all the macros in a call chain, which can then be used to identify
the remaining "extra" arguments (analogous to varArgs in FTL's <#macro varArgs...>).

The result is the caller can access any arg names in the resulting map which had a default
value using simple syntax guaranteed not to cause missing values. e.g

<#macro name args={} inlineArgs...>
  <#local args = mergeArgMaps(inlineArgs, args, {"myParam1":true})>
  <#if args.myParam1>
    ...
  </#if>
</#macro>

OR

<#macro name args={} inlineArgs...>
  <#local args = mergeArgMaps(inlineArgs, args, {"myParam1":true})>
  <#local dummy = localsPutAll(args)>
  <#if myParam1>
    ...
  </#if>
</#macro>

This can also be used for functions, but for functions, the inlineArgs param should always
be passed an empty hash (functions don't support named parameters).

<#macro name arg1="" arg2="" ... argN="" attribs={} inlineAttribs...>

pattern, whereby inlineAttribs map is merged over the attribs map, and these maps only contain extra
element attributes.

This pattern is simpler but much less flexible than the 'args={} inlineArgs...' pattern.
They are different and NOT interchangeable.

Parameters are analogous to #mergeArgMaps but implied logic differs.

Macro Class Arguments

Macro class arguments can have essential (required) and non-essential (default)
defaults and values added by the macro before producing the final class attribute.
The essentials can't be omitted.
The non-essentials in some cases you want to replace with value and other times
you want to keep them but only add extra classes. Having multiple args for each elem
class arg gets heavy.

So to address all the cases, these functions cause the class arg on all supporting macros
to accept following values:

In a few cases, the non-essential defaults are "conditionally essential"
so class="=" makes little sense, but usually doesn't warrant special handling.

ADD CLASS ARG FUNCTIONS

These functions take a template-level/logical scipio macro "class" arg and add to it the given class.
Should be called by the implementing macros only.

Depending on the previous value in class, non-essential (default) values may simply be discarded, but
essentials (required) will always be added in some way, transforming the class value.

The newClass parameter is a simple string literal and is not interpreted.

These are non-destructive except for addClassArgReplacing which always causes the string to become
a replacing string ("=").