Project: Plug-ins-Plus : Client-Side Validation Pro

Created by Bartosz Ostrowski, last modified by Jackie McIlroy on Jun 15, 2020

Table of Contents

Introduction

Make your Oracle APEX validations more powerful and user friendly. Warn users about problems with their entries before they submit and perform actions when validation fails. With Client-side Validation Pro, you are able to evaluate existing validations on the client-side without defining custom JavaScript validations.

This means you don't need to duplicate or write any new code! Existing, native, APEX validations are picked up and evaluated. Enrich your end-users experience with a new, improved way of validating data and take advantage of the plug-in’s capabilities to create application flow dependent on validation results.

All you need to do is install the plug-in and decide where you want client-side validation to be enabled. Take advantage of multiple combinations of triggering elements and affected elements to meet your requirements.

Features at glance

Safe to Use

The plug-in is an overlay for existing native validations. If a page is submitted then native validation processes are executed.

No Extra Validations

The plug-in uses native APEX validation which means there is no need to rewrite or define new validations specifically for the client-side.

Flexible Configuration

The plug-in supports 17 different combinations of triggering elements and affected elements in the dynamic action.

Oracle APEX Validations

The plug-in executes native Oracle APEX validations in the client-side in the user's browser and server-side using JavaScript, AJAX, and PL/SQL.

HTML5 Validation

The plug-in is able to evaluate HTML5 validations defined on an item and column level.

Client-Side Validation

The plug-in can execute 14 validations and 25 validation conditions directly in the user's browser without submitting the page and without an AJAX call.

Interactive Grid

The plug-in can be used to validate Interactive Grid columns when a dynamic action event occurs.

Validation flow

The plug-in validates items and columns using HTML5 validation, client-side validation, and in the end server-side validation.

Callbacks

The plug-in supports validation callbacks so it is possible to build a custom flow dependent on validation results.

Translations

The plug-in supports HTML5 translations using new translation texts and native translations (shadow application).

Authorization Schemes

The plug-in evaluates associated Authorization Schemes before executing the validation.

Debounce Events

The plug-in can be used with the Key Release event for items. Debounce time can be applied through the plug-in attribute in the dynamic action.

Requirements

The table below describes the requirements that were used to define the plug-in scope. The Native APEX validation and Client-Side Validation Pro columns compare the requirement against native validation provided by Oracle APEX and the capability to fulfill the requirement by the plug-in.

Requirement

Description

Native APEX Validation

Client-Side Validation Pro

1

The plug-in should execute validations on the client-side without an AJAX call.

Usually, client-side validation is done by writing custom javascript functions to validate. The plug-in should execute native Oracle APEX validations without any extra effort from a developer.

Purpose: Execute defined APEX validations on the client-side using JavaScript without defining any JavaScript code.

(error)

Oracle APEX validations are always executed on the server-side.

(tick)

The plug-in can evaluate natively defined validations using JavaScript based on APEX validation definitions.

2

The plug-in should allow evaluating validation conditions on the client-side without an AJAX call.

Usually, client-side validation is done by writing custom javascript functions to validate. The plug-in should evaluate native Oracle APEX validation conditions without any extra effort from a developer.

Purpose: Evaluate defined APEX validations on the client-side (using JavaScript) condition before executing a validation.

(error)

Oracle APEX validations are always executed on the server-side.

(tick)

The plug-in evaluates natively defined validation conditions using JavaScript based on APEX validation definitions.

3

The plug-in should be able to execute interactive grid column validations.

Purpose: Support interactive grid column validation.

(tick)

Native feature

(tick)

The plug-in supports validating interactive grid columns.

4

The plug-in should execute all validations server-side using an AJAX call.

The end-user can turn off the JavaScript in their browser settings which is the reason that all validations that can be executed on the client-side should be rechecked on the server-side.

Purpose: Prevent end-users from disabling validation using JavaScript.

(tick)

Oracle APEX validations are always executed on the server-side.

(tick)

The plug-in always evaluates defined validations on the server-side.

5

The plug-in should be able to execute items validations on an event triggered on the specified region.

Purpose: Reduce the effort required to validate all items in the specified region. Instead of specifying item(s) specify the region.

(error)

Oracle APEX validation can be restricted to a given request (When Button Pressed) which is associated with an APEX button.

(tick)

When the plug-in affected elements are set to Region, the plug-in will validate all items embedded in the specified region.

6

The plug-in should be able to validate a given item(s).

Purpose: Give the possibility to specify which items should be validated using the plug-in.

(error)

Oracle APEX validation can be restricted to a given request (When Button Pressed) which is associated with an APEX button.

(tick)

