Oracle APEX Part 13 - JavaScript APIs in Oracle APEX

 Core JavaScript APIs for APEX

The Oracle APEX framework provides simple, powerful APIs for interacting with page items: 

• apex.item("ITEM_NAME").getValue(): Gets the value of a page item. Can also be written as $v("ITEM_NAME").
• apex.item("ITEM_NAME").setValue(value): Sets the value of a page item. Can also be written as $s("ITEM_NAME", value).
• apex.server.process("AJAX_PROCESS_NAME", ...): Calls an "Ajax Callback" (server-side PL/SQL or JavaScript) process defined in your application.
• apex.navigation.dialog(url, ...): Opens a modal or non-modal dialog page.
• apex.debug.info(...): Writes messages to the browser console when debug mode is enabled, useful for testing and debugging. 

Usage Examples

Here are common usage examples demonstrating how to incorporate JavaScript into an APEX application:

1. Getting and Setting Page Item Values

This is typically used in a Dynamic Action to perform client-side calculations or updates. 

Scenario: Calculate a total price based on quantity and unit price fields (P1_QTY and P1_UNIT_PRICE), and display the result in a P1_TOTAL field.

• Location: Create a Dynamic Action on the "Change" event of P1_QTY and P1_UNIT_PRICE. The action should be "Execute JavaScript Code".
• Code:

• // Explicitly convert values to floating point numbers for calculations
  var quantity = parseFloat(apex.item("P1_QTY").getValue()) || 0;
  var unitPrice = parseFloat(apex.item("P1_UNIT_PRICE").getValue()) || 0;
  
  var total = quantity * unitPrice;
  
  // Set the value of the P1_TOTAL item
  apex.item("P1_TOTAL").setValue(total);

2. Calling a Server-Side Process (Ajax Callback)

You can use JavaScript to call a PL/SQL procedure without submitting the entire page. 

Scenario: Validate a username (P1_USERNAME) against a database table when the user leaves the input field. 

• Server-Side (Ajax Callback Process):
• Name: VALIDATE_USERNAME
• PL/SQL Code:
• DECLARE
•     l_count NUMBER;

• BEGIN
      SELECT COUNT(*)
      INTO l_count
      FROM users
      WHERE username = apex_application.g_x01; -- g_x01 holds the first parameter from JS
  
      IF l_count > 0 THEN
          apex_application.g_print_success := 'EXISTS';
      ELSE
          apex_application.g_print_success := 'AVAILABLE';
      END IF;
  END;

• Client-Side (Dynamic Action - Execute JavaScript Code):
  • Event: "Change" on P1_USERNAME
  • Code:

  • var username = apex.item("P1_USERNAME").getValue();
    
    apex.server.process(
        "VALIDATE_USERNAME", // Name of the Ajax Callback Process
        {
            x01: username     // Pass the item value as the first parameter
        },
        {
            success: function(response) {
                if (response === "EXISTS") {
                    alert("Username already exists!");
                } else {
                    // Update a status field or perform other actions
                    apex.item("P1_STATUS").setValue("Username available");
                }
            },
            error: function(jqXHR, textStatus, errorThrown) {
                console.error(errorThrown);
            }
        }
    );

     

3. Executing Code When the Page Loads

Code can be executed automatically when a page finishes loading. 

Scenario: Display a welcome alert when the page loads. 

• Location: Page Designer -> Page attributes -> JavaScript -> "Execute when Page Loads".
• Code
• alert("Welcome, " + apex.item("P1_USER_GREETING").getValue());