Skip Headers
Oracle® Application Express API Reference
Release 4.1

Part Number E21676-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
PDF · Mobi · ePub

20 JavaScript APIs

This section describes JavaScript functions and objects included with Oracle Application Express and available on every page. You can use these functions and objects to provide client-side functionality, such as showing and hiding page elements, or making XML HTTP Asynchronous JavaScript and XML (AJAX) requests.

Topics:


apex.event.trigger(pSelector,pEvent,pData)

Given a jQuery selector, jQuery object or DOM Node the specified pEvent will be triggered. pEvent can be a browser event like "click" or "change" but also a custom event like "slidechange". This function should only be used to trigger events that are handled by the dynamic action framework. Otherwise, custom events registered by plug-ins installed in your application or any event that is already exposed in dynamic actions can be compromised.

Return Value

Boolean

Parameters

pSelector (jQuery selector | jQuery object | DOM Node)
pEvent (String)
pData (Object)

apex.widget.initPageItem(pName,pOptions)

Given a page item name different options can be registered for a page item with the Application Express JavaScript framework. This is necessary to seamlessly integrate a plug-in item type with the built-in page item related JavaScript functions of Application Express.

Parameters

pName (string)
pOptions (Object)

$x(pNd)

Given a DOM node or string ID (pNd), this function returns a DOM node if the element is on the page, or returns false if it is not.

Return Value

(DOM Node | false)

Parameters

pNd (DOM Node | string ID)

$v(pNd)

Given a DOM node or string ID (pNd), this function returns the value of an Application Express item in the same format as it would be posted.

Parameters

pNd (DOM Node | string ID)

$v2(pNd)

Given a DOM node or string ID (pNd), this function returns the value of an Application Express item as a string or an array. If the page item type can contain multiple values like a shuttle, checkboxes or a multi select list an array will be returned, otherwise a string.

Return Value

(string|array)

Parameters

pNd (DOM Node | string ID)

$s(pNd, pValue, pDisplayValue, pSuppressChangeEvent)

Given a DOM node or string ID (pNd), this function sets the Application Express item value taking into account the item type. The pDisplayValue is optional. If used for a page item of type "Popup LOV" where the attribute "Input Field" = "Not Enterable, Show Display Value and Store Return Value", it is used to set the "Input Field". The value of pValue will be stored in the hidden return field. The pSuppressChangeEvent parameter is optional. Passing either FALSE or not passing this parameter value results in a change event firing for the item being set. Pass TRUE to prevent the change event from firing for the item being set.

Parameters

pNd (DOM Node | string ID)
pValue  (String | Array)
pDisplayValue(String)
pSuppressChangeEvent(Boolean)

$u_Carray(pNd)

Given a DOM node or string ID or an array (pNd), this function returns an array. Used for creating DOM based functionality that can accept a single or multiple DOM nodes.

Return Value

pNd (DOM Node | string ID | Array)

Parameters

Array

$u_Narray(pNd)

Given a DOM node or string ID or an array (pNd), this function returns a single value, if an pNd is an array but only has one element the value of that element will be returned otherwise the array will be returned. Used for creating DOM based functionality that can accept a single or multiple DOM nodes.

Return Value

Array (DOM Node | string ID | Array)

Parameters

Array or first value

$nvl(pTest, pDefault)

If pTest is empty or false return pDefault otherwise return pTest.

Return Value

(string | Array)

Parameters

pTest  (String | Array)
pDefault (String | Array)

apex.submit(pOptions)

This function submits the page using the options sepcified in pOptions.

Parameters

pOptions (Object)
where Object can contain the following options:

request - The request value to set (defaults to null)
set - Object conatining name/value pairs of items to be set on the page prior to submission(defaults to null).
showWait - Flag to control if a 'Wait Indicator' icon is displayed, which can be useful when running long page operations (Defaults to false).

Example

This example submits the page with a REQUEST value of 'DELETE' and 2 page item values are set, P1_DEPTNO to 10 and P1_EMPNO to 5433. During submit a wait icon is displayed as visual indicator for the user as well.

apex.submit({  request:"DELETE",  set:{"P1_DEPTNO":10, "P1_EMPNO":5433},  showWait:true});

apex.submit(pRequest)