When the plug-in affected elements are set to Item(s), the plug-in will validate all specified items in one execution.

7

The plug-in should be able to execute items validations on a custom event triggered on the document (DOM tree node)

Purpose: Give the possibility to bind the plug-in validation from global page 0.

(error)

Native Oracle APEX validation can be performed only after the page is submitted.

(tick)

The plug-in supports triggering elements defined as a JavaScript Expression.

8

The plug-in should be able to execute column validations (for currently edited row) on an event triggered by an interactive grid.

Purpose: Reduce the amount of effort required to bind the plug-in with all interactive grid columns.

(error)

Native Oracle APEX validation is done after the interactive grid save action is triggered.

(tick)

The plug-in supports triggering elements defined as Region (interactive grid).

9

The plug-in should be able to execute columns validations (for currently edited row) on an event triggered by an interactive grid column.

Purpose: Give more control to a developer as to which columns are validated under the specified conditions.

(error)

Native Oracle APEX validation is done after the interactive grid save action is triggered.

(tick)

The plug-in supports triggering elements defined as Column(s).

10

The plug-in should execute validations in a defined sequence order.

Purpose: Mimic the native validation process.

(tick)

Native Oracle APEX validation is done in order of validation sequence.

(tick)

The plug-in executes validation in the defined validation sequence.

11

The plug-in should expose validation events.

Purpose: Allow developers to control and enhance the validation process. Using the plug-in events it is possible to visualize the validation process, validation results, and build custom validation flows.

(error)

Native Oracle APEX validation doesn’t trigger events. When validation is successful the page is reloaded. When validation fails the page is not reloaded and validation errors are shown.

(tick)

The plug-in fires different events at each validation step.

12

The plug-in should allow executing validation after a button is clicked.

Purpose: Mimic native validation behavior.

(tick)

Native Oracle APEX validation is always performed after the button submitting the page is clicked.

(tick)

The plug-in validation can be triggered on a button click event which can be combined with the plug-in attributes to create more user-friendly validation.

13

The plug-in should allow item/column validation on the item/column event.

Purpose: Get validation results right after the user inputs data into the item/column.

(error)

Native Oracle APEX validation can be performed only after the page is submitted.

(tick)

The plug-in validation can be triggered on the item/column events supported by Oracle APEX dynamic actions. For example Change, Key release, and so on.

14

The plug-in should render validation errors using the Oracle APEX JavaScript API.

Purpose: Mimic native validation behavior.

(tick)

Native Oracle APEX validation renders validation results using the apex.message API.

(tick)

Validation errors are shown using the Oracle APEX apex.message API.

15

The plug-in should display validation errors in positions supported by APEX.

Validation errors can be shown in 4 different positions.

Purpose: Mimic native validation behavior.

(tick)

Native Oracle APEX validation behavior

(tick)

The plug-in supports 3 positions excluding the On Error Page position.

16

The plug-in should allow an overriding validation error display location.

Purpose: Give the possibility to show validation errors in different positions depending on triggering events. For example, show validation errors inline with the field when the triggering event is set to Change and show validation errors Inline with Field and Notifications when the specified button is clicked.

(error)

Native Oracle APEX validation result positions cannot be changed at run-time.

(tick)

The plug-in allows overriding the validation position from the perspective of dynamic action implementation. Even though the APEX validation result position is defined to be shown in a particular position, the plug-in can override it.

17

The plug-in should support HTML5 validations.

The native Oracle APEX validation process includes HTML5 validations.

Purpose: Mimic native validation behavior.

(tick)

Native feature

(tick)

The plug-in mimics the native approach and HTML5 validations are evaluated.

18

The plug-in should support translations for HTML5 validations.

HTML5 validation messages are based on end-user browser preferences, which means support the language currently selected by end-user.

Purpose: Make translating HTML5 validations easy and maintainable.

(error)

Native Oracle APEX HTML5 validations can’t be translated using the native approach.

(tick)

The plug-in supports HTML5 validation translations using native APEX text messages.

19

The plug-in should support translations for native validations

Validations are translated using the built-in Globalization feature.

Purpose: Mimic the native feature.

(tick)

Oracle APEX validations are translated using a Shadow Application.

(tick)

The plug-in supports a Shadow Application.

20

The plug-in should evaluate the validation authorization scheme before execution.

The Oracle APEX validation process includes evaluation of the authorization scheme assigned to the validation.

Purpose: Mimic the native feature.

(tick)

Native feature

(tick)

The plug-in mimics the native validation process and evaluates authorization schemes before executing a validation.

21

The plug-in should evaluate the validation conditions before executing the validation.

