instant-validation-plugin

• Introduction
• Plug-in Features
• Supported Validations
• Client Side vs Server Side Validation
• Installation
• Plug-in Usage
• Plug-in Settings
• Plug-in Browser Events
• Implementing Custom Error Rendering
• Globalization & Multi-language Support

Introduction

Validate Oracle APEX page items instantly using this dynamic action plug-in. Bind the plug-in for example on an "onChange" event of a page item and immediately get a feedback if the user input for this page item is valid.

APEX validates page items in a submit process. If the page setting for "Reload on Submit" is set to "Only for Success" an AJAX call is performed prior to the acutal page submit. All validations for all page items are executed. In case of validation errors the error messages will be shown and the page is not submitted. With the standard APEX behavoir for validations there is no way to perform validations for individual page items and for events other then submit. This plug-in aims to close the gap. Bind it on any event for a page item and let the validations associated with this page item be executed whenever the event is triggered. In case of errors the item will be highlighted with an error message in the item's error placeholder (standard APEX error rendering) or a custom error handling can be implemented that is triggered whenever the plug-in fires the events instant-validation-failure or instant-validation-success.

Plug-in Features

• Validate individual page items on request
• Bind execution of validation to any browser event
• Supports both client side (HTML5) and server side (PL/SQL) validation
• Supports custom error rendering
• Triggers browser events instant-validation-start, instant-validation-failure and instant-validation-success
• Short-circuit evaluation of validations (first validation error is returned to client)

Supported Validations

The plug-in supports the following validations:

Validation Code	Validation Name
EXISTS	Rows returned
NOT_EXISTS	No Rows returned
EXPRESSION	Expression
ITEM_REQUIRED1)	Value Required
NATIVE_NUMBER_FIELD2)	Number field with optional min and max settings
FUNC_BODY_RETURNING_BOOLEAN	Function Body (returning Boolean)
FUNC_BODY_RETURNING_ERR_TEXT3)	Function Body (returning Error Text)
ITEM_NOT_NULL	Item is NOT NULL
ITEM_NOT_NULL_OR_ZERO	Item is NOT NULL or zero
ITEM_IS_NOT_ZERO	Item is NOT zero
ITEM_CONTAINS_NO_SPACES	Item contains no spaces
ITEM_IS_ALPHANUMERIC	Item is alphanumeric
ITEM_IS_NUMERIC	Item is numeric
ITEM_IS_DATE4)	Item is a valid date
ITEM_IN_VALIDATION_EQ_STRING2	Item = Value
ITEM_IN_VALIDATION_NOT_EQ_STRING2	Item != Value
ITEM_IN_VALIDATION_IN_STRING2	Item is contained in Value
ITEM_IN_VALIDATION_NOT_IN_STRING2	Item is NOT contained in Value
ITEM_IN_VALIDATION_CONTAINS_ONLY_CHAR_IN_STRING2	Item contains only characters specified in Value
ITEM_IN_VALIDATION_CONTAINS_AT_LEAST_ONE_CHAR_IN_STRING2	Item contain at least one of the characters in Value
ITEM_IN_VALIDATION_CONTAINS_NO_CHAR_IN_STRING2	Item does NOT contain any of the characters in Value
REGULAR_EXPRESSION	Item matches Regular Expression

Notes:

¹⁾ - Supports HTML5 client side validation.

²⁾ - MIN and MAX values (if provided) support HTML5 client side validation.

³⁾ - The error text returned by the PL/SQL function body is returned by the plug-in in JSON object (validationResult.message) and if error rendering is turned on for the plug-in will be shown as error message.

⁴⁾ - The date validity is checked with the "Application Date Format" (see Shared Components > Application Definition Attributes > Globalization) or if nothing specified with the NLS_DATE_FORMAT parameter of the database session.

Client Side vs Server Side Validation

Some validations in APEX are implemented as HTML5 constraint validations. A typical example is the Value Required flag you can set for a page item in the APEX builder:

For the HTML input element APEX sets the required attribute:

From a user perspective HTML5 constraint validations brings performance improvements since no server round trip is required to detect an input violation. However, for security reasons it is not recommended to rely on client side validations. An attacker could easly bypass client side validation e.g. by removing the required attribute in the HTML document.

APEX provides security features to both benefit from client side validation and prevent manipulation or bypassing of validation rules. Each client side validation is executed on the server side as well. For the Value Required example a column Is Required exists which can be queried via apex_application_page_items view. The plug-in ensures that client side validations are also executed on the server side!

Installation

Download the plug-in import file dynamic_action_plug-in_org_christianhesse_instant_validation.sql. Go to Shared Components > Plug-ins and choose Import. Select the file and follow the instructions in the wizzard.

Plug-in Usage

1. Define a validation for a page item: In this example restrict the input for P31_LAST_NAME to alphabetic characters.

   

2. Create a Dynamic Action and bind it to the item's Change or Lose Focus event.

   

3. Define a TRUE Action and choose Instant Item Validation [Plug-in] from the available Actions.

   

4. Save and run the page to test the plug-in.

   

Plug-in Settings

