Introduction Oracle APEX JavaScript APIs (#1 apex.item)

Hello everyone and welcome back to our Blog. In this blog series, we would like to draw your attention to some Javascript APIs provided by APEX. Those APIs will help you to write much efficient Javascript code and will make your life much easier :-).

In each post, we will take one of these APIs and demonstrate our understanding in a demo. Before we dive into the first API, let's first explain what is APEX Javascript APIs and how it works.

APEX provides some functions to make it easy for developers to interact with the items, regions, reports, and many other objects in a simpler way than using plain Javascript. You can use these functions to provide client-side functionality, such as showing and hiding page elements, or making Ajax (Asynchronous JavaScript and XML) requests.

Most of the APEX JavaScript APIs are organized into namespaces. There is one top-level APEX namespace called apex. This has a number of sub-namespaces such as apex.server and apex.util. Namespaces help to organize code and reduce the chance of name conflicts with other JavaScript libraries.

There are some older global functions that are not in a namespace. Most of them start with a $ character. These are known as Non-namespace APIs. Global symbols that begin with APEX or $ are reserved by APEX.

Some functions return an interface, which is an object that contains functions known as methods and variables known as properties, that allows access to a specific instance of a page component or other entity.

APEX also includes a number of UI widgets based on the jQuery UI widget factory. Widgets are high-level user interface components such as menus, trees, or grids. 

Now and after this introduction, let's start with the first API which is the item function. This function returns an item interface that is used to access item-related methods and properties. As of the latest APEX versions, when you call apex.item() you get back an item interface that is specific to the type of item it is. For example, the interface for a Number Field item had the extra method getNativeValue.

Let's create a demo app in apex.oracle.com and use various items to see some of the advantages of using this interface. Create a page and add a static region in it.

Please keep in mind that we are not going through all props and methods, we will just discuss the most useful ones.

Accessning Page Items

there are two ways to access one of your page items. The first option is to use the apex.item() function by providing the item name you want to access as a string, for example apex.item('P1_ITEM'). The second way is to use the apex.items module for example apex.items.P1_ITEM

Element Property

this property returns the JQuery object for the selected element, so it is equivalent to the JQuery selector using id $('#id'). 

In our demo app add the following items in the static region: 

• Text Field item: name=P1_ITEM0
• Display only item: name:P1_ITEM0_VAL
• button: name:Get

add a dynamic action to the button which fire on button click and a true action which execute a javascript code and write the following code:

apex.items.P1_ITEM0_VAL.value=apex.items.P1_ITEM0.element[0].outerHTML

you should have something like this:

run the application, press the button and you should get the JQuery object of the text field element (which is P1_ITEM0) displayed in the display only element (P1_ITEM0_VAL).

In the Code you can see that we used one of the JQuery property to get the DOM element as text of the selected element, you use the node property which is provided by the item interface to get the DOM element directly e.g apex.items.P1_ITEM0.node

Value Property

in the previous example we used this property to set the value of the display only item, you can use the value property to get and set the page items value. In a future posts we will see that you can set/get items values using methods provided by the interface, however using the property is a shorthand of those methods.

for getting an item value, you can simply write:

apex.items.P1_ITEM1.value

or you can use

apex.item('P1_ITEM1').value

In the static region add the following items and dynamic action:

• Text field item: name=P1_ITEM1
• Display only item: name=P1_ITEM1_VAL
• Dynamic action: event=Key Release, selection type=item, items=P1_ITEM1. add a true action that execute the following javascript code: apex.items.P1_ITEM1_VAL.setValue(apex.items.P1_ITEM1.value)

at the end you should have something like:

Now run the application and try to write something in the text field, you should see directly that what you are writing is being displayed on the other item (the display only item)

item_type property

this will give you back the item type, e.g date, number, text, etc. So if you want to know the type of your page item, you only have to write this line of code and you are done:

apex.item('P1_ITEM2').item_type

in the static region add the following page items and dynamic actions:

• Date page item: name= P1_ITEM2
• Display only page item: name=P1_ITEM2_VAL
• dynamic action that fires on page load, and has a true action of type set value, type is javascript and write the following: apex.item('P1_ITEM2').item_type. make sure that the true action will fire on page initialization.

run the application and notice the result. 

in this post we have discussed the properties that are provided by the item interface and we gave some basic examples on how to use each of these props. In the next post we will discuss the most useful methods provided by the same interface, so stick around ;).

Demo

References:

• https://docs.oracle.com/en/database/oracle/application-express/21.2/aexjs/item.html#item_type