Oracle APEX validation process includes the evaluation of defined validation conditions.

Purpose: Mimic the native validation behavior.

(tick)

Native feature

(tick)

The plug-in mimics the native validation process and evaluates validation conditions before executing a validation.

22

The plug-in should be able to execute validations with the When Button Pressed attribute defined.

Purpose: Mimic the native validation behavior.

(tick)

Native feature

(tick)

The plug-in evaluates validations that have the When Button Pressed attribute set using the plug-in Request attribute.

23

The plug-in should support the debounce mechanism for events such as Key Down, Key Release, and Key Press for APEX items.

The plug-in debounce mechanism can be applied to APEX items. It is planned to support interactive grid columns in the future.

Purpose: Prevent duplicated validations for keyboard events.

(error)

Native Oracle APEX evaluates validations only after a page is submitted.

(tick)

Plug-in feature

24

The plug-in should expose configurable callbacks on validation results.

Purpose: Allow the possibility to create application flow based on validation results.

(error)

Native feature

(tick)

The plug-in allows creating JavaScript callbacks on validation results.

25

The plug-in should allow its execution to be debugged.

The plug-in validation process can be inspected using the Oracle APEX debug feature.

Purpose: Mimic the native validation debug.

(tick)

Native Oracle APEX validation can be inspected in debug mode.

(tick)

The plug-in supports debug mode and logs the plug-in validation process.

26

The plug-in should combine HTML5, client-side, and server-side validation together

All validations combined together.

(error)

Native Oracle APEX doesn’t support evaluating defined APEX validation on the client-side

(tick)

Plug-in feature

27

The plug-in should allow validations to be specified as Server-side only.

Purpose: Give a developer control as to whether defined validations should be executed on the client-side.

(error)

Native Oracle APEX validation doesn’t support executing some validation on the client-side.

(tick)

Plug-in feature

28

Preserve Errors

The plug-in validation can be implemented in separate dynamic actions under different conditions (triggering event, a different set of items). Each implementation can result in a different errors and the plug-in can make a summary of these results.

Purpose: Give a developer the control to decide whether currently executed validations should include errors from other implementations of the plug-in.

(error)

Native Oracle APEX validation is executed once on page submit and doesn’t need such a feature.

(tick)

Plug-in feature

29

Wait for results

Developers can define whether true actions following plug-in validation should be executed immediately after the validation or if they should wait for validation results.

Purpose: Give a developer control over dynamic action flow.

(error)

Native Oracle APEX validation is executed once on page submit and doesn’t need such a feature

(tick)

Plug-in feature

The Plug-in

Dynamic Action

Form Events

The plug-in can be bound with form inputs using standard events such as Key Release, Key Press, Key Down, Lose Focus, Change, and Click.

Triggering Elements and Affected Elements

The plug-in uses a combination of triggering elements and affected elements to evaluate a set of items (or interactive grid columns) to be validated. The table below describes currently supported combinations.

Triggering Element

Affected Elements

Element(s) to validate

Comment

Region

(not interactive grid)

Not set

Any APEX item from the region that triggered a dynamic action event

Use this combination to validate the item that has triggered a dynamic action event.

Item(s)

APEX item(s) defined as affected elements

Use this combination to validate the specified item(s) after a dynamic action event has been triggered in the specified region.

Column(s)

Not supported

Region

Item(s) that are defined under the specified region

Use this combination to trigger validation on items in the region that is specified in affected elements.

Region

(interactive grid)

Not set

Any interactive grid column that triggered a dynamic action event

Use this combination to trigger validation on a currently edited column after the specified dynamic action event

Item(s)

Not supported

Column(s)

All column(s) defined as affected elements

Use this combination to validate column(s) specified as affected elements after any column in a currently edited row triggers a dynamic action event.

Region

Not supported

Column(s)

Not set

A column defined as a triggering element that triggered a dynamic action event

Use this combination to validate the column specified as a triggering element after it triggers a dynamic action event.

Item(s)

Not supported

Column(s)

Column(s) defined as affected elements

Use this combination to validate the columns specified as affected elements after columns specified as triggering elements trigger a dynamic action event.

Region

Not supported

Item(s)

Not set

Any item that is specified as a triggering element and which triggered a dynamic action event

Use this combination to validate an item immediately after it triggers a dynamic action event.

Item(s)

APEX item(s) defined as affected elements

Use this combination to validate affected element item(s) after the item specified as a triggering element triggers a dynamic action event.

Column(s)

Not supported

Region

Item(s) that are defined under region specified in affected elements

Use this combination to validate item(s) that are children of the affected elements region after item(s) specified as a triggering element trigger a dynamic action event.

