Page items and Javascript: More than $s and $v ...
Released |
APEX version |
Database version |
September 2017 |
ab 5.0 |
ab 11.2 |
Today, most APEX applications do contain more or less Javascript code. Javascript is particularly
useful to make forms more interactive and therefore more user-friendly. Most developers know and already
have used the $s, $v and $x
functions to work with form items in Javascript. $s sets an item
value, $v retrieves it and $x determines
whether an item with the given name exists on the current page.
These functions are available in Application Express for a long time. And the names are so nicely
short and quickly typed. But actually this is shortcut syntax for the functions within the
"apex.item" Javascript namespace. And within apex.item, there are more functions
than you might think.
Before having a closer look into the functions of the apex.item namespace, let me repeat the general recommendation
about Javascript within APEX applications: Whenever possible, use declarative
Dynamic Actions instead of custom Javascript code. Your page will remain maintainable, all the
functionality will be reflected in the Application Express Dictionary Views and you will have to
care for less code. Use custom Javascript (and the functions explained below) only when dynamic actions
are not possible or not appropriate.
Given that, let's now get into the apex.item functions: First, we will need a form to play with - create
one on the well-known table
EMP. Make sure that it contains a bit more than simple text fields
(select lists, radio groups or check boxes and perhaps a date picker).
Example form: Table EMP
Now open the Javascript developer console in your browser (typically you have to press F12 for this).
Javascript developer console in your browser
Now you can start trying out some Javascript functions. Let's start with retrieving item values.
$v( "P2_ENAME" )
apex.item( "P2_ENAME" ).getValue()
Work with Javascript and page items in the developer console
apex.item provides special support for page items which are based on a list of values (select lists, radio groups or checkboxes).
As with other item types,
$v or getValue() retrieves
the selected value. Multiple values (for check boxes) will be returned as an array.
You will get the Return values, which are most often numeric keys. But sometimes,
the developer needs the Display value - which is no problem for the
displayValueFor() function.
Retrieve the display value for a page item based on a list of values
displayValueFor() only works for page items where the full list
of values is known to the browser - which is the case for select lists, radio buttons or check boxes.
For a Popup LOV, where the list of values is now known to the browser (it would typically be too large),
the function will not work.
setValue() allows to change the value of a page item. It supports
the differences and specialities of the various item types. So, when executed on a select list, the
browser will automatically select the correct option. Note that you have to provide the
return value for page items based on list of values. To set multiple values (e.g. for checkboxes), pass
the values as a Javascript array.
select
As already mentioned, for Popup LOV items the browser does not know the list of values. So, if only the
return value were provided, APEX would not know what to display, so it will actually display the return value.
Thus apex.item.setValue() allows to explicitly pass the display value as well. Note that you only
need this for item types like Popup LOVs.
For the popup LOV item type, setValue can set return and display values
setValue() also allows to suppress the change event.
By default, using setValue() will lead to the same sitation as if the end user had manually modified the
item value. So the browser will fire the change event, Dynamic Actions for that change event will
be fired and their functionality will be executed. In some situations, developers want to change
a page item's value but to not have dynamic actions fired.
For these cases, use the third ("pSuppressChangeEvent") argument
of the setValue() function as follows. Now dynamic actions to be executed on change
will not execute.
apex.item( "P2_ENAME" ).setValue( "DOE", null, true )
And apex.item can do even more: You'll find functions for all the things you can do with
dynamic actions (show, hide, enable, disable, set focus, assign a CSS style).
- Show and Hide
apex.item( "P2_ENAME" ).hide() und apex.item( "P2_ENAME" ).show()
Hide page items
- Enable and Disable
apex.item( "P2_ENAME" ).enable() und apex.item( "P2_ENAME" ).disable()
Disable page items
The isChanged() function is also worth a closer look. Right after
page load, all page items have not been modified. Thus, the function will return
false. As soon as the end user changes values (or setValue() has been
called), the isChanged() function will return true for that page item.
So you can use isChanged() to determine whether item values have been changed - which can be pretty useful
when it's about to decide whether, for instance, an AJAX request to the server is required. If no item
has been changed, you might save on roundtrips to the server.
Has the value of a page item been changed? The isChanged() function knows the answer.
Last but not least the setStyle() function allows to assign
a CSS style to a page item. That is useful to highlight page items in specific sitautions, for instance
after a validation failed or after other fields have been set. The CSS style properties are to be
passed as a Javascript object in JSON style.
Highlight a form item using CSS styles
Feel free to play with these functions a bit. The browsers' developer console is very helpful when
exploring the functionality. You can use these functions whereever you are using Javascript within
your application - making forms more interactive and user-friendly.
back to blogs.oracle.com/apex
|