The apex.item namespace contains global functions related to Oracle APEX items. The apex.item.create function defines the behavior for an item type. The apex.item function provides access to an item interface for a specific item.
This function is only for item plug-in developers. It provides a way for item plug-ins to initialize without having to render a call to a JavaScript function. The handler function is called when the page initializes.
Parameters:
Name | Type | Description |
---|---|---|
pHandler |
function | pHandler( pContext$ ). A function provided by the plug-in that will initialize all item instances of the plug-in type. The function receives a jQuery object that is the context in which the item(s) can be found. |
- Since:
- 20.2
Example
In this example the plug-in render function produces an input element with class "mySuperInput". The following code goes in the plug-in's JavaScript file.
const mySuperInputPrototype = {
type: "MY_SUPER_INPUT",
// other item interface methods ...
};
function attachMySuperInput( pContext$ ) {
$( "input.mySuperInput", pContext$ ).each( function() {
var myItem$ = $(this);
// Do what is needed to initialize the plug-in myItem$ element.
apex.item.create( this.id, mySuperInputPrototype );
} );
}
apex.item.addAttachHandler( attachMySuperInput );
This function is only for item plug-in developers. It provides a plug-in specific implementation for the item.
This is necessary to seamlessly integrate a plug-in item type with the built-in item
related client-side functionality of Oracle APEX. A plug-in should call this method even if
it passes in an empty pItemImpl
object. See also apex.item.addAttachHandler.
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pItemId |
Element | string | The item name. This is also the id of the main DOM element associated with the item. For backward compatibility this can also be the main item DOM Element. Passing in an element is deprecated and the id/name should be used instead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pItemImpl |
object | function | An object with properties that provide any functions needed to customize the
Oracle APEX item instance behavior. All the properties of this object are copied to
the item interface so it is possible to add additional methods or properties to it.
The item interface has default implementations
for each of its methods that are appropriate for many page items particularly for items that use standard
form elements. For each method of item you should check if the default handling is appropriate for
your item plug-in. If it isn't you can provide your own implementation of the corresponding function
through this pItemImpl object. The default behavior is used for any functions omitted.
This parameter can also be a function that is called during creation with a single object argument that is the base item interface. The function should add any needed functions or properties to the item interface. ItemImpl can contain any of the following properties: Properties
|
- Since:
- 5.1
Returns:
jQuery
Deferred object when delayLoading is set
to true. The jQuery
deferred object must be resolved in order for the
APEX page load to complete. If delayLoading is set to false (the default), then nothing is returned.
- Type
- object
Examples
The following example shows a call to apex.item.create( pNd, pItemImpl ) with most available callbacks and properties passed to illustrate the syntax (although it is unlikely that any plug-in needs to supply all of these).
apex.item.create( "P100_COMPANY_NAME", {
item_type: "FANCY_ITEM",
displayValueFor: function( pValue ) {
var lDisplayValue;
// code to determine the display value for pValue
return lDisplayValue;
},
getPopupSelector: function() {
return "<some CSS selector>";
},
getValidity: function() {
var lValidity = { valid: true };
if ( <item is not valid expression> ) {
lValidity.valid = false;
}
return lValidity;
},
getValidationMessage: function() {
// return validation message if invalid or empty string otherwise
},
getValue: function() {
var lValue;
// code to determine lValue based on the item type.
return lValue;
},
setValue: function( pValue, pDisplayValue ) {
// code that sets pValue and pDisplayValue (if required), for the item type
},
reinit: function( pValue, pDisplayValue ) {
// set the value possibly using code like
// this.setValue( pValue, null, true );
return function() {
// make an ajax call that gets new option values for the item
}
},
disable: function() {
// code that disables the item type
},
enable: function() {
// code that enables the item type
},
isDisabled: function() {
// return true if item is disabled and false otherwise
}
show: function() {
// code that shows the item type
},
hide: function() {
// code that hides the item type
},
isChanged: function() {
var lChanged;
// code to determine if the value has changed
return lChanged;
},
addValue: function( pValue ) {
// code that adds pValue to the values already in the item type
},
nullValue: "<null return value for the item>",
setFocusTo: $( "<some jQuery selector>" ),
setStyleTo: $( "<some jQuery selector>" ),
loadingIndicator: function( pLoadingIndicator$ ){
// code to add the loading indicator in the best place for the item
return pLoadingIndicator$;
}
});
The following example shows a call to apex.item.create( pNd, pItemImpl ) with delayLoading option set to true. Doing so results in the create function returning a deferred object, which must be later resolved in order for page load to complete.
var lDeferred = apex.item.create( "P100_COMPANY_NAME", {
// provide other callback functions as needed
delayLoading: true
});
// At some point later in the code when the item has finished its initialization, resolve the deferred object
lDeferred.resolve();
The following example shows a call to apex.item.create where the pItemImpl argument is a function. This item plug-in provides its own custom logic for the setValue function. The plug-in supports multiple toolbar modes which can be set programmatically with the custom function setToolbarMode.
apex.item.create( itemName, function( baseItem ) {
baseItem.setValue = function( pValue, pDisplayValue ) {
// code that sets pValue and pDisplayValue (if required), for the item type
};
// provide other callback functions as needed
baseItem.setToolbarMode = function( pMode ) {
// implementation to set the toolbar mode
};
// other custom functions as needed
} );
// later the custom function can be used as follows
apex.item( itemName ).setToolbarMode( "EXPANDED" );
This function returns true if and only if there is a DOM element with id equal to pItemId that has had an item interface created for it with apex.item.create.
For backward compatibility with items that don't call apex.item.create a default implementation of item is used to treat any DOM element with an id as if it were an APEX item. There are some simple items with only default behavior that can be used as an item even though isItem returns false for it. This function allows you to distinguish items that explicitly create an item interface from arbitrary DOM elements.
Parameters:
Name | Type | Description |
---|---|---|
pItemId |
string | Item id. |
Returns:
- Type
- boolean
Example
The following will only hide the item if it is an APEX item.
if ( apex.item.isItem( someId ) ) {
apex.item( someId ).hide();
}