Button

Not set

All page items

Use this combination to validate all page items after the button specified as a triggering element triggers a dynamic action event.

Item(s)

APEX item(s) defined as affected elements

Use this combination to validate item(s) specified as affected elements after the button specified as a triggering element triggers a dynamic action event.

Column(s)

Not supported

Region

Item(s) that are defined under region specified in affected elements

Use this combination to validate item(s) that are children of the affected elements region after the button specified as a triggering element triggers a dynamic action event.

document

(framework events ie. Key Release, Change and so on)

Not set

APEX items(s) that can be mapped from a dynamic action event target

Use this combination to validate an item right after it triggers a dynamic action event. A dynamic action event property target is compared with existing APEX items and, if the event target references the APEX item, then it is validated.

Item(s)

APEX item(s) defined as affected elements

Use this combination to validate item(s) specified as affected elements after a dynamic action event is populated up to the document tree node.

Column(s)

Not supported

Region

Item(s) that are defined under region specified in affected elements

Use this combination to validate item(s) that are children of the affected elements region after a dynamic action event is populated up to the document tree node.

document

(custom event)

Not set

All page items

Use this combination to validate all page items after a dynamic action custom event is populated up to the document tree node.

Item(s)

APEX item(s) defined as affected elements

Use this combination to validate item(s) specified as affected elements after a dynamic action custom event is populated up to the document tree node.

Column(s)

Not supported

Region

Item(s) that are defined under region specified in affected elements

Use this combination to validate item(s) that are children of affected elements region after a dynamic action custom event is populated up to the document tree node.

Oracle APEX Validations

The plug-in uses native Oracle APEX validations to validate items (or interactive grid columns) on the client-side (without an AJAX call) and on the server-side (using an AJAX call).

The Supported Validation and Supported Validation Conditions sections describe Oracle APEX validations and Oracle APEX validation conditions that are supported by the plug-in. Read these sections to learn which native Oracle APEX validations and validation conditions can be executed by the plug-in on the client-side and which are supported only on the server-side.

Supported Validation

Oracle APEX validations are supported by the plug-in if the icon (tick) is presented in the Server-side column. Oracle APEX validations can be executed on the client-side (without PL/SQL context) if the icon (tick) is presented in the Client-side column.

For example, the Rows returned validation is supported by the plug-in but it can only be evaluated server-side (in the context of PL/SQL using an AJAX call). This is because the validation needs to evaluate a SQL Query which defines the validation result. On the other hand, native validation Item is NOT NULL can be tested on the client-side because it tests whether the given item has a value - it can be tested without the context of PL/SQL.

Validation

Client-side

Server-side

Rows returned

(error)

(tick)

No Rows returned

(error)

(tick)

SQL Expression

(error)

(tick)

PL/SQL Expression

(error)

(tick)

PL/SQL Error

(error)

(tick)

PL/SQL Function Body (returning Boolean)

(error)

(tick)

PL/SQL Function (returning Error Text)

(error)

(tick)

Item is NOT NULL

(tick)

(tick)

Item is NOT NULL or zero

(tick)

(tick)

Item is NOT zero

(tick)

(tick)

Item contains no spaces

(tick)

(tick)

Item is alphanumeric

(tick)

(tick)

Item is numeric

(tick)

(tick)

Item is a valid date

(error)

(tick)

Item is a valid timestamp

(error)

(error)

Item = Value

(tick)

(tick)

Item != Value

(tick)

(tick)

Item is contained in Value

(tick)

(tick)

Item is NOT contained in Value

(tick)

(tick)

Item contains only characters specified in Value

(tick)

(tick)

Item contains at least one of the characters in Value

(tick)

(tick)

Item does NOT contain any of the characters in Value

(tick)

(tick)

Item matches Regular Expression

(tick)

(tick)

Supported Validation Conditions

Oracle APEX validations conditions are supported by the plug-in if the icon (tick) is presented in Server-side column. Oracle APEX validation conditions can be evaluated on the client-side (without PL/SQL context) if the icon (tick) is presented in Client-side column.

For example, the PL/SQL Function Body validation condition requires PL/SQL context to evaluate an anonymous PL/SQL function, thus it can be executed only on the server-side (using an AJAX call).

Condition

Server-side

Client-side

Rows returned

(tick)

(error)

No Rows returned

(tick)

(error)

SQL Expression

(tick)

(error)

PL/SQL Expression

(tick)

(error)

PL/SQL Function Body

(tick)

(error)

Request = Value

(tick)

(tick)

Request != Value

(tick)

(tick)

Request is contained in Value

(tick)

(tick)

Request is NOT contained in Value

(tick)