The plug-in defines the following settings:

Items to Submit:	Select or enter a list of comma separated page items to be submitted. The triggering page item gets always submitted (default). If a validation expression or the validation condition for the triggering page item depends on other page item(s) enter the page item name(s) here.
Show Validation Progress Indicator:	If true, a 'Wait Indicator' spinner is displayed next to the triggering page item. Depending on the duration of the AJAX call the spinner may not show up (for low duration AJAX calls). If false no spinner will be displayed.
Render Error:	If true, a validation error will be displayed according to standard APEX validation error rendering. If false, no error rendering will be displayed. Use false if you want to implement custom error rendering using the JavaScript plugin events instant-validation-success and instant-validation-failure. You can bind a Dynamic Action to each plugin event to excecute custom JavaScript code for validation error rendering. See here for more details.

Plug-in Events

The plug-in triggers the following browser events:

Event Name in APEX Builder	Browser Event	Description
Instant Validation Start	instant-validation-start	Triggered when plug-in starts validation. Useful to check if validation is in progress (for longer running validations).
Instant Validation Success	instant-validation-success	Triggered when all validations associated with the triggering page item pass. Indicates that the plug-in has finished execution.
Instant Validation Failure	instant-validation-failure	Triggered when one validation associated with the triggering page item fails. The event is triggered after the first failed validation (short circuit evaluation). Indicates that the plug-in has finished execution.
Instant Validation Error	instant-validation-error	Triggered in case there is an error during the AJAX call. Indicates that the plug-in has finished execution.

All events can be selected as Component Events for Dynamic Actions.

Implementing Custom Error Rendering

In the following example a custom error rendering routine is created to change the background-color of a page item with failed validation to red.

1. Create a new Dynamic Action and name it "Render Custom Validation Error".

   

   Select Instant Validation Failure [Instant Item Validation] as Event.

   To implement a page wide error rendering routine choose JavaScript Expression as Selection Type and enter document as expression. In case you want to create an error rendering indiviual for a page item select Item(s) as Selection Type and choose the item.

   

   Create a TRUE Action Execute JavaScript Code and provide the following code:

   let validationResult = this.data.validationResult;
   apex.debug("Error rendering");
   $('#' + validationResult.item).addClass('hasError');
   $('#' + validationResult.item + '_error_placeholder').text(validationResult.message);
       

   In case of validation errors the plug-in triggers the instant-validation-failure event and returns a JSON object with the following structure:

   {
       "validationResult":{
           "item":"P31_LAST_NAME"
          ,"validationType":"ITEM_REQUIRED"
          ,"passed":false
         ,"message":"Last Name must have some value"
       }
   }
       

   To access the returned JSON object from the Dynamic Action use this.data.validationResult. The triggering item id can be determined with this.data.validationResult.item and the error message with this.data.validationResult.message

   In the example above a CSS class hasError is set for the triggering item and the error message is shown in the items default error message placeholder.

   Add following inline CSS code for the page:

   .hasError {
       background-color: #eea29a;
   }
       

2. Create a another Dynamic Action and name it "Clear Custom Validation Error".

   Select Instant Validation Success [Instant Item Validation] as Event and use the same Selection Type as entered in Step 1.

   Create a TRUE Action Execute JavaScript Code and provide the following code to clear the error (if present):

   let validationResult = this.data.validationResult;
   apex.debug("Error Clearing");
   $('#' + validationResult.item).removeClass('hasError');
   $('#' + validationResult.item + '_error_placeholder').text('');
       

3. Save and run the page to test the plug-in.

   

Globalization & Multi-language Support

In order to use the plug-in in a multi-language application in APEX it is mandatory to define translateable text messages via Shared Components > Globalization > Text Messages.

Define for each validation a text message in all languages that your app supports. In the example below a text message ITEM_IS_MULTIPLE_OF_10 was created for English (en) and German (de) language.

Don't forget to switch on the "Used in JavaScript" Option

For the validation error message choose a text message by using the following APEX syntax: &APP_TEXT$<TEXT_MESSAGE_NAME>.
An excellent blog post about text messages was written by Philipp Hartenfeller: Reusable, and Translatable: Oracle APEX Text Messages

In our example the text message is referenced with &APP_TEXT$ITEM_IS_MULTIPLE_OF_10. and don't forget the trailing dot (".")

Also be aware that client side validations use Oracle internal text messages that need to be translated to any language of your app other than English (en). A list of text messages that require translation are always part of the APEX documention, e.g. for 23.2 you can find it here. Just search for "Internal Messages Requiring Translation" in the APEX documention of your APEX version. For example if you use the "Value Required" feature of a page item in the APEX builder a client side validation is done prior to the server side validation. In this case it is mandatory to translate the corresponding Oracle internal text message (APEX.PAGE_ITEM_IS_REQUIRED) to all languages of your application. To find the corresponding text message look up the documentation as mentioned above. Don't forget to switch on the "Used in JavaScript" option when defining the text message (as shown above).

If you modify your application don't forget to re-seed and re-publish you application in all supported languages!

Here is a demo of the plug-in using validation error messages in multiple languages.