15.2 Understanding Validations

Use validations to create edit checks on specific items, pages, or columns.

• About Validations
  Learn about validations.
• What Happens When a Validation Fails?
  Learn what happens when a validation fails.
• Creating a Validation
  Create validations in Page Designer.
• Editing a Validation
  Edit validations in Page Designer.
• About Determining When Validations Execute
  Determine when a validation executes by edting the Always Execute attribute.
• About Defining How Validation Error Messages Display
  Control how validation messages display by editing the Error Message and Error Message attributes.
• Processing Validations Conditionally
  Control when and if a validation executes by configuring the Server-side Condition attributes.
• About Altering the Go to Error Link
  Alter the Go to Error text to change the default text or to translate it into a language that is not translated by default.

15.2.1 About Validations

Learn about validations.

A validation is an edit check. Validations specific to a single item are page item validations. Validations that apply to an entire page are page validations. Validations for tabular forms specific to a single column are column level validations. Validations for tabular forms that do not apply to a single column are tabular form row validations.

You can define a validation declaratively by selecting a validation method. You enter the actual validation edit check in the Validation Messages field. Be aware that if a validation fails, subsequent page processes or computations do not occur. Also remember that the validation you enter must be consistent with the validation type you selected.

15.2.2 What Happens When a Validation Fails?

Learn what happens when a validation fails.

If a page is submitted and some of the validations fail, Oracle Application Express redisplays the existing page with all inline validation errors. While displaying inline errors, Application Express does not execute computations, application processes, or page processes (for example, Automated Row Fetch) which are defined to execute during Page Rendering (in other words, all "On Load %" display points). The one exception is if the computations and processes use the condition type Inline Validation Errors Displayed.

The reason for skipping these computations and processes is that any of they could potentially alter the data entered by the user. For example, an Automated Row Fetch process would fetch and overwrite the modified data with the values from the database when the user actually wants to get the entered data in order to fix the validation error.

If a computation is skipped, the following displays in the debug output:

Do not perform computation because inline validation errors found.

If an application or page process is skipped, the following displays in the debug output:

Skip because inline validation errors found.

15.2.3 Creating a Validation

Create validations in Page Designer.

Note:

Text entered for validations may not exceed 3,950 characters.

To create a validation in Page Designer:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Click the Processing tab in the left pane.
3. Right-click Validations and select Create Validation.

   Validation attributes display in the Property Editor. Attributes are organized in groups.

   Note:

   To find a group or attribute, enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. Or, you can click Go to Group and select the group.

4. Identification, Name - Enter the name of the validation. Make this name should be descriptive so that developers can easily identify conditions being checked.
5. Execution Options, Sequence - Enter the sequence for this validation. The sequence determines the order of execution.
6. Edit the following Validation attributes:
   1. Validation, Editable Region - Select the associated region.
   2. Validation, Type - Select the type of equality to be tested for this validation. Depending on your selection, one or more additional attributes are required to fully define this validation.
      If the validation passes the equality test, or evaluates to TRUE, then the validation error message does not display. Validation error messages display when the validation fails the equality test, or evaluates to FALSE, or a non-empty text string is returned.
   3. Validation, Always Execute - Specify whether this validation always executes.
      If set to On, this validation is always evaluated, irrespective of the Execute Validations setting defined against the button that submitted the page. If set to Off, this validation is only evaluated if the triggering button has an Execute Validations setting of On.
7. Edit the following Error attributes:
   1. Error, Error Message - Enter text for the error message.
   2. Error, Display Location - Select where the error message displays for this validation.
      Validation error messages display on a separate error page, or inline with the existing page. Inline error messages display underneath the Associated Item label and/or in a Notification area, defined as part of the page template.
   3. Error, Associated Item - Select the item where this validation error message displays.
      If you select an item and the Error message display location includes Inline with Field, the error message displays underneath the label of the specified item. If the Error message display location does not include Inline with Field, this attribute has no impact on the display of the error message.
8. Click Save.

See Also:

• "Creating Pre-Rendering Branches, Computations, and Processes"

• "Creating Page Submission Branches, Validations, Computations, and Processes"

15.2.4 Editing a Validation

Edit validations in Page Designer.