(tick)

Item = Value

(tick)

(tick)

Item != Value

(tick)

(tick)

Item is NULL

(tick)

(tick)

Item is NOT NULL

(tick)

(tick)

Item is zero

(tick)

(tick)

Item is NOT zero

(tick)

(tick)

Item is NULL or zero

(tick)

(tick)

Item is NOT NULL and NOT zero

(tick)

(tick)

Item contains no spaces

(tick)

(tick)

Item is numeric

(tick)

(tick)

Item is NOT numeric

(tick)

(tick)

Item is alphanumeric

(tick)

(tick)

Item is in colon delimited list

(tick)

(tick)

Item is NOT in colon delimited list

(tick)

(tick)

User Preference = Value

(error)

 (error)

User Preference != Value

(error)

 (error)

Current Page = Page

(tick)

(tick)

Current Page != Page

(tick)

(tick)

Current Page is in comma delimited list

(tick)

(tick)

Current Page is NOT in comma delimited list

(tick)

(tick)

Current Page is in Printer Friendly Mode

(error)

 (error)

Current page is NOT in Printer Friendly Mode

(error)

 (error)

Page/Region is Read Only

(tick)

(error)

Page/Region is NOT Read Only

(tick)

(error)

User is Authenticated (not public)

(tick)

(tick)

User is the Public User (user has not authenticated)

(tick)

(tick)

Inline Validation Errors displayed

(tick)

 (error)

Inline Validation Errors NOT displayed

(tick)

 (error)

Current Language = Value

(error)

 (error)

Current Language != Value

(error)

 (error)

Current Language is contained in Value

(error)

 (error)

Current Language is NOT contained in Value

(error)

 (error)

Never

(tick)

(tick)

HTML5 Validations

HTML5 validations are performed for APEX items and interactive grid columns that have the required attribute set or have a subtype specified as URL, Phone, or E-mail.

Validation Flow

Validation Flow Diagram

The diagram below presents the plug-in validation flow. Each step of the plug-in validation flow is described in the sections below.

Validation Start

When a dynamic action implementing the plug-in is fired, the plug-in evaluates a combination of dynamic action triggering elements and the plug-in affected elements. The plug-in supports triggering elements such as document, Item(s), Region, Button, Interactive Grid, and Interactive Grid Column(s). Supported affected elements are Not set, Item(s), Region, Column(s).

Before the plug-in validation starts the Validation start event is triggered on the document - dynamic actions listening to this event have access to special validation objects exposed via this.data. A validation start event can be used to display the loading indicator and Validation end to remove it right after validation is done.

HTML5 Validation

HTML5 validations are browser driven validations that ensure that all fields are valid before submitting data to the server. In APEX, HTML5 validations can be applied to page items and Interactive Grid columns using item and column attributes Validation \ Value Required and Settings \ Subtype.

The plug-in performs HTML5 validation on every page item and interactive grid column. If the item or column has HTML5 validation enabled, the plug-in evaluates it and puts every error on the stack to be displayed using the APEX JavaScript API.

Client-side Validation

Client-side validation is performed on every item and column that has a validation qualified as a client-side validation. APEX validation is qualified as client-side if its evaluation can be done without the context of PL/SQL - you can check client-side validations and validation conditions in the Validation \ Validations section.

Native APEX validations that can be executed client-side are fetched from APEX tables by the plug-in when a page is loaded. These validations are evaluated using the plug-in’s predefined JavaScript test functions that represent native APEX validation tests. Thanks to this approach you don't have to write your own JavaScript functions to test the values of items and columns.

If client-side validation fails, errors are put on the stack of validation errors and the validation result is presented to end-user.

To enable client-side validations you must uncheck the Server-side Only plug-in setting. If this setting is checked, then client-side validation is not performed and the plug-in evaluates all defined validation on the server-side only.

Server-side Validation

Server-side validation is obligatory to forbid the end-user to affect validation results. When HTML5 and client-side validations are successful, the plug-in then performs validation on the server-side in the PL/SQL context. Items that are used in teh validation definition (validation expression or condition) are sent to the APEX session using an AJAX call and each validation is performed. The plug-in validation is done in two steps. First, the plug-in performs basic validation and then, immediately after, the plug-in performs the validation defined by the developer in the APEX page designer.

Basic Validation

The basic validation checks whether the item or column has the Validation \ Value Required attribute defined.

Validation End

When validation is finished the plug-in triggers the validation end event on the document and triggers the Item/Column is valid and Item/Column is invalid events depending on the validation result.

Attributes

Standard

Attribute

Supported

For Item(s)

(tick)

For Button

(error)

For Region

(tick)

