addValue |
function
|
function(value, displayValue) Specify a function for adding a value to the item,
where the item supports multiple values. This is called by the item#addValue method which has no default
behavior for adding a value. Currently there is no client-side functionality of Oracle Application Express dependent on this.
Note: Even if this function is defined, the default handling always calls the afterModify method. |
afterModify |
function
|
function() Specify a function that is called after an item is modified.
This is useful, for example as some frameworks need to be notified if widgets are
modified, for example their value has been set, or they have been disabled in order to keep both the native
and enhanced controls in sync. This callback provides the hook to do so.
Note: This callback is deprecated. |
delayLoading |
boolean
|
Specify if the item needs to delay APEX page loading. There are many places
in the APEX framework where client-side logic is run after the page has finished loading, for example Dynamic Actions
set to 'Fire on Initialization', or code defined in the page level attribute 'Execute when Page Loads'. If an item
takes longer to initialize (for example if it uses a module loader like requirejs to load additional modules,
or if the underlying JavaScript widget itself takes longer to initialize), setting delayLoading to true allows
you to tell APEX to wait for your item to finish initializing, before firing it's built in page load logic. This
allows you as a developer to ensure that your item is compatible with these built-in APEX features like Dynamic
Actions.
When this is set to true, apex.item.create will return a jQuery
deferred object, which will need to be resolved in order for page loading to complete.
Note: If using this option, you must ensure your item initializes as quickly as possible, and also that
the returned deferred object is always resolved, to avoid disrupting the default APEX page load behavior. |
disable |
function
|
function() Specify a function for disabling the item, which overrides the
default item#disable behavior. The default behavior sets the disabled property of the item node to true.
Providing this override could be useful for example where the item consists of compound elements which
also need disabling, or if the item is based on a widget that already has its own disable method that you want
to reuse. Ensuring the item can disable correctly means certain item related client-side functionality of
Oracle Application Express still works, for example when using the Disable action of a Dynamic Action to disable
the item.
Note: Even if this function is defined, the default handling always calls the afterModify method. |
displayValueFor |
function
|
function(value, [state]):string Specify a function that returns a string
display value that corresponds to the given value. This overrides the default behavior of the
item#displayValueFor method. The default behavior supports a standard select element and conceals the
value of password inputs. |
enable |
function
|
function() Specify a function for enabling the item, which overrides the
default item#enable behavior. The default behavior sets the disabled property of the item node to false.
Providing this override could be useful for example where the item consists of compound elements which
also need enabling, or if the item is based on a widget that already has its own enable method that you want
to reuse. Ensuring the item can enable correctly means certain item related client-side functionality
of Oracle Application Express still works, for example when using the Enable action of a Dynamic Action
to enable the item.
Note: Even if this function is defined, the default handling always calls the afterModify method. |
getValidationMessage |
function
|
function():string Specify a function to return the
validation message, which overrides the default item#getValidationMessage behavior. |
getValidity |
function
|
function():ValidityState Specify a function that returns a
validity state object, which overrides the default item#getValidity behavior.
The returned object must at a minimum have the Boolean valid property. It may include any of the properties
defined for the HTML5 ValidityState object. The default implementation returns the validity object of
the item element if there is one otherwise it returns { valid: true }. |
getValue |
function
|
function():string Specify a function for getting the item's value,
which overrides the default item#getValue behavior. The default behavior handles
the standard HTML form elements. Ensuring the item returns its value correctly means certain item related
client-side functionality of Oracle Application Express still works, for example in Dynamic Actions to evaluate
a When condition on the item, or when calling the JavaScript function $v to get the item's value. |
hide |
function
|
function() Specify a function for hiding the item, which overrides the default
item#hide behavior. This could be useful for example where the item consists of compound elements which also
need hiding, or if the item is based on a widget that already has its own hide method that you want to reuse.
Ensuring the item can hide correctly means certain item related client-side functionality of Application
Express still works, for example when using the Hide action of a Dynamic Action, to hide the item.
Note: if the item is in an element with an id that matches the name of the item with a '_CONTAINER' suffix
then the container element is hidden and this function is not called. |
isChanged |
function
|
function():Boolean Specify a function that returns true if the
current value of the item has changed and false otherwise, which overrides the default item#isChanged
behavior. This function allows the Warn on Unsaved Changes feature to work.
The default implementation uses built-in functionality of HTML form elements to detect changes.
If this function does not work correctly then changes to the plug-in item type value will not be
detect and the user will not be warned when they leave the page. |
isDisabled |
function
|
function():Boolean Specify a function that returns true if the
item is disabled and false otherwise, which overrides the default item#isDisabled behavior.
Ensuring the item returns its value correctly means certain item related client-side functionality of
Oracle Application Express still works, for example client-side validation and Interactive Grid. |
getPopupSelector |
function
|
function():string Specify a function that returns a
CSS selector that locates the popup used by the item.
Any plug-in item type that uses a popup (a div added near the end of the document
that is positioned near the input item and floating above it) needs to provide a CSS selector that locates
the top level element of the popup. This allows the item type to be used in the Interactive Grid region or
any other region that needs to coordinate focus with the popup. The default implementation returns null.
In addition the top level popup element must be focusable (have attribute tabindex = -1).
For best behavior of a popup in the Interactive Grid. The popup should:
- have a way of taking focus
- close on escape when it has focus
- close when the element it is attached to loses focus
- return focus to the element that opened the popup when it closes
- manage its tab stops so they cycle in the popup or return to the element that opened the popup at the ends
|
loadingIndicator |
function
|
function(loadingIndicator$):jQuery Specify a function that normalizes
how the item's loading indicator is displayed during a partial page refresh of the item.
This function must pass the pLoadingIndicator$ parameter as the first parameter, which contains a
jQuery object with a reference to the DOM element for the loading indicator. The function then adds
this loading indicator to the appropriate DOM element on the page for the item, and also returns the
jQuery object reference to the loading indicator, such that the framework has a reference to it,
so it can remove it once the call is complete.
This is used, for example, if the item is a Cascading LOV and the Cascading LOV Parent Item changes,
or when setting the item's value by using one of the server-side Dynamic Actions such as
Set Value - SQL Statement. |
nullValue |
string
|
Specify a value to be used to determine if the item is null.
This is used when the item supports definition of a List of Values, where a developer can define a
Null Return Value for the item and where the default item handling needs to know this in order to
assert if the item is null or empty. This can be done by following these steps:
From the Render function in the plug-in definition, emit the value stored in p_item.lov_null_value as
part of the item initialization JavaScript code that fires when the page loads. For example:
# Assumes that you have some JavaScript function called 'com_your_company_your_item'
# that accepts 2 parameters, the first being the name of the item and the second being
# an object storing properties (say pOptions) required by the item's client side code.
apex_javascript.add_onload_code (
p_code => 'com_your_company_your_item('||
apex_javascript.add_value(
apex_plugin_util.page_item_names_to_jquery(p_item.name)||', {'||
apex_javascript.add_attribute(
'lovNullValue', p_item.lov_null_value, false, false)||
'});' );
Then, in the implementation of com_your_company_your_item( pName, pOptions ) you have the value defined for
the specific item's Null Return Value in the pOptions.lovNullValue property. This can then be used in your
call to apex.item.create, to set the nullValue property.
Ensuring the nullValue property is set means certain item related client-side functionality of
Oracle Application Express still works, for example, in Dynamic Actions to correctly evaluate an is null
or is not null when condition on the item, or when calling the JavaScript function
item#isEmpty to determine if the item is null. |
refresh |
function
|
function() Specify a function to refresh the item.
This is called by the item#refresh method. The default behavior triggers event "apexrefresh"
for legacy plug-in items. |
reinit |
function
|
function(value, display):function Specify a function to
initialize an item's value when it is reused in a new context. This is only called for column items every time
a new record is being edited. The default behaviour calls item#setValue and suppresses the change event.
Items that support cascading LOVs should implement this function to first set the item's value (which may also
require adding the value as an option in the item), then return a function where the cascade will take place. |
removeValue |
function
|
function(value) Specify a function for removing a value from the item,
where the item supports multiple values. This is called by the item#removeValue method which has no default
behavior for removing a value. Currently there is no client-side functionality of Oracle Application Express dependent on this.
Note: Even if this function is defined, the default handling always calls the afterModify method. |
setFocusTo |
Element
|
string
|
function
|
Specify the element to receive focus
when focus is set to the item using the item#setFocus method. This can be defined as either a jQuery
selector, jQuery object or DOM Element which identifies the DOM element, or a no argument function that returns a jQuery
object referencing the element. This can be useful when the item consists of compound elements,
and you do not want focus to go to the element that has an ID matching the item name, which is the
default behavior.
Ensuring the item sets focus correctly means certain item related client-side functionality of
Oracle Application Express still works, for example when using the Set Focus action of a Dynamic Action to
set focus to the item, when users follow the Go to Error link that displays in a validation error
message to go straight to the associated item, or when the item is the first item on a page and
the developer has the page level attribute Cursor Focus set to First item on page. |
setStyleTo |
Element
|
string
|
function
|
Specify the element to receive style, when style is set to
the item using the item#setStyle method. This can be defined as either a jQuery selector,
jQuery object or DOM Element which identifies the DOM element(s), or a no argument function that returns a jQuery object
referencing the element(s). This is useful when the item consists of compound elements, and you do not
want style to be set to the element or just the element, that has an ID matching the item name which is
the default behavior.
Ensuring the item sets style correctly means certain item related client-side
functionality of Oracle Application Express still works, for example when using the Set Style action of a
Dynamic Action to add style to the item.
Note: Even if this property is defined, the default behavior of item#setStyle calls the afterModify method. |
setValue |
function
|
function(value, displayValue, suppressChangeEvent) Specify a function for
setting the item's value, which overrides the default item#setValue behavior. The default behavior handles
the standard HTML form elements. Ensuring the item can set its value correctly means certain item related
client-side functionality of Oracle Application Express still works, for example
when using the Set Value action of a Dynamic Action to set the item's value, or when calling the
JavaScript function $s to set the item's value.
Note: Even when this function is defined, the default handling always calls the afterModify function and
triggers the change event according to the pSuppressChangeEvent parameter. The pSuppressChangeEvent parameter
is provided to this function for informational purpose only. In most cases it can be ignored. |
show |
function
|
function() Specify a function for showing the item, which overrides the
default item#show behavior. This is useful for example where the item consists of compound elements which
also need showing, or if the item is based on a widget that already has its own show method that you want
to reuse. Ensuring the item can show correctly means certain item related client-side functionality of
Oracle Application Express still works, for example when using the Show action of a Dynamic Action, to show the item.
Note: if the item is in an element with an id that matches the name of the item with a '_CONTAINER' suffix
then the container element is shown and this function is not called. |