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

Sending emails with the "APEX_MAIL" API (APEX Mail #2)

As mentioned in the previous blog, we want to share everything about sending emails with Oracle APEX. So continue with the second topic.

#2 Sending emails with the "APEX_MAIL" API

If you have an APEX version older than 21.2 in your environment, email templates can only be sent with a few lines of PL/SQL code. But it is still not difficult and we will explain how to do it step by step.

Let´s start by creating (or modifying) a demo app

To avoid having to create a new application again, let's take the demo app from the previous blog post or follow all steps up to "Create a process to send the email".

Then we need a new (or second) button to send an email by using the API. So add a button "Text and Icon (Hot)" to the "Close" position. Name the button "Send_API" and use e.g. "fa-send-o" as the icon and "Send email with API" as the label.

What we now have is an application with a form to send an email based on an email template. 

If you start the application now, it should look like this.

Create a new process to send the email

Next, we need a process to send an email when we hit the "Send email with API" button.

Therefore, switch to Processes in the tree structure and create a new process. For example, name it "Send mail with API" and select the type "Execute Code". 

Under Source, enter the following PL/SQL Code:

begin

    -- This procedure adds a mail to the mail queue of Oracle APEX

    apex_mail.send(

        -- Valid email address to which the email is sent

        p_to                 => :P1_TO,

        -- Email address from which the email is sent

        p_from               => :APP_EMAIL,

        -- Static identifier string, used to identify the shared component email template

        p_template_static_id => :P1_EMAIL_TEMPLATE,

        -- JSON string representing the placeholder names along with the values, to be substituted

        p_placeholders       => '{' ||

        '    "CONTACT":'     || apex_json.stringify( :P1_CONTACT ) ||

        '}'

    );    

    -- Oracle APEx stores unsent email messages in a table named APEX_MAIL_QUEUE.

    -- You can manually deliver mail messages stored in this queue to the

    -- specified SMTP gateway by invoking the APEX_MAIL.PUSH_QUEUE procedure.

    apex_mail.push_queue;

end;

Note: If you have a deeper look into your email template, you can see an example of using the API at the bottom. This can be very helpful with more complex templates ;-)

Finally, enter the success and error message and the server-side condition when the process should be executed.

Success Message: Email sent

Error Message: Email sent failed!

When Button Pressed: SEND_API

Let's try to send an email by clicking on the "Send email with API" button.

And again, this is how the result of the email should look like.

So, that's it...here is the link for the demo app.

Quellen:

• https://bit.ly/3CSrTQR

Sending emails with "E-Mail Templates" (APEX Mail #1)

In this series we want to list step by step everything you need to know about sending emails with Oracle APEX. 

Let's start with the first issue :-)

#1 Sending emails with "E-Mail Templates"

Since APEX version 21.2 it is easier than ever to send emails with templates. Everything can now be configured declaratively in the APEX Builder. In the previous versions you had to use the "APEX_MAIL" API which will be discussed in the next blog post.

Let´s start by creating a demo app

Create a new application in the App Builder. In the wizard you can name your application "Email Demo" for example. Our application is now ready to add more components. The home page has no regions at the moment.

Create an email template

Let´s create an email template first. To do this, go to "E-Mail Templates" under "Other Components" of the Shared Components section.

For our newly created template, we enter the following information:

Template Name: Hello World

Static Identifier (will be generated automatically): HELLO_WORLD

Email Subject: Hello World

Then we can populate the HTML snippets for our template. We will use substitution strings such as #CONTACT# to pass the values to the template from our application.

Header:

<H1>Hello World!</H1>

Body:

<p>Hello #CONTACT#,</p>

<p>this is an email sent from <strong>Oracle APEX</strong>.</p>

<p>Best Regards</p>

Plain Text Format:

Hello #CONTACT#,

this is an email sent from Oracle APEX.

Best Regards

By clicking on "Apply changes" we have created the template and can now use it in our application.

Create a "List of Values" to list all available email templates

Next, we need a "List of Values" that lists all available email templates. To do this, go to "List of Values" under "Other Components" of the "Shared Components" section and create a new LOV from scratch. For example, name it "EMAIL TEMPLATES" and set the type to "Dynamic". Then select the source type "SQL Query" and enter the following SQL statement.

select name as display,

       static_id as return

  from APEX_APPL_EMAIL_TEMPLATES

"APEX_APPL_EMAIL_TEMPLATES" is a predefined view from which all email templates can be selected. So with the LOV, we can now create a "Select List" of all available email templates.

Create the Home-Page

Now our application is ready to add a region, some components and a process to send emails.

First, add a "Static Content" region to your "Content Body" and name it for example "Send Email".

Then we need to have the following items:

• P1_TO as Text Field (This will have the address of the email recipient)
• P1_CONTACT as Text Field (This will have the name of the recipient)
• P1_EMAIL_TEMPLATE as Select List (This contains the email template that we will send)

For the "Select List", go to the attribute "List of Values" and set the type to "Shared Component". Then select the previously created LOV "EMAIL TEMPLATE" under "List of values".

Finally, the page needs a button to send an email. So add a button "Text and Icon (Hot)" to the "Close" position. Name the button "Send" and use e.g. "fa-send" as the icon and "Send email" as the label.

When you start the application now, it should look like this.

Create a process to send the email

Next, we need a process to send an email when we hit the "Send Email" button.

Therefore, switch to Processes in the tree structure and create a new process. For example, name it "Send mail" and select the type "Send E-Mail". 

Under Settings, enter the following:

From: &APP_EMAIL.

To: &P1_TO.

Email Template: Hello World

Placeholder Values: Placeholder -> Contact / Value -> &P1_CONTACT.

Send immediately: true

Success Message: Email sent

Error Message: Email sent failed!

When Button Pressed: SEND

Note! If you set "Send immediately" to true, APEX will send all emails directly. Otherwise, APEX stores unsent emails in a table and periodically delivers them for better system performance.

Let's try to send an email by clicking on the "Email send" button.

And this is how the result of the email should look like.

So, that's it...here is the link for the demo app.

As announced at the beginning, in the next blog post we will describe how to send email templates in previous APEX versions using the "APEX_MAIL" API.

Quellen:

• https://bit.ly/3HKxVqt