For jQuery Selector

(error)

For JavaScript Expression

(error)

For Triggering Element

(error)

For Event Source

(error)

Affected Element Required

(error)

Check "Fire on Initialization"

(error)

Has "Stop Execution on Error" Attribute

(error)

Has "Wait For Result" Attribute

(tick)

Has "Initialization JavaScript Code" Attribute

(error)

Custom

Application Attributes

The plug-in doesn’t expose any application attributes.

Component Attributes

These attributes are available in page designer for the dynamic action implementing the plug-in. Use these attributes to define the validation process.

Attribute

Dependent on

Type

Description

Validation

Not applicable

Checkbox

Available options:

  • Force Execution on Server-side

  • Show processing

  • Custom Callback (Item)

  • Custom Callback (Validation)

  • Debounce mechanism

  • Request

Custom Item Callback

Validation

  • Custom Callback (Item) is checked

JavaScript Code

The anonymous function that will be executed by the plug-in when the validation finishes for one APEX item

Custom Validation Callback

Validation

  • Custom Callback (Validation) is checked

JavaScript Code

The anonymous function that will be executed by the plug-in when the validation finishes for all items

Debounce time

Validation

  • Debounce mechanism is checked

Number

Number of milliseconds to wait before executing the plug-in method validating an item/column

Request

Validation

  • Request is checked

Text

Request name so the plug-in will respect when button pressed condition and request related conditions

Help in the Page Designer

The plug-in attributes are exposed along with help text built into the page designer in the Help tab.

An example of the help for the plug-in attribute Settings \ Validation Settings is presented below.

Events

The plug-in exposes 6 events that can be bound using Oracle APEX dynamic actions.

Event name

Event name

Target

Validation start

validationstart

document

Validation end

validationend

document

Validation item is valid

validationitemisvalid

APEX item

Validation item is invalid

validationitemisinvalid

APEX item

Validation column is valid

validationcolumnisvalid

Interactive Grid region

Validation column is invalid

validationcolumnisinvalid

Interactive Grid region

Event Data

Each validation event has access to data describing validation state.

Validation start

Variable

Description

Scope

this.data.columns

An array of column names to be validated

Column

this.data.recordId

Interactive grid column record id

Column

this.data.region

Reference to an interactive grid DOM element

Column

this.data.items

An array of item names to be validated

Item

this.data.affectedElements

Affected elements of the dynamic action responsible for validation

Item & Column

this.data.browserEvent

An event that executed the dynamic action responsible for validation

Item & Column

this.data.triggeringElement

Triggering element of the dynamic action responsible for validation

Item & Column

Validation end

Variable

Description

Scope

this.data.columns

An array of column names to be validated

Column

this.data.recordId

Interactive grid column record id

Column

this.data.region

Reference to an interactive grid DOM element

Column

this.data.items

An array of item names to be validated

Item

this.data.affectedElements

Affected elements of the dynamic action responsible for validation

Item & Column

this.data.browserEvent

An event that executed the dynamic action responsible for validation

Item & Column

this.data.errors

An array of errors returned by a validation

Item & Column

this.data.triggeringElement

Triggering element of the dynamic action responsible for validation

Item & Column

Validation item is valid

This event doesn't expose any data through this.data.

Validation item is invalid

The variable this.data has only the errors property. Errors is an array of validation errors and each entry is described below:

Variable

Description

this.data.errors[i].displayLocation

Validation message display location code. Possible values are:

  • INLINE_WITH_FIELD_AND_NOTIFICATION,

  • INLINE_WITH_FIELD,

  • INLINE_IN_NOTIFICATION,

  • ON_ERROR_PAGE

this.data.errors[i].item

Item name of the validation that failed

this.data.errors[i].message

Validation failure message

Validation column is valid

Variable

Description

this.data.column

Interactive grid validated column name

this.data.recordId

Interactive grid validated column record ID (PK)

Validation column is invalid

Variable

Description

this.data.column

Interactive grid validated column name

this.data.errors

JavaScript array of column validation errors

this.data.recordId

Record id (primary key) of the validated column

Each entry of this.data.errors has the properties described below:

Variable

Description

this.data.errors[i].column

Interactive grid validated column name

this.data.errors[i].displayLocation

Validation message display location code. Possible values are:

  • INLINE_WITH_FIELD_AND_NOTIFICATION,

  • INLINE_WITH_FIELD,

  • INLINE_IN_NOTIFICATION,

  • ON_ERROR_PAGE

this.data.errors[i].message

Validation failure message

this.data.errors[i].recordId

Record id (primary key) of the validated column

Translations