This function submits the page setting the Application Express Request value pRequest.

Parameters

pRequest (String)

Example

Submits the current page with a REQUEST value of 'DELETE'.

apex.submit({
  request:"DELETE",
  set:{"P1_DEPTNO":10, "P1_EMPNO":5433});

apex.confirm(pMessage, pRequest)

Displays a confirmation showing a message (pMessage) and depending on user's choice, submits a page setting request value (pRequest) or cancels page submit.

Parameters

pMessage (string)
pRequest (string)

Example

This example shows a confirmation dialog with the text 'Delete Department'. If the user chooses to proceed with the delete, the current page is submitted with a REQUEST value of 'DELETE'

apex.confirm('Delete Department', 'DELETE');

apex.confirm(pMessage, pOptions)

Displays a confirmation showing a message (pMessage) and depending on user's choice, submits a page setting request values specified by (pOptions) or cancels page submit.

Parameters

pMessage (string)
pOptions (object)
Object can contain the following options:
request - The request value to be set (Defaults to null)
set - Object containing name / value pairs of items to be set on the page prior to submission (Defaults to null)

Example 1

This example shows a confirmation message with the 'Save Department?' text. If the user chooses to proceed with the save, the page is submitted with a REQUEST value of 'SAVE' and 2 page item values are set, P1_DEPTNO to 10 and P1_EMPNO to 5433."

apex.confirm("Save Department?", {
  request:"SAVE",
  set:{"P1_DEPTNO":10, "P1_EMPNO":5433}

  });

Example 2

This example submits the current page and sets the REQUEST value to SAVE.

apex.submit('SAVE');

$x_Style(pNd, pStyle, pString)

Sets a specific style property (pStyle) to given value (pString) of a DOM node or DOM node Array (pNd).

Return Value

(DOM node | DOM Array)

Parameters

pNd (DOM node | string ID | DOM node Array )
pStyle (String)
pString (String)

$x_Hide(pNd)

Hides a DOM node or array of DOM nodes (pNd). This will also take into consideration which type of Application Express item is being hidden.

Return Value

(DOM node | Array)

Parameters

pNd (DOM node | string ID | DOM node Array )

$x_Show(pNd)

Shows a DOM node or array of DOM nodes (pNd). This will also take into consideration which type of Application Express item is being hidden.

Return Value

(DOM node | Array)

Parameters

pNd (DOM node | string ID | DOM node Array )

$x_Toggle(pNd)

Toggles a DOM node or array of DOM nodes (pNd).

Return Value

(DOM node | Array)

Parameters

pNd (DOM node | string ID | Array)

$x_Remove(pNd)

Removes a DOM node or array of DOM nodes.

Return Value

(DOM Node | Array)

Parameters

pNd (DOM node | string ID | DOM node Array)

$x_Value(pNd,pValue)

Sets the value (pValue) of a DOM node or array of DOM nodes (pNd).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node Array)
pValue (String)

$x_UpTill(pNd, pToTag)

Starting from a DOM node (pNd), this function cascades up the DOM tree until the tag of node name (pToTag) is found.

Return Value

(DOM Node | false)

Parameters

pNd  (DOM Node | string ID) 
String (pToTag) 
String (pToClass ) 

$x_ItemRow(pNd,pFunc)

Given DOM node or array of DOM nodes, this function (shows, hides, or toggles) the entire row that contains the DOM node or array of DOM nodes. This is most useful when using Page Items.

Return Value

Not applicable.

Parameters

pNd (DOM Node | string ID | Dom node Array) 
pFunc ['TOGGLE','SHOW','HIDE'] (String )

$x_HideItemRow(pNd)

Given a page item name, this function hides the entire row that holds the item. In most cases, this will be the item and its label.

Return Value

Not applicable.

Parameters

pNd (DOM Node | string ID | DON node Array)

$x_ShowItemRow(pNd)

Given a page item name, this function shows the entire row that holds the item. In most cases, this will be the item and its label.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM note Array)

$x_ToggleItemRow(pNd)

Given a page item name (pNd), this function toggles the entire row that holds the item. In most cases, this will be the item and its label.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node ray)

$x_HideAllExcept(pNd,pNdArray)

