JS Manipulations for APEX regions (Interactive Grid)

Introduction

Oracle APEX provides built-in dynamic actions that allow developers to perform basic interactions without writing custom JavaScript. These actions can be triggered by events such as clicking a button, changing the value of a field, or selecting an option from a dropdown. While these built-in features cover many everyday use cases, more complex interactions often require advanced JavaScript (or jQuery) to enhance functionality and provide a richer user experience.

This blog post will explore advanced JavaScript techniques for working with APEX regions, focusing on Interactive Grids. These components are powerful but sometimes require additional customization to meet specific requirements. By leveraging JavaScript, we can handle dynamic actions with jQuery Selectors and enhance Interactive Grids with custom validations, event handling, and dynamic modifications.

Let’s dive into how JavaScript can take APEX regions to the next level!

Basic JavaScript

Before beginning with Interactive Grids, let’s start with basic examples.

Accessing Page Items

For instance, we can use JavaScript to read or set the value of APEX page items. The functions $v() and $s() are commonly used:

• Get the value of a page item:

• Set the value of a page item:

Triggering Notifications

APEX provides built-in notifications using the apex.message namespace, which handles client-side display and management of messages.

• Success Notification:

• Error Notification:

Advanced JavaScript

As I said before, in the Introduction, we can handle dynamic actions with jQuery Selectors and enhance Interactive Grids with custom validations, event handling, and dynamic modifications.

In Oracle APEX, Dynamic Actions allows developers to create event-driven behaviour without writing complex code. One powerful way to trigger these actions is by using jQuery selectors. These selectors allow you to target specific elements within the DOM of your APEX page. You can handle a wide range of user interactions by combining dynamic actions with jQuery selectors.

A jQuery selector is essentially a way to find or select HTML elements based on their properties (like ID, class, tag, etc.) and then apply actions to them. This enables developers to interact with different components on the page in a flexible way.

Some types of jQuery Selectors in Oracle APEX