The plug-in supports translations for validation messages. The plug-in can translate HTML5 validation messages (user’s browser) and native APEX validations. 

Native Validations

To translate APEX defined validations the plug-in uses a translated application (Shadow Application).

HTML5 Validations

An HTML5 validation message's language is dependent on the user's browser language. The plug-in translates these messages by overriding them with messages defined as Oracle APEX text messages.

To translate validations ensure that:

  • The Globalization \ Application Language Derived From application attribute is set and the application supports translations

  • HTML5 Text Messages have Used in JavaScript set to Yes

Text Message Code

Description

APEX.PAGE_ITEM_IS_REQUIRED

Message displayed when required item is empty

HTML5.PAGE_ITEM_IS_TEL

Message displayed when phone item doesn’t match phone pattern

HTML5.PAGE_ITEM_IS_URL

Message displayed when url item doesn’t match url pattern

HTML5.PAGE_ITEM_IS_EMAIL

Message displayed when e-mail item doesn’t match e-mail pattern

Additionally, if the HTML5 validation defined for an item or interactive grid column uses data-valid-message to present a custom message then the plug-in tries to translate the custom message. The translation is done using the native apex.lang.getMessage APEX API. The parameter for the getMessage function is the value of the data-valid-message attribute.

Usage Guide

This section describes three basic examples of implementing the plug-in to validate a simple form and interactive grid columns. The usage guide shows a basic implementation of the plug-in but does not describe the plug-in attributes or ideas on how the plug-in can be used.

Examples of how the plug-in attributes can be used to enrich the validation process are shown and described in the Client-side Validation Pro sample application.

Validation on Button Click

This guide describes the plug-in validation performed after clicking the BTN_PLUGIN_VALIDATION button. The dynamic action implementing the plug-in only performs validation without submitting the page and doesn’t implement any fancy features of the plug-in.

Introduction

In an example application, page 710 is defined. On the page, a region called Form is created and contains 3 items and 1 button.

Oracle APEX items:

  • P710_ENAME

  • P710_DEPARTMENT

  • P710_SAL

Oracle APEX buttons:

  • BTN_PLUGIN_VALIDATION

The BTN_PLUGIN_VALIDATION button has it’s behavior set to Defined by Dynamic Action and it will be used to trigger the plug-in validation.

Each item has a native Oracle APEX validation defined which is described in the table below:

Item

Validation

P710_ENAME

Item is NOT NULL

P710_ENAME

Item is alphanumeric

P710_DEPARTMENT

Item is NOT NULL

P710_SAL

Item is NOT NULL

P710_SAL

Item is numeric

Page 710 in page designer is presented below:

The resulting page will look as follows:

Implementing the Plug-in

To implement the plug-in, creating a new dynamic action is required. Follow the steps below:

Dynamic Action

  1. Create a new dynamic action

  2. Change the dynamic action’s name to The plug-in validation on button click

  3. Set When \ Event to Click

  4. Set When \ Selection Type to Button

  5. Set When \ Button to BTN_PLUGIN_VALIDATION

The dynamic action definition in the page designer is presented below:

Dynamic Action - True Action

The default true action of the newly defined dynamic action is Show.

  1. Select the default true action Show

  2. Change Identification \ Action to Client-side Validation Pro [Plug-in]

  3. (Optional) Configure the plug-in using the Settings attributes

  4. Set Affected Elements \ Selection Type to Region

  5. Set Affected Elements \ Region to Form

  6. Set Execution Options \ Fire on Initialization to No

  7. Save the page

The plug-in dynamic true action is presented below:

Test the Implementation

  1. Open page 710 in browser

  2. Click button BTN_PLUGIN_VALIDATION (plug-in validation)

The result after clicking the BTN_PLUGIN_VALIDATION button is presented below:

Validation on Item Event

This guide describes the plug-in validation performed each time the Lose Focus event is triggered on any item in the specified form. The dynamic action implementing the plug-in performs only the defined validations without implementing any fancy features of the plug-in.

Examples of how the plug-in attributes can be used are shown and described in the Client-side Validation Pro sample application.

Introduction

In an example application, page 720 is created. On the page, a region called Form is created and contains 3 items.

Oracle APEX items:

  • P720_ENAME

  • P720_DEPARTMENT

  • P720_SAL

Each item has a native Oracle APEX validation defined which is described in the table below.

Item

Validation

P720_ENAME

Item is NOT NULL

P720_ENAME

Item is alphanumeric

P720_DEPARTMENT

Item is NOT NULL

P720_SAL

Item is NOT NULL

P720_SAL

Item is numeric

Page 720 in page designer is presented below:

The resulting page will look as follows:

Implementing the Plug-in