Hides all DOM nodes referenced in pNdArray and then shows the DOM node referenced by pNd. This is most useful when pNd is also a node in pNdArray.

Return Value

(DOM node | DOM Array)

Parameters

pNd (DOM node | string ID | DOM node Array) 
pNdArray (DOM node | String | Array)

$x_HideSiblings(pNd)

Hides all sibling nodes of given pNd.

Return Value

(DOM node)

Parameters

pNd (DOM node | string ID )

$x_ShowSiblings(pNd)

Shows all sibling DOM nodes of given DOM nodes (pNd).

Return Value

(DOM node)

Parameters

pNd (DOM node | string ID )

$x_Class(pNd,pClass)

Sets a DOM node or array of DOM nodes to a single class name.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node Array)
pClass (String)

$x_SetSiblingsClass(pNd, pClass, pNdClass)

Sets the class (pClass) of all DOM node siblings of a node (pNd). If pNdClass is not null the class of pNd is set to pNdClass.

Return Value

(DOM node | false)

Parameters

pNd (DOM Nnde | string ID)
pClass (String)
pThisClass (String)

$x_ByClass(pClass, pNd, pTag)

Returns an array of DOM nodes by a given class name (pClass). If the pNd parameter is provided, then the returned elements will be all be children of that DOM node. Including the pTag parameter further narrows the list to just return nodes of that tag type.

Return Value

(Array)

Parameters

pClass (String)
pNd  (DOM node | string ID)
pTag (String)

$x_ShowAllByClass(pNd, pClass, pTag)

Show all the DOM node children of a DOM node (pNd) that have a specific class (pClass) and tag (pTag).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID)
pClass (String)
pTag (String)

$x_ShowChildren(pNd)

Show all DOM node children of a DOM node (pNd).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID)

$x_HideChildren(pNd)

Hide all DOM node children of a DOM node (pNd).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID)

$x_disableItem(pNd, pTest)

Disables or enables an item or array of items based on (pTest).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node array)
a (true | false)

$f_get_emptys(pNd, pClassFail, pClass)

Checks an item or an array of items to see if any are empty, set the class of all items that are empty to pClassFail, set the class of all items that are not empty to pClass.

Return Value

false, Array  Array of all items that are empty (false | Array)

Parameters

pNd (DOM node | string ID | DOM node Array)
Sting (pClassFail)
Sting (pClass)

$v_Array(pNd)

Returns an item value as an array. Useful for multiselects and checkboxes.

Return Value

(Array)

Parameters

pId (DOM Node | string ID)

$f_ReturnChecked(pNd)

Returns an item value as an array. Useful for radio items and check boxes.

Return Value

(Array)

Parameters

pId (DOM node | string ID)

$d_ClearAndHide(pNd)

Clears the content of an DOM node or array of DOM nodes and hides them.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node array)

$f_SelectedOptions(pNd)

Returns the DOM nodes of the selected options of a select item (pNd).

Return Value

(DOM Array)

Parameters

pNd (DOM node | string ID)

$f_SelectValue(pNd)

Returns the values of the selected options of a select item (pNd).

Return Value

(DOM Array | String)

Parameters

pNd (DOM node | string ID)

$u_ArrayToString(pArray, pDelim)

Given an array (pArray) return a string with the values of the array delimited with a given delimiter character (pDelim).

Return Value

Not applicable.

Parameters

pArray (pArray)
pDelim (String)

$x_CheckImageSrc(pId,pSearch)

Checks an image (pId) source attribute for a substring (pSearch). The function returns true if a substring (pSearch) is found. It returns false if a substring (pSearch) is not found.

Return Value

(true | false)

Parameters

pId (DOM Node | String)
pSearch (pSearch)

$v_CheckValueAgainst(pThis, pValue)

Checks an page item's (pThis) value against a set of values (pValue). This function returns true if any value matches.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pValue (Number | String | Array)

$f_Hide_On_Value_Item(pThis, pThat, pValue)

Checks page item's (pThis) value against a value (pValue). If it matches, a DOM node (pThat) is set to hidden. If it does not match, then the DOM node (pThat) is set to visible.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_Show_On_Value_Item(pThis, pThat, pValue)