1. ID Selector (#)

• It selects a single element with a specific ID.

  Copy to Clipboard
  Syntax Highlighter$("#P1_EMPLOYEE_NAME").on("focus", function() { 
    apex.message.alert("Employee name input got focus!"); 
  });

2. Class Selector (.)

• It selects all elements with a specific class.

  Copy to Clipboard
  Syntax Highlighter$(".employee-field").hover(function() { 
    $(this).css("background-color", "yellow"); 
  }, function() { 
      $(this).css("background-color", ""); 
  });

3. Element Selector (Tag Selector).

• Selects all elements of a specific HTML tag.

  Copy to Clipboard
  Syntax Highlighter$("input").on("focus", function() { 
    $(this).css("border", "2px solid red"); 
  });

4. Attribute Selector

• It selects elements based on the value of an attribute.

  Copy to Clipboard
  Syntax Highlighter$("input[type='text']").css("background-color", "#e0e0e0");

5. Descendant Selector

• It selects elements that are descendants of a specific parent element.

  Copy to Clipboard
  Syntax Highlighter$("#myRegion .child-item").css("color", "blue");

6. Pseudo Classes

• Select elements based on their state (e.g., checked, disabled, etc.).

  Copy to Clipboard
  Syntax Highlighter$("input:checked").each(function() { 
    apex.message.alert("Checkbox is checked!"); 
  });

7. Oracle APEX Specific selectors

In addition to the general jQuery selectors, Oracle APEX provides specific classes and IDs for interacting with its components:

• Regions:

  Copy to Clipboard
  Syntax Highlighter$(".t-Region").hide(); // Hide all the regions from a page

• Page Items:

  Copy to Clipboard
  Syntax Highlighter$(".apex-item-text").val(); // Selects all the text items from a page

• APEX Buttons:

  Copy to Clipboard
  Syntax Highlighter$(".t-Button").click(); // It simulates the click event over all the page buttons.

• Interactive Grid:

  Copy to Clipboard
  Syntax Highlighter// Get all the selected rows from an Interactive Grid 
  $("#myGrid").interactiveGrid("getSelectedRecords");

Common JavaScript manipulations for IG in APEX

The Interactive Grid API in Oracle APEX allows developers to manipulate and customize interactive grids directly through JavaScript. This API enables dynamic operations such as adding, editing, or deleting rows, changing display settings in real-time, applying custom filters, and responding to specific user events. It facilitates the creation of richer user experiences aligned with business logic, optimizing data management and interaction in enterprise applications.”

This API extends the capabilities of interactive grids, providing detailed control over data and the interface in real-time.

• Accessing the Interactive Grid API: You can access the Interactive Grid object using apex.region() and the region’s static ID.

  Copy to Clipboard
  Syntax Highlightervar ig$ = apex.region("my_interactive_grid").widget();

• Getting the Current View Mode (Grid, Chart, etc.): Interactive Grids can have different views (Grid, Icon, Chart). You can get the current view type using:

  Copy to Clipboard
  Syntax Highlightervar viewMode = ig$.interactiveGrid("getViews", "grid"); 
  console.log(viewMode);

• Refreshing the Interactive Grid: To refresh the data in the Interactive Grid, for example, after an update:

  Copy to Clipboard
  Syntax Highlighterig$.interactiveGrid("refresh");

• Selecting Rows Programmatically: You can choose programmatically rows in the grid using the following code:

  Copy to Clipboard
  Syntax Highlightervar model = ig$.interactiveGrid("getViews", "grid").model; 
  model.selectRow(0); // Select the first row

• Accessing the Selected Rows: You can access data from selected rows in the Interactive Grid like this:

  Copy to Clipboard
  Syntax Highlightervar selectedRecords = ig$.interactiveGrid("getSelectedRecords"); 
  console.log(selectedRecords); // Outputs an array of selected records

• Updating Data Programmatically: To update data programmatically in a specific cell:

  Copy to Clipboard
  Syntax Highlightervar model = ig$.interactiveGrid("getViews", "grid").model; 
  var record = model.getRecord(0); // Access the first row 
  model.setValue(record, "COLUMN_NAME", "New Value"); // Update a column's value

• Adding a New Row: You can add a new row to the grid with the following code:

  Copy to Clipboard
  Syntax Highlightervar model = ig$.interactiveGrid("getViews", "grid").model; 
  model.insertNewRecord();

• Deleting a Row: You can delete a row programmatically by:

  Copy to Clipboard
  Syntax Highlightervar model = ig$.interactiveGrid("getViews", "grid").model; 
  var record = model.getRecord(0); // Get the first record 
  model.deleteRecord(record);

• Save Data Programmatically: After making changes, you may want to save the data programmatically:

  Copy to Clipboard
  Syntax Highlighterig$.interactiveGrid("save");

• Customizing the Toolbar: You can manipulate the toolbar of the Interactive Grid using toolbarData. Here is an example of how you might modify the toolbar to add a button:

Interactive Grid Region – Initialization JavaScript Function

Copy to Clipboard
Syntax Highlighterfunction( options ) { 
  var $ = apex.jQuery, 
  toolbarData = $.apex.interactiveGrid.copyDefaultToolbar(), // Make a copy of the default toolbar 
  reportsGroupControls = toolbarData.toolbarFind( "reports" ).controls; // Locate the reports group 
  
  // Add a new button after the default report controls. Note the toolbar is action driven, so 
  // we just need to define the correct action name with the button. 
  reportsGroupControls.push({ 
    type: "BUTTON", 
    action: "save-report", 
    iconOnly: true 
  }); 
  
  // Assign new toolbar data back to toolbarData configuration property 
  options.toolbarData = toolbarData;
  
  // Return the options 
  return options; 
}

This way, we Initialize the interactiveGrid with the toolbar data option specified in the Interactive Grid region Initialization JavaScript Function attribute.

• Customizing action columns per row: You can add virtual columns to a grid to create actions involving the specified row.

In the following example, we create a new virtual column in our grid to set a button with different actions depending on the value of another column:

Custom ACTION column

Custom ACTION column visualization

Depending on the STATUS_CD column value, the button created will execute different actions:

Copy to Clipboard
Syntax Highlighter{case STATUS_CD/} 
	{when ASSIGNED/} 
		<button id="bToProgressId_&ID." type="button" metadata-id=&ID. onclick="inProgressClick(this)" style="border:none;background-color:transparent;" class="a-Button a-Button--noLabel a-Button--iconTextButton js-actionButton" metadata-id=&ID. title="In progress">
			<span class="fa fa-play" aria-hidden="true" style="color:blue;"/>
		</button> 
	{when IN-PROGRESS/} 
		<button id="bToCompleteId_&ID." type="button" metadata-id=&ID. onclick="completeClick(this)" style="border:none;background-color:transparent;" class="a-Button a-Button--noLabel a-Button--iconTextButton js-actionButton" metadata-id=&ID. title="To complete">
			<span class="fa fa-flag-checkered" aria-hidden="true" style="color:green;"/>
		</button> 
{endcase/}

The actions specified on the “onclick” event, will be declared on the “Function and Global Variable Declaration” section of the Page:

Copy to Clipboard
Syntax Highlighterfunction inProgressClick(element) { 
  var widget = apex.region('mis_proyectos').widget(); 
  var grid = widget.interactiveGrid('getViews', 'grid'); 
  var model = grid.model; 
  
  // Get the ID value of the row (Our primary key) 
  const id = element.getAttribute('metadata-id'); 
  
  // We read the record belonging to the ID 
  const record = model.getRecord(id); 
  
  // In this example, we check that the value of the column STATUS_CD is "Assigned" 
  const isAssigned = model.getValue(record, "STATUS_CD").d === 'Assigned'; 
  
  // If it's true... 
  if (isAssigned) { 
    model.setValue(record, "STATUS_CD", { "d": "In-Progress", "v": "IN-PROGRESS" }); 
  } 
  
  // We save the report by calling the default "Save" button of the IG 
  $('[data-action="save"]').click(); 
} 

function completeClick(element) { 
  // .... 
}

Conclusion

Customizing Oracle APEX regions with JavaScript, especially Interactive Grids, unlocks a world of possibilities for enhancing user experience and optimizing data management. While APEX provides a powerful set of declarative tools, integrating advanced JavaScript and jQuery techniques allows for more precise control over events, validations, and dynamic modifications.

By mastering these concepts, developers can create more intuitive, dynamic, and tailored applications without compromising performance or scalability. The key is to strike a balance between leveraging APEX’s native functionalities and implementing custom code, ensuring an efficient and maintainable solution.