To implement the plug-in, creating new dynamic action is required. Follow the steps below:

Dynamic Action

  1. Create a new dynamic action

  2. Change the dynamic action’s name to The plug-in validation on item(s) Lose Focus event

  3. Set When \ Event to Lose Focus

  4. Set When \ Selection Type to Region

  5. Set When \ Region to Form

The dynamic action definition in the page designer is presented below:

Dynamic Action - True Action

The default true action of the newly defined dynamic action Show.

  1. Select the default true action, Show

  2. Change Identification \ Action to Client-side Validation Pro [Plug-in]

  3. (Optional) Configure the plug-in using the Settings attributes

  4. Empty the Affected Elements \ Selection Type attribute (set value to - Select -)

  5. Set Execution Options \ Fire on Initialization to No

  6. Save the page

The plug-in dynamic true action is presented below:

Test the Implementation

The plug-in validation is executed when the end-user leaves the input (event Lose Focus is triggered)

  1. Open page 720 in a browser

  2. For item P720_ENAME

    1. when the field is empty, focus it and click outside of it - validation Ename not null error message is displayed

    2. input non-alphanumeric values and click outside of the item - validation Ename alphanumeric error message is displayed

  3. For item P720_DEPTNO

    1. when the field is empty ( - Select - ), focus it and click outside of it - validation Deptno not null error message is displayed

    2. select any value that is not - Select -, no validation errors are displayed for this field

  4. For item P720_SAL

    1. when the field is empty, focus it and click outside it - validation Sal not null error message is displayed

    2. input a non-numeric value and click outside of the item - validation Sal numeric error message is displayed

Example validation result after providing invalid values is presented below:

Validation on Interactive Grid Columns

This guide describes the plug-in validation performed each time the Change event is triggered on interactive grid ENAME, JOB, and SAL columns. The dynamic action implementing the plug-in performs only the defined validations without implementing any fancy features of the plug-in.

Examples of how the plug-in attributes can be used are shown and described in the Client-side Validation Pro sample application.

Introduction

In an example application, page 730 is defined. On the page, an interactive grid region called Employees is created on the emp table. Columns ENAME, JOB and SAL have native Oracle APEX validations defined as described in the table below:

Column

Validation

ENAME

Column is not null

ENAME

Column is alphanumeric

JOB

Column is not null

SAL

Column is not null

SAL

Column is numeric

Page 730 in page designer is presented below:

The resulting page will look as follows:

Implementing the Plug-in

To implement the plug-in, creating a new dynamic action is required. Follow the steps below:

Dynamic Action

  1. Create a new dynamic action

  2. Change the dynamic action’s name to The plug-in validation on IG column(s)

  3. Set When \ Event to Change

  4. Set When \ Selection Type to Column(s)

  5. Set When \ Region to Employees

  6. Set When \ Column(s) to ENAME,JOB,SAL

The dynamic action definition in the page designer is presented below:

Dynamic Action - True Action

The default true action of the newly defined dynamic action is Show.

  1. Select the default true action, Show

  2. Change Identification \ Action to Client-side Validation Pro [Plug-in]

  3. (Optional) Configure the plug-in using the Settings attributes

  4. Empty the Affected Elements \ Selection Type attribute (set value to - Select -)

  5. Set Execution Options \ Fire on Initialization to No

  6. Save the page

The plug-in’s true action is presented below:

Test the Implementation

  1. Open page 730 in a browser

  2. For the ENAME column, insert invalid characters (out of alphanumeric scope). For example !@#.

  3. For the JOB column, select the null value (- Select -)

  4. For the SAL column, insert invalid characters (out of numeric characters). For example Not numeric value.

The validation result will be visible after you leave the currently edited column. Example validation errors are presented below:

Sample Application

The plug-in is delivered with a sample application which describes all of the features of Client-side Validation Pro with example implementations. The sample application describes and implements the following topics:

The Basics

The basics describe how the plug-in works, how the plug-in events can be used, and allows live testing of the plug-in’s core functionality - evaluating native Oracle APEX validations and validation conditions on the client-side and the server-side.

  • Flow

  • Validations

  • Conditions

  • Events

  • Translations

Plug-in Attributes

The plug-in attributes pages describes and shows example implementations of each of the plug-in attributes.

  • Debounce

  • Server-Side Only

  • Callbacks

  • Override Display Location

  • Request

  • Wait for Results

  • Preserve Errors

Triggering Element

The triggering element pages describe and show the implementation of each combination of the triggering elements and affected elements.

  • Document

  • Region

  • Button

  • Item(s)

  • Interactive Grid

  • Interactive Grid Column(s)