Javascript APIs (#3 the date namespace)

Hello everyone and welcome back to a new blog, this blog is one of the blog series about the Javascript APIs that we have started. In this blog, we will talk about the date namespace so let's get started :). 

The apex.date namespace contains the oracle APEX functions related to date operations, so this API has functions that will help you work with the date items and values. It makes working with different dates format much easier than using normal Javascript. 

Before we start, go to our demo app, navigate to the first page and add a new static region. Now we can start...

date.parse()

this function returns parsed date object of a given date string and a format mask, it accepts a date in a string format and converts it into a date object so you can use all methods available on a date object. The function uses the default date format mask defined in the application globalization settings. 

Go to the demo app and add the following in the new static region

• Date page item: name= P1_DATE1
• Display only page item: name=P1_DATE1_VAL
• Dynamic action that fires when P1_DATE1 changes: add a new true action that run the following Javascript code:

                                            let date_val = apex.item('P1_DATE1').getValue();

                                            let parsed_date = apex.date.parse(date_val);

                                            apex.items.P1_DATE1_VAL.value=parsed_date.toString();

you should have something like 

in the code above, we converted the value of the date object into a string to show it in the display-only item. the parse() function accepts a second parameter to specify the format, if the parameter is not given, the function uses the default format and language defined in the application globalization settings. To check your application setting, you can go to shared components and see globalization, or open the developer tool in your browser and write the following javascript code:

apex.local.getDateFormat();

apex.local.getLanguage();

you can also try using a different format, type the following in you console

apex.date.parse('2021.12.02 11:20','YYYY.MM.DD HH24:MI')

date.add() 

This function is used to add a certain amount of time to an existing date object, it also returns a date object. the function accepts three parameters, the first is the date object you want to modify, the second is the amount you want to add, and the third is optional which is the unit.

Go back to the Demo app and add the following:

• Date page item: name= P1_DATE2
• button: name= addDay
• dynamic action fires when addDay button click: add a true action that execute the following Javascript code

let strDate = apex.items.P1_DATE2.value;

let dateVal = apex.date.parse(strDate);

let newDate = apex.date.add(dateVal, 1, apex.date.UNIT.DAY);

apex.items.P1_DATE2.value = newDate.toString();

in the same way, you can add a Month, year, or any amount of time. Just change the unit. You can also subtract a specific amount of date from a date object using subtract()

date.format()

you can use this function to change the default date format, meaning if you want to use a specific date format other than the default one. but keep in mind that you can only use oracle compatible format masks. by giving an extra parameter you can also specify the language you want.

Add the following items in the demo app

• Date page item: name= P1_FORMAT
• Display only page item: name=P1_FORMAT_VAL
• Button: name=format
• Dynamic action fires when the format button is clicked, add a true action which runs the following Javascript code:

let strDate = apex.items.P1_FOMRAT.value;

let selectedDate = apex.date.parse(strDate);

let formattedDate = apex.date.format(selectedDate, 'yyyy.Month.dd', 'de');

apex.items.P1_FORMAT_VAL.value = formatted date;

date.firstOfMonth()

this function is very useful, it returns a date object for the first day a month of a given date object. You have a date object and you want to get the first day in the month of your date, just use this function.

Add the follwoing in the demo app

• Date page item: name=P1_DATE3
• Display only page item: name= P1_FIRST_DAY
• Button: name= getFirstDay
• Dynamic action fires when getFirstDay button click: add a new true action which runs the following Javascript code

let strDate = apex.items.P1_DATE3.value;

let selectedDate = apex.date.parse(strDate);

let firstDay = apex.date.firstOfMonth(selectedDate);

apex.items.P1_FIRST_DAY.value = apex.date.format(firstDay,'yyyy.mm.dd');

you should have something like this:

there is a similar function to get the last of the month, just use lastOfMonth() instead of firstOfMonth()

isAfter()

this function is used to compare two date objects, it returns true if the first date object is after the second date object, otherwise, it returns false.

Add the following items to the demo app

• 2x Date page item: name= P1_FIRST_DATE, P1_SECOND_DATE
• Display only page item: name= P1_RESULT
• Button: name=compare
• Dynamic action fires when compare button is clicked: add a true action that runs the following Javascript code

let strFirstDate = apex.items.P1_FIRST_DATE.value;

let strSecondDate = apex.items.P1_SECOND_DATE.value;

let firstDate = apex.date.parse(strFirstDate);

let secondDate = apex.date.parse(strSecondDate);

let result = apex.date.isAfter(firstDate, secondDate);

apex.items.P1_RESULT.value = result;

in the same way, you can compare is a date object is before a given date, just use isBefore()

date.isSame()

this function is used for comparing two dates, it returns true if the first date matches the second.

Go to the demo app and add the following:

• Date page item: name=P1_IS_SAME1
• Date page item: name=P1_IS_SAME2
• Display only page item: name = P1_IS_SAME_VAL
• Button (name=P1_IS_SAME) with a dynamic action which fires on the button click and runs the following Javascript code:

let strDate1 = apex.items.P1_IS_SAME1.value;

let strDate2 = apex.items.P1_IS_SAME2.value;

let date1 = apex.date.parse(strDate1);

let date2 = apex.date.parse(strDate2);

let result = apex.date.isSame(date1,date2);

apex.items.P1_IS_SAME_VAL.value = result;

date.isLeapYear()

this will be the last function for this blog. As the name suggests, this function tells you whether the given year is a leap year or not, it returns true when it is. let's try it by adding the following to the demo app

• Date page item: name= P1_LEAP
• Display only page item: name= P1_LEAP_VAL
• Button: name= P1_CHECK
• Dynamic action fires when the button is clicked, add a true action that runs the following Javascript code

let strDate = apex.items.P1_LEAP.value;

let leapDate = apex.date.parse(strDate);

let isLeap = apex.date.isLeapYear(leapDate);

apex.items.P1_LEAP_VAL.value = isLeap;

So that's it for this post, in the next post we will start with a new namespace :).

Demo

References:

• https://docs.oracle.com/en/database/oracle/application-express/21.2/aexjs/apex.date.html#.isLeapYear

Javascript APIs (#2 apex.item)

Hello everyone and welcome back to the next post where we will cover the second part of the item interface. This post is one of a series in which we will discuss the most commonly used Javascript APIs. 

In the following, we will continue by explaining the methods provided by the item interface and see how we can use them in our Demo app. 

Disable, Enable, and isDisabled methods

as the name suggests, these methods can be used to Disable or Enable one of the page items, they make it either available for editing or unavailable. Please notice, that not all items support being editable, so we can't use this method on all items. We can use them only on items that can be edited e.g text field items.

Go to the demo app we created in the last post and add the following item and dynamic actions in a new static region:

• Text field page item: name=P1_ITEM3
• Button: name=change
• Dynamic action: fires when change button is clicked, add a true action that execute the following javascript code:

if (apex.items.P1_ITEM3.isDisabled())

    apex.items.P1_ITEM3.enable();

    else

    apex.items.P1_ITEM3.disable();

as you can see in the code we first test whether the text field is already disabled if this was the case, we enable it, otherwise, we disable it. 

run the application and test it, please note that you can achieve the same by simply using the predefined dynamic action which enables/disables an item. but the idea here is to learn how to use the JS API.

getValue/setValue methods

getValue returns the current value of an item. There is a shorthand for this function which is $v() and also as we discussed in the previous post you can use the value attribute of the item. e.g 

apex.items.P1_ITEM1.value

is equivalent to

apex.item('P1_ITEM1').getValue()

and are the same as

$v('P1_ITEM1')

Now, for setting an item value we can use the shorthand $s() or the item attribute value or we can use the  following function which give us more options

apex.item('P1_ITEM1').setValue(param1,param2,param3)

this function sets the current value of the item, but the session state will not be affected until you submit the page (or you can use AJAX) .

param1: the value to set. if the item can accept more than one value, you can give those values as an array of string

param2: the display value. This parameter is optional, you have to provide it when the display value is not the same as the item value.

param3: some items have a change event, this event will run the callback function whenever the item value has been changed. You can prevent the event from firing by giving true as a value for this parameter. 

Go back to our demo and add the following:

• text field page item: name= P1_ITEM5
• display only page item: name=P1_ITEM5_VAL
• dynamic action that fires on key release: selection type=item, item=P1_ITEM5. this dynamic action has a true action which runs the following javascript: 

apex.item('P1_ITEM5_VAL').setValue(apex.item('P1_ITEM5').getValue())

run the application and test it. 

setStyle method

this method sets the style of an item, meaning you change the style of an item as you do use CSS. However, keep in mind that this method is not the best practice. It is also recommended that you add/remove the class of an item and then edit the style in your CSS code using those classes.

Go to the demo app and add the following 

• text field page item: name=P1_ITEM6
• button: name=change_color
• dynamic action that fires on change_color click: add a true action which runs the following javascript code

apex.item( "P1_ITEM6" ).setStyle( "background", "red" );

so at the end your application should look something like

so as you see there are many ways to use these cool APIs... all other methods are basically the same, you know have an idea about how to use them... so go to the JS APIs documentation and have a look and stay tuned for our coming posts :)

Demo

References

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

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