Page items and Javascript: More than $s and $v ...

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