Building an Oracle APEX Plugin: A Deep Dive, part 3

Now we need to move on to the JavaScript portion, which forms the core of our proposal: replacing the item’s default validation with a fully customized solution tailored to our specific requirements. This step is crucial, as it allows us to override Oracle APEX’s standard validation behavior and implement logic that aligns with the unique needs of our application. For more details on these foundational elements, refer to our earlier discussions linked.

Let’s dive into how this new JavaScript-based validation can be structured and implemented, we start by recalling this part of the SQL code, where we call the JavaScript initialization for our plugin:

Copy to Clipboard

This snippet is crucial as it ensures that the custom JavaScript logic is properly executed once the page has finished loading. Here’s what happens in detail:

apex_javascript.add_onload_code:
- This procedure allows us to inject JavaScript code that will run after the page is fully loaded. It is ideal for initializing plugin-specific client-side functionality.
Function Call (textCustomValidation._initialize):
- The _initialize function is part of the JavaScript logic for our plugin. This serves as the entry point for any custom behavior.
- The function is invoked with two parameters:
  - attr_short_text: A custom attribute passed to the JavaScript function, which might define additional configurations or validation criteria.
  - l_item_name: The unique identifier for the plugin’s HTML element, allowing the JavaScript to interact directly with the DOM element.

The key file for our plugin is ns.plugin.tcv.js, which handles all client-side functionality. This file replaces or extends Oracle APEX’s default behavior, enabling custom validations, dynamic interactions, and DOM updates. Integrated through the plugin’s resources, it ensures seamless execution and maintainability, forming the backbone of the plugin’s client-side operations.

Copy to Clipboard

var textCustomValidation = {
    name: null, // Property to store the name of the item.

_initialize: function (short_text, itemName) {
        "use strict";

this._initMessages();

const self = this; // Capture the current context of textCustomValidation.

// Override Apex's getValidity method to validate the item's value.
        apex.item(itemName).getValidity = function () {
            // Initialize validity object with default values.
            var lValidity = {
                valid: true,
                empty: false,
                startsWithError: false
            };
            let value = $v(itemName); // Get the item's value.

// Check if the value is empty.
            if (!value || value.trim() === "") {
                lValidity.valid = false;
                lValidity.empty = true; // Mark as empty.
            }
            // If not empty, check if it starts with the required text.
            else if (!value.startsWith(short_text)) {
                lValidity.valid = false;
                lValidity.startsWithError = true; // Mark as a prefix error.
            }

return lValidity; // Return the validity object.
        };

// Override Apex's getValidationMessage method to provide user-friendly messages.
        apex.item(itemName).getValidationMessage = function () {
            const validity = this.getValidity(); // Reuse getValidity to get the state.

if (validity.empty) {
                return apex.lang.getMessage(self._getMessage('IS_EMPTY'));
            }
            if (validity.startsWithError) {
                return apex.lang.formatMessage(self._getMessage('IS_START_INCORRECT'), short_text);
            }
            if (!validity.valid) {
                return apex.lang.getMessage(self._getMessage('IS_INVALID'));
            }
            return ""; // Return an empty string if valid.
        };
    },

_initMessages: function () {
        // here we have the labels and messages for which the developer should be 
        // able to config translations in APEX
        apex.lang.addMessages({
            'NS.TCV.IS_EMPTY': "This item cannot be empty",
            'NS.TCV.IS_INVALID': "The value entered is not valid",
            'NS.TCV.IS_START_INCORRECT': "The value must start with the prefix '%0'."
        });
    },

_getMessage: function (key) {
        return apex.lang.getMessage('NS.TCV.' + key);
    },

// Method to get the current value of the item associated with `name`.
    value: function () {
        return $v(this.name); // Return the value using Apex.
    }
};

The _initialize method is the starting point for setting up custom validation logic for an Oracle APEX item. This method integrates directly with APEX’s item object and overrides its default validation methods to apply tailored rules. Here’s how it works:

Code Overview

Custom Validation Setup

Copy to Clipboard

The getValidity method is overridden to check:
- Empty Values: If the value is missing (value.trim() === ""), the validity.empty flag is set to class="code cc-1tbex3z" data-renderer-mark="true">true.
- Prefix Validation: If the value does not start with short_text, the validity.startsWithError flag is set to true.
The validity object summarizes the state:

Copy to Clipboard

Custom Error Messages

Copy to Clipboard

This method builds user-friendly messages based on the getValidity results:

If validity.empty is true, it returns a message like “This item cannot be empty.”
If validity.startsWithError is true, it returns a formatted message such as “The value must start with the prefix ‘ABC’.”

In this setup, Oracle APEX automatically calls the overridden getValidity method whenever it needs to validate an item’s state. When APEX invokes getValidationMessage, it first checks getValidity to determine if the input is valid. Based on the result, it applies the appropriate error message—whether the input is empty, has an incorrect prefix, or is otherwise invalid.

Customizing these methods unlocks the full potential of APEX’s validation system. Developers can implement advanced validation logic, integrate external data sources, and apply dynamic rule updates. This approach ensures a seamless, user-friendly experience while extending APEX’s default capabilities. By overriding and enhancing built-in validation behavior, we create powerful workflows tailored to specific business needs.

With this level of flexibility, APEX validations go beyond static rules, offering real-time feedback and contextual checks. This customization empowers developers to build scalable and intelligent validation systems, improving both accuracy and usability.

For more information, please visit our company website, explore the plugin on APEX World, or check out the source code and documentation on our GitHub repository. Stay updated and feel free to reach out for support or contributions!