apex.util namespace

apex.util namespace contains general utility functions of Oracle Application Express.

apex.util.escapeCSS

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

Parameters

Table 38-73 apex.util.escapeCSS

Name	Type	Description
`pValue`	String	The string that may contain CSS meta-characters to be escaped.

Returns

The escaped string.

Example

This example escapes an element id that contains a (.) period character so that it finds the element with id = “my.id”. Without using this function the selector would have a completely different meaning.

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

Parent topic: apex.util namespace

apex.util.escapeHTML

Returns string pValue with any special HTML characters (&<>"'/) escaped to prevent cross site scripting (XSS) attacks.

Note:

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

Parameters

Table 38-74 apex.util.escapeHTML

Name	Type	Description
`pValue`	String	The string that may contain special HTML characters to be escaped.

Returns

The escaped string.

Example

This example appends text to a DOM element where the text comes from a page item called P1_UNTRUSTED_NAME. Data entered by the user cannot be trusted to not contain malicious markup.

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

Parent topic: apex.util namespace

apex.util.showSpinner

Function that renders a spinning alert to show the user 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.

Parameters

Table 38-75 util.showSpinner

Name	Type	Description
`pContainer`	Object	Optional jQuery selector, jQuery, or DOM object identifying the container within which you want to center the spinner. If not passed, the spinner will be centered on the whole page. The default is `$("body")`.
`pOptions`	Object	Optional object with the following options: - "alert" Alert text visually hidden, but available to assistive technologies. Defaults to Processing. The default is `Processing`.

Returns

jQuery object for the spinner.

Example

To show the spinner:

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

To remove the spinner:

 lSpinner$.remove();

Parent topic: apex.util namespace

apex.util.stripHTML

Return string pText with all HTML tags removed.

Parameters

Table 38-76 apex.util.stripHTML

Name	Type	Description
`pText`	String	A string that may contain HTML markup that you want removed.

Returns

The input string with all HTML tags removed.

Example

This example removes HTML tags from a text string.

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

Parent topic: apex.util namespace

apex.util.applyTemplate

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 do prepare_url (this must be done on the server). Using a template to insert JavaScript into the DOM is not supported. The template after processing will have script tags removed.

The format of a template string is any text intermixed with any number of replacement tokens. Two kinds of replacement tokens are supported: placeholders and substitutions. Placeholders are processed first.

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).

Substitution syntax is (any of):

     &<item-name>.
     &<item-name>!<escape-filter>.
     &"<quoted-item-name>".
     &"<quoted-item-name>"!<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. If no replacement for a substitution can be found it is replaced with an empty string. 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. 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.

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.
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.

Parameters

Table 38-77 defaultEscapeFilter

Name	Type	Description
`pTemplate`	String	A template string with the format described above.
`pOptions`	Object	An object that specifies how the template is to be processed. Refer to the following `pOptions` properties table.

Table 38-78 pOptions properties

Name	Description
`placeholders`	An object map of placeholder names to values. The default is`null`.
`defaultEscapeFilter`	One of the above escape-filter values. The default is HTML. This is the escaping/filtering that is done if the substitution token doesn't specify an escape-filter. If a model column definition has an escape property then it will override the default escaping.
`includePageItems`	If `true` the current value of page items are substituted. The default is `true`.
`model`	The Application Express model used to get column item values. The default is `null`.
`record`	The record in the model to get column item values from. Option model must also be provided. The default is `null`.
`extraSubstitutions`	An object map of extra substitutions. The default is `null`.
`includeBuiltinSubstitutions`	If `true` built-in substitutions such as `APP_ID` are done. The default is `true`.

Returns

A string that is the template with all the replacement tokens substituted.

Examples

This example inserts an image tag where the path to the image comes from the built-in IMAGE_PREFIX substitution and a page item called P1_PROFILE_IMAGE_FILE.

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

This example inserts a div with a message where the message text comes from a placeholder called MESSAGE.

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

Parent topic: apex.util namespace

About apex.util.delayLinger

The delayLinger singleton solves the problem of flashing progress indicators (such as spinners ). For processes such as an Ajax request (and subsequent user interface update) that may take a while it is important to let the user know that something is happening. The problem is that if an async process is quick there is no need for a progress indicator. The user experiences the user interface update as instantaneous. Showing and hiding a progress indicator around an async process that lasts a very short time causes a flash of content that the user may not have time to fully perceive. At best this can be a distraction and at worse the user wonders if something is wrong or if they missed something important. Simply delaying the progress indicator doesn't solve the problem because the process could finish a short time after the indicator is shown. The indicator must be shown for at least a short but perceivable amount of time even if the request is already finished.

You can use this object to help manage the duration of a progress indication such as apex.util.showSpinner or with any other progress implementation. Many of the Oracle Application Express asynchronous functions such as the ones in the apex.server namespace already use delayLinger internally so you only need this API for your own custom long running asynchronous processing.

Parent topic: apex.util namespace

apex.util.delayLinger.start

Call this function when a potentially long running async process starts. For each call to start with a given pScopeName, you must make a corresponding call to finish with the same pScopeName. Calls with different pScopeName arguments will not interfere with each other.

Multiple calls to start for the same pScopeName before any calls to finish is allowed but only the pAction from the first call is called at most once.

Parameters

Table 38-79 apex.util.delayLinger.start Function Parameters

Name	Type	Description
`pScopeName`	String	Unique name for each unique progress indicator.
`pAction`	Function	Function called to display the progress indicator.

Parent topic: apex.util namespace

apex.util.delayLinger.finish

Call this function when a potentially long running async process finishes. For each call to start with a given pScopeName, you must make a corresponding call to finish with the same pScopeName. The pAction is called exactly once if and only if the corresponding start pAction was called. If there are multiple calls to finish, the pAction from the last one is called.

Parameters

Table 38-80 apex.util.delayLinger.finishFunction Parameters

Name	Type	Description
`pScopeName`	String	Unique name for each unique progress indicator
`pAction`	Function	Function to call to display the progress indicator

Example

var lSpinner$, lPromise;
lPromise = doLongProcess();
apex.util.delayLinger.start( "main", function() {
    lSpinner$ = apex.util.showSpinner( $( "#container_id" ) );
} );
lPromise.always( function() {
    apex.util.delayLinger.finish( "main", function() {
        lSpinner$.remove();
    } );
} );

Parent topic: apex.util namespace