Namespace: util

This function applies data to a template. It processes the template string given in pTemplate by substituting values according to the options in pOptions. The template supports Application Express server style placeholder and item substitution syntax.

This function is intended to process Application Express style templates in the browser. However it doesn't have access to all the data that the server has. When substituting page items and column items it uses the current value stored in the browser not what is in session state on the server. It does not support the old non-exact substitutions (with no trailing dot e.g. &ITEM). It does not support the old column reference syntax that uses #COLUMN_NAME#. It cannot call PREPARE_URL (this must be done on the server). Using a template to insert JavaScript into the DOM is not supported. After processing the template all script tags are removed.

The format of a template string is any text intermixed with any number of replacement tokens or directives. Two kinds of replacement tokens are supported: placeholders and data substitutions. Directives control the processing of the template. Directives are processed first, then placeholders and finally data subsitutions.

Placeholders

This is also known as a hash substitution.

Placeholder syntax is:

#<placeholder-name>#

The <placeholder-name> is an uppercase alpha numeric plus "_", and "$" string that must be a property name in option object placeholders that gets replaced with the property value. Any placeholder tokens that don't match anything in the placeholders object are left as is (searching for the next placeholder begins with the trailing # character).

Data substitutions

Substitution syntax is (any of):

&<item-name>.
&<item-name>!<escape-filter>.
&"<quoted-item-name>".
&"<quoted-item-name>"!<escape-filter>.
&APP_TEXT$<message-key>.
&APP_TEXT$<message-key>!<escape-filter>.
&"APP_TEXT$<message-key>".
&"APP_TEXT$<message-key>"!<escape-filter>.

The <item-name> is an uppercase alpha numeric plus "_", "$", and "#" string. The <quoted-item-name> is a string of any characters except "&", carriage return, line feed, and double quote. In both cases the item name is the name of a page item (unless option includePageItems is false), a column item (if model and record options are given), a built-in substitution (unless option includeBuiltinSubstitutions is false), or an extra substitution if option extraSubstitutions is given.

The <item-name> can include a property reference. A '%' character separates the item-name from the property name. For example &P1_NAME%LABEL. will return the label of the P1_NAME item. The property name is case insensitive.

The properties and the values they return for a page item are:

• LABEL - The item label.
• DISPLAY - The display value of the item's current value.
• CHANGED - 'Y' if the item has been changed and 'N' otherwise.
• DISABLED - 'Y' if the item is disabled and 'N' otherwise.

The properties for a column item are:

• HEADING - The column heading text. The heading may include markup. If there is no heading the label will be used if there is one.
• LABEL - The column label. If there is no label the heading will be used with markup removed.
• DISPLAY - The display value of the column value for the current row/record.
• HEADING_CLASS - Any CSS classes defined for the column heading.
• COLUMN_CLASS - Any CSS classes defined for the column.
• REQUIRED - 'Y' if the column is required and 'N' otherwise.

The <message-key> is a message key suitable for use in apex.lang.getMessage and is replaced with the localized message text for the given key. The message must already be loaded on the client by setting the Text Message attribute Used in JavaScript to On or otherwise adding it such as with apex.lang.addMessages. If no replacement for a substitution can be found it is replaced with the message key. The language specifier that is supported for server side message substitutions is not supported by the client and will be ignored if present.

When substituting a column item the given record of the given model is used to find a matching column name. If not found and if the model has a parent model then the parent model's columns are checked. This continues as long as there is a parent model. The order to resolve an item name is: page item, column item, column item from ancestor models, built-in substitutions, and finally extra substitutions. For backward compatibility column items support the "_LABEL" suffix to access the defined column label. For example if there is a column item named NOTE the substitution &NOTE_LABEL. will return the label string for column NOTE. It is better to use the label property in this case, for example: &NOTE%label..

The built-in substitution names are:

• &APP_ID.
• &APP_PAGE_ID.
• &APP_SESSION.
• &REQUEST.
• &DEBUG.
• &IMAGE_PREFIX.

The escape-filter controls how the replacement value is escaped or filtered. It can be one of the following values:

• HTML the value will have HTML characters escaped using apex.util.escapeHTML.
• ATTR the value will be escaped for an HTML attribute context (currently the same as HTML)
• RAW does not change the value at all.
• STRIPHTML the value will have HTML tags removed and HTML characters escaped.

This will override any default escape filter set with option defaultEscapeFilter or from the column definition escape property.

Directives

Directive syntax is:

{<directive-name>[ <directive-arguments>]/}

The directive name determines what it does as described below. Directive names are case insensitive. There can be no whitespace between the open bracket '{' and the directive name. Directives often come in sets that work together. A directive may have additional arguments.

If condition directives

Syntax:

{if [!]NAME/}
TRUE_TEMPLATE_TEXT
{elseif [!]NAME2/}
ELSE_TRUE_TEMPLATE_TEXT
{else/}
FALSE_TEMPLATE_TEXT
{endif/}

The entire text from the if directive to the matching endif directive is replaced with the processed template text following the first if or elseif directive that evaluates to true or the template text following the else directive if none are true. There must be an if and endif directive. The elseif and else directives are optional. There can be any number of elseif directives. The directives must go in the order shown. If directives can be nested. That means any of the template texts can contain another if directive.

The if and elseif directives test the value of NAME and if it is true process the following template text. The NAME can be an item-name, quoted-item-name, or placeholder-name. The value of an item-name or quoted-item-name is the value of that page item or column item. The value of a placeholder-name is the text of the placeholder. If no data substitution or placeholder with that name exists then the value is empty string.

A value is false if after trimming leading and trailing spaces it is an empty string, or for a page item the item item#isEmpty method returns true, or if the value is equal to any of the values in the falseValues option. Any value that is not false is true. If the name is prefixed with exclamation mark (!) then the logic is negated and the following template text is processed if the value is false.

Example:
The page contains items P1_TITLE, P_ICON, P1_DESCRIPTION, and P1_DETAILS and all have optional values. The template outputs a default title if P1_TITLE is empty. An optional icon is shown only if there is a title. The template output includes markup for the description if it is not empty or details if it is not empty and nothing otherwise.

<h3>{if P1_TITLE/}&P1_TITLE. {if P1_ICON/}<span class="fa &P1_ICON."></span>{endif/}
{else/}Untitled{endif/}</h3>
{if P1_DESCRIPTION/}
  <p class="description">&P1_DESCRIPTION.</p>
{elseif P1_DETAILS/}
  <p class="details">&P1_DETAILS.</p>
{endif/}

Case condition directives

Syntax:

{case NAME/}
{when string1/}
TEMPLATE_TEXT1
{when string2/}
TEMPLATE_TEXT2
{otherwise/}
TEMPLATE_TEXT
{endcase/}

The entire text from the case directive to the matching endcase directive is replaced with the processed template text after the when directive that matches the NAME value. The value of NAME is compared with each of the strings in the when directive and if it is equal the following template (TEMPLATE_TEXTn) is processed. If no when directive matches then the template after the otherwise directive is processed if there is one. The otherwise directive is optional but it must come at the end and there can only be one. Case directives can be nested. That means any of the template texts can contain another case directive.

The NAME can be an item-name, quoted-item-name, or placeholder-name. The value of an item-name or quoted-item-name is the value of that page item or column item. The value of a placeholder-name is the text of the placeholder. If no data substitution or placeholder with that name exists then the value is empty string. The NAME value and each string is trimmed of leading and trailing spaces before comparison. The comparison is case sensitive.

Example:
The page contains items P1_NAME and P1_DETAILS, and P1_DETAIL_STYLE that can have a value of "FULL" or "BRIEF". The intention is to control the markup according to the detail style.

{case P1_DETAIL_STYLE/}
{when FULL/}
    <div class="full">
        <span>&P1_NAME!HTML.</span>
        <p class="description">&P1_DETAILS!HTML.</p>
    </div>
{when BRIEF/}
  <div class="brief">
      <span>&P1_NAME!HTML.</span>
  </div>
{endcase/}

Loop directives

Syntax:

{loop ["SEP"] NAME/}
TEMPLATE_TEXT
{endloop/}

The entire text from the loop directive to the matching endloop directive is replaced with the template text evaluated once for each item in the NAME value.

The NAME can be an item-name, quoted-item-name, or placeholder-name. The value of an item-name or quoted-item-name is the value of that page item or column item. The value of a placeholder-name is the text of the placeholder. If no data substitution or placeholder with that name exists then the value is empty string. The NAME value should be a separator delimited string that contains a list of items. The optional SEP argument defines the separator character. The default separator is ":". If SEP is more than one character it is treated as a regular expression.

Within the loop there are two extra data substitutions available:

• APEX$ITEM This is the value of the current item in the list.
• APEX$I This is 1 based index of the current item in the list.

Example:
The following example takes a page item, P1_TAGS that contains a bar '|' separated list of tags such as "apples|cherries|pears" and turns it into an HTML list that can be nicely styled.

<ul class="tags">{loop "|" P1_TAGS/}
  <li class="tag-item">APEX$ITEM</li>
{endloop/}</ul>

Comments

Syntax:

{!<comment-text>/}

This directive is substituted with nothing. It allows adding comments to templates. The comment-text can be any characters except new line and the "/}" sequence.

Example:
This example includes a comment reminding the developer to complete something. In this case replace a hard coded English string with a localizable text message.

<span>Name: &P1_NAME.</span> {!to do replace Name: with text message/}

Escape open bracket '{'

Syntax:

{{/}

In rare cases a lone open bracket '{' can be confused for the start of a directive if another directive follows it on the same line.

Example:
This is an example where the open bracket '{' has to be escaped.

<span>The coordinates {{/}c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>

Here are similar cases that don't require an escape.

<span>The coordinates { c, d } = {if VAL/}&VAL.{else/}unknown{endif/}</span>

<span>The coordinates {c, d} =
{if VAL/}&VAL.{else/}unknown{endif/}</span>

apex.jQuery( "#photo" ).html(
    apex.util.applyTemplate(
        "<img src='&IMAGE_PREFIX.people/&P1_PROFILE_IMAGE_FILE.'>" ) );

var options = { placeholders: { MESSAGE: "All is well." } };
apex.jQuery( "#notification" ).html( apex.util.applyTemplate( "<div>#MESSAGE#</div>", options ) );

Compare two arrays and return true if they have the same number of elements and each element of the arrays is strictly equal to each other. Returns false otherwise. This is a shallow comparison.

apex.util.arrayEqual( [1,"two",3], [1, "two", 3] );

apex.util.arrayEqual( [1,"two",3], [1, "two", "3"] );

Wrapper around cancelAnimationFrame that can fallback to clearTimeout. Cancels the callback using the id returned from apex.util.invokeAfterPaint.

Returns a new function that calls pFunction but not until pDelay milliseconds after the last time the returned function is called.

function formatValue() {
    var value = $v("P1_PHONE_NUMBER");
    // code to format value as a phone number
    $s("P1_PHONE_NUMBER_DISPLAY", value);
}
apex.jQuery( "#P1_PHONE_NUMBER" ).on( "keypress", apex.util.debounce( formatValue, 100 ) );

Returns string pValue with any CSS meta-characters escaped. Use this function when the value is used in a CSS selector. Whenever possible if a value is going to be used as a selector, constrain the value so that it cannot contain CSS meta-characters making it unnecessary to use this function.

apex.jQuery( "#" + apex.util.escapeCSS( "my.id" ) );

Returns string pValue with any special HTML characters (&<>"'/) escaped to prevent cross site scripting (XSS) attacks. It provides the same functionality as sys.htf.escape_sc in PL/SQL.

This function should always be used when inserting untrusted data into the DOM.

apex.jQuery( "#show_user" ).append( apex.util.escapeHTML( $v("P1_UNTRUSTED_NAME") ) );

Get a JavaScript Date object corresponding to the input date string which must be in simplified ISO 8601 format. In the future Date.parse could be used but currently there are browsers we support that don't yet support the ISO 8601 format. This implementation is a little stricter about what parts of the date and time can be defaulted. The year, month, and day are always required. The whole time including the T can be omitted but if there is a time it must contain at least the hours and minutes. The only supported time zone is "Z". This function is useful for turning the date strings returned by the APEX_JSON.STRINGIFY and APEX_JSON.WRITE procedures that take a DATE value into Date objects that the client can use.

var date1 getDateFromISO8601String( result.dateString );

Returns the nested object at the given path pPath within the nested object structure in pRootObject creating any missing objects along the path as needed. This function is useful when you want to set the value of a property in a deeply nested object structure and one or more of the nested objects may or may not exist.

var o = apex.util.getNestedObject( options, "views.grid.features" );
o.cellRangeActions = false; // now options.views.grid.features.cellRangeActions === false

Gets the system scrollbar size for cases in which the addition or subtraction of a scrollbar height or width would effect the layout of elements on the page. The page need not have a scrollbar on it at the time of this call.

var size = apex.util.getScrollbarSize();

Return an htmlBuilder interface.

Wrapper around requestAnimationFrame that can fallback to setTimeout. Calls the given function before next browser paint. See also apex.util.cancelInvokeAfterPaint.

See HTML documentation for window.requestAnimationFrame for details.

var id = apex.util.invokeAfterPaint( myAnimationFunction );
// ... if needed it can be canceled
apex.util.cancelInvokeAfterPaint( id );

Function that renders a spinning alert to show the user that processing is taking place. Note that the alert is defined as an ARIA alert so that assistive technologies such as screen readers are alerted to the processing status.

var lSpinner$ = apex.util.showSpinner( $( "#container_id" ) );

lSpinner$.remove();

Returns string pText with all HTML tags removed.

apex.util.stripHTML( "Please <a href='www.example.com/ad'>click here</a>" );
// result: "Please click here"

Function that returns an array based on the value passed in pValue.

lProducts = apex.util.toArray( "Bags:Shoes:Shirts" );

lProducts = apex.util.toArray( "Bags,Shoes,Shirts", "," );

lTextFields = apex.util.toArray( jQuery("input[type=text]") );