Checks page item's (pThis) value against a value (pValue). If it matches, a DOM node (pThat) is set to visible. If it does not match, then the DOM node (pThat) is set to hidden.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_Hide_On_Value_Item_Row(pThis, pThat, pValue)

Checks the value (pValue) of an item (pThis). If it matches, this function hides the table row that holds (pThat). If it does not match, then the table row is shown.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_Show_On_Value_Item_Row(pThis, pThat, pValue)

Checks the value (pValue) of an item (pThis). If it matches, this function shows the table row that holds (pThat). If it does not match, then the table row is hidden.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_DisableOnValue(pThis, pValue, pThat)

Checks the value (pValue) of an item (pThis). If it matches, this function disables the item or array of items (pThat). If it does not match, then the item is enabled.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pValue (String)
pThat  (DOM node | string ID | DOM node Array )

$x_ClassByClass(pNd, pClass, pTag, pClass2)

Sets a class attribute of an array of nodes that are selected by class.

Return Value

(DOM node | DOM node Array)

Parameters

pNd (DOM node | string ID)
pClass (String)
pTag (String)
pClass2 (String)

$f_ValuesToArray(pThis, pClass, pTag)

Collects the values of form items contained within DOM node (pThis) of class attribute (pClass) and nodeName (pTag) and returns an array.

Return Value

No applicable.

Parameters

pThis (DOM node | string ID)
pCLass (String)
pTag (String)

$x_FormItems(pNd, pType)

Returns all form input items contained in a DOM node (pThis) of a certain type (pType).

Return Value

DOM node Array

Parameters

pNd (DOM node | string ID)
pType (String)

$f_CheckAll(pThis, pCheck, pArray)

Check or uncheck (pCheck) all check boxes contained within a DOM node (pThis). If an array of checkboxes DOM nodes (pArray) is provided, use that array for affected check boxes.

Return Value

Not applicable.

Parameters

pThis (DOM node | string ID)
pCheck (true | fales)
pArray (DOM node array)

$f_CheckFirstColumn(pNd)

This function sets all checkboxes located in the first column of a table based on the checked state of the calling checkbox (pNd), useful for tabular forms.

Return Value

DOM node Array

Parameters

pNd (DOM node | String)

$v_PopupReturn(pValue, pThat)

Sets the value of the item in the parent window (pThat), with (pValue) and then closes the popup window.

Return Value

Not applicable.

Parameters

pValue (string)
pThat (DOM node | string ID)

$x_ToggleWithImage(pThis,pNd)

Given an image element (pThis) and a DOM node (pNd), this function toggles the display of the DOM node (pNd). The src attribute of the image element (pThis) will be rewritten. The image src will have any plus substrings replaced with minus substrings or minus substrings will be replaced with plus substrings.

Return Value

(DOM Node)

Parameters

pThis (DOM Node | string ID)
pNd (DOM Nnde | string iD | DOM node Array)

$x_SwitchImageSrc(pNd, pSearch, pReplace)

Checks an image (pId) src attribute for a substring (pSearch). If a substring is found, this function replaces the image entire src attribute with (pReplace).

Return Value

(DOM node | false)

Parameters

pNd (DOM node | string ID)
pSearch (String)
pReplace (String)

$x_CheckImageSrc(pNd, pSearch)

Checks an image (pNd) source attribute for a substring (pSearch). The function returns true if a substring (pSearch) is found. It returns false if a substring (pSearch) is not found.

Return Value

(true | fales)

Parameters

pNd  (DOM node | string ID)
pSearch (String)

$u_SubString(pText,pMatch)

Returns a true or false if a string (pText) contains a substring (pMatch).

Return Value

(true | false)

Parameters

pText (String) 
pMatch (String)

html_RemoveAllChildren(pNd)

Use DOM methods to remove all DOM children of DOM node (pND).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID) 

$v_IsEmpty(pThis)

Returns true or false if a form element is empty, this will consider any whitespace including a space, a tab, a form-feed, as empty. This will also consider any null value that has been specified on the item.

Return Value

[true | false]

Parameters

pThis (DOM Node | String)

html_SetSelectValue(pId,pValue)

Sets the value (pValue) of a select item (pId). If the value is not found, this functions selects the first option (usually the NULL selection).

Return Value