To edit a validation in Page Designer:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Click the Processing tab in the left pane.
3. Expand Validating and then Validations and select the validation.
   Validation attributes display in the Property Editor. Attributes are organized in groups.

   Note:

   To find a group or attribute, enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. Or, you can click Go to Group and select the group.

4. In the Property Editor, edit the appropriate attributes.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.

5. Click Save.

15.2.5 About Determining When Validations Execute

Determine when a validation executes by edting the Always Execute attribute.

The Always Execute attribute determines if validations execute when a page is submitted. Use this attribute for buttons or certain page items that submit a page. The Always Execute attribute has two options:

• On - The validation always executes independent of validation settings for buttons or items on a page.

  For example, select On if your validation is a security check which determines if the current user is allowed to modify or delete the current record. This ensures the validation executes for any operation and prevents unprivileged users from modifying data.

• Off - The validation only executes if the button or item used to submit the page has the Execute Validations attributes set to On.

  For example, it is not useful to verify that an item be numeric and display an error message if the user is simply deleting a record. In that scenario, the validations should only execute when the user clicks the Create or Apply Changes buttons.

  To accomplish this behavior:

  • For the validation, set Always Execute to On

  • For the Create and Apply Changes buttons, set Execute Validations to On.

  • For the Delete button, set Execute Validations to Off to avoid unnecessary validations.

See Also:

"Editing a Validation"

15.2.6 About Defining How Validation Error Messages Display

Control how validation messages display by editing the Error Message and Error Message attributes.

You can choose to have validation error messages display inline (that is, on the page where the validation is performed) or on a separate error page.

You define how a validation error message displays by configuring the following validation attributes:

1. Error, Error Message - Enter the error message text in this field. You can use #LABEL# as placeholder for the label of the associated page item or #COLUMN_HEADER# for the heading of the associated editable region column. The placeholders are not supported if error display location is set to On Error Page.

2. Error, c - Select where the error message displays for this validation. Validation error messages display on a separate error page, or inline with the existing page. Inline error messages display underneath the Associated Item label and/or in a Notification area, defined as part of the page template.

   Options include:

   • Inline with Field and in Notification - Error displays inline within the field label and within a notification area (defined as part of the page template).

   • Inline with Field - Error displays inline within the field label.

   • Inline in Notification - Error displays inline within a notification area (defined as part of the page template).

   • On Error Page - Displays the error on a separate error page. To create a hard error that stops all processing (including validations), you must display the error on an error page.

3. Error, Associated Item (or Column) - Select the item (or column) where this validation error message displays.

   If you select an item and the Error message display location includes Inline with Field, the error message displays underneath the label of the specified item. If the Error message display location does not include Inline with Field, this attribute has no impact on the display of the error message.

See Also:

"Editing a Validation"

15.2.7 Processing Validations Conditionally

Control when and if a validation executes by configuring the Server-side Condition attributes.

You can control when and if a validation executes by configuring the following Server-side Condition attributes:

1. Server-side Condition, When Button Pressed - If you want this page processing component to execute only when the specified button is clicked, select a button from the list. You can incorporate this button condition with other conditions to further refine when this page processing component executes.

   If no button is pressed, other conditions are evaluated before performing the validation.

2. Server-side Condition, Type - Select a condition type from the list that must be met in order for this component to be rendered or processed.
   To view a list of options, select the Type attribute in the Property Editor and click the Help tab in the central pane.

See Also:

• "Editing a Validation"

• "Understanding Conditional Rendering and Processing"

15.2.8 About Altering the Go to Error Link

Alter the Go to Error text to change the default text or to translate it into a language that is not translated by default.

If you define an associated item, Oracle Application Express renders a Go to Error link in the Notification display location next to the corresponding error message. When clicked, the user's focus is set to the associated item.

You can alter the Go to Error text to change the default text or to translate it into a language that is not translated by default with Oracle Application Express. In either case, define a text message called APEX.GO_TO_ERROR with the text and language of your choice. Additionally, you can disable this functionality and remove the Go to Error link by setting the text of the APEX.GO_TO_ERROR text message to just a single space.

See Also:

"Translating Messages Used Internally by Oracle Application Express"