Not applicable.

Parameters

pId (DOM node | String)
pValue (String)

addLoadEvent(pFunction)

Adds an onload function (func) without overwriting any previously specified onload functions.

Return Value

Not applicable.

Parameters

pFunction (Javascript Function)

$f_Swap(pThis,pThat)

Swaps the form values of two form elements (pThis,pThat).

Return Value

Not applicable.

Parameters

pThis (DOM Node | String)
pThat (DOM Node | String)

submitEnter(pNd,e)

Submits a page when ENTER is pressed in a text field, setting the request value to the ID of a DOM node (pNd).

Usage is onkeypress="submitEnter(this,event)"

Return Value

Not applicable.

Parameters

pNd (DOM node | String | Array)

$f_SetValueSequence(pArray,pMultiple)

Sets array of form item (pArray) to sequential number in multiples of (pMultiple).

Return Value

Not applicable.

Parameters

pArray (Array) 
pMultiple (Number)

$dom_AddTag(pThis, pTag, pText)

Inserts the html element (pTag) as a child node of a DOM node (pThis) with the innerHTML set to (pText).

Return Value

DOM node

Parameters

pThis (DOM node | string ID ) 
pTag (String)
pText (String)

$tr_AddTD(pThis,pText)

Appends a table cell to a table row (pThis). And sets the content to (pText).

Return Value

(DOM node)

Parameters

pThis (DOM node | string ID)
pText (String)

$tr_AddTH(pThis,pText)

Appends a table cell to a table row (pThis). And sets the content to (pText).

Return Value

DOM node

Parameters

pThis (DOM node | string ID)
pTest (String)

$dom_AddInput(pThis,pType,pId,pName,pValue)

Inserts the html form input element (pType) as a child node of a DOM node (pThis) with an id (pId) and name (pName) value set to pValue.

Return Value

(DOM node)

Parameters

pThis (DOM node | string ID)
pType (String)
pId (String)
pName (String)
pValue (String)

$dom_MakeParent(p_Node,p_Parent)

Takes a DOM node (p_Node) and makes it a child of DOM node (p_Parent) and then returns the DOM node (pNode).

Return Value

(DOM node)

Parameters

p_This (DOM node | string ID)
p_Parent (DOM node | string ID)

$x_RowHighlight(pThis, pColor)

Give an table row DOM element (pThis), this function sets the background of all table cells to a color (pColor). A global variable gCurrentRow is set to pThis.

Return Value

Not applicable.

Parameters

pThis (DOM node | String)
pColor(String)

$x_RowHighlightOff(pThis)

Give an table row Dom node (pThis), this function sets the background of all table cells to NULL.

Return Value

Not applicable.

Parameters

pThis (DOM Element | String)

$v_Upper(pNd)

Sets the value of a form item (pNd) to uppercase.

Return Value

Not applicable.

Parameters

pNd (DOM Node | String)

$d_Find(pThis,pString,pTags,pClass)

Hides child nodes of a Dom node (pThis) where the child node's inner HTML matches any instance of pString. To narrow the child nodes searched by specifying a tag name (pTag) or a class name (pClass). Note that the child node will be set to a block level element when set to visible.

Return Value

Not applicable.

Parameters

pThis (DOM node | String)
pString (String)
pTags (String 
pClass (String)

returnInput(p_R, p_D)

Sets DOM node in the global variables returnInput (p_R) and returnDisplay (p_D) for use in populating items from popups.

Return Value

Not applicable.

Parameters

p_R (DOM node | String)
p_R (DOM node | String)

setReturn(p_R,p_D)

Sets DOM items in the global variables returnInput (p_R) and returnDisplay (p_D) for use in populating items from popups.

Return Value

Not applicable.

Parameters

p_R
p_D

$f_First_field(pNd)

Places the user focus on the a form item (pNd). If pNd is not found then this function places focus on the first found user editable field.

Return Value

true (if successful)

Parameters

pNd

GetCookie (pName)

Returns the value of cookie name (pName).

Return Value

Not applicable.

Parameters

pName (String)

SetCookie (pName,pValue)

Sets a cookie (pName) to a specified value (pValue).

Return Value

Not applicable.

Parameters

pName (String)
pValue (String)