15.2 Understanding Validations

This section describes how to create validations.

Topics:

15.2.1 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 Managing Validations in Page Designer

This section describes how to create validations.

Topics:

See Also:

See Also:

15.2.2.1 Creating a Validation in Page Designer

To create a validation in Page Designer:

Note:

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

  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.

    To view all attributes in the Property Editor, click Show All .

  4. To search for a group or an attribute, enter a keyword in the Filter Properties field.
  5. Edit the following attributes:
    1. Identification, Name - Enter the name of the validation.
    2. Execution Options, Sequence - Enter the sequence for this validation. The sequence determines the order of execution.
    3. Validation, Editable Region - Select the associated region.
    4. 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.

    5. Validation, Always Execute - Specify whether this validation always executes.

      If set to Yes, this validation is always evaluated, irrespective of the Execute Validations setting defined against the button that submitted the page. If set to No, this validation is only evaluated if the triggering button has an Execute Validations setting of Yes.

    6. Error, Error Message - Enter text for the error message.
    7. 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.

    8. Error, Associated Item/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.

      Tip:

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

  6. Click Save.

See Also:

15.2.2.2 Editing a Validation 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.

    Property Editor displays Validation attributes.

  4. To view all attributes in the Property Editor, click Show All .
  5. To search for a group or an attribute, enter a keyword in the Filter Properties field.
  6. 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.

  7. Click Save.

15.2.3 Managing Validations in Legacy Component View

Developers create a validation by running the Create Validation Wizard. This wizard changes slightly depending upon what you are validating. Validations are either specific to a given field (either a single page item or tabular form column validation) or, they are not field specific (either a page or tabular form row validation).

Topics:

See Also:

15.2.3.1 Creating a Validation for a Page Item

To create a validation for a page item:

Note:

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

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. Access the Create Validation Wizard. Under Page Processing, locate Validations. Click the Create icon.

    The Create Validation Wizard appears.

  3. For Identify the validation level, select Page Item and click Next.
  4. For Identify the Page Item that is to be validated, select the item to be validated and click Next.
  5. For Sequence and Name:
    1. Sequence - Enter the sequence number for this item.
    2. Validation Name - Enter a name for the validation.
    3. Error Display Location - Select the display location of the validation error message. Validation error messages can display on an error page or inline with the submitted page. Inline validations can display in the notification area (defined as part of the page template) or within the field label.
    4. Click Next.
  6. For Validation Type, select a method as described inTable 15-1 and click Next.

    Table 15-1 Page Item Validation Methods

    Validation Method Descriptions

    Not Null

    Checks if an item's value in session state is null.

    For example, you could validate that the user enters a value in a field by creating an item validation and then selecting the validation method Item Not Null.

    String Comparison

    Compares the value of an item to a specific string. When prompted select a validation type.

    There are several string comparison validations that compare the value of an item to a literal string. For example, you select the validation type Item in Expression 1 is contained in Expression 2 to validate a user entry in a field against a list of values you provide.

    In Expression 1, enter the name of the item you want to validate without a colon. For example:

    P1_VALUE

    In Expression 2, enter a string of values you want to validate against. For example:

    ABC/DEF/GHI

    Regular Expression

    Regular expressions provide a method to describe text patterns. Use a Regular Expression validation to perform data validation. When prompted, enter a regular expression.

    For example, you could use the following regular expression validation to verify that a string of entered data always consists of groups of six numbers separated by commas and followed by a comma:

    ^([[:digit:]]{6},)+$

    This regular expression would find the following entries valid:

    123456,654321,

    123456,

    123456,123456,654321,

    However, the following would not be valid:

    123456,12345

    12345

    SQL

    Compares to values in the database. Select a validation type:

    • Exists

    • NOT Exists

    • SQL Expression

    For example, you can use a SQL validation to verify whether a last name typed into a field exists in the database. In the following Exists SQL validation, the field is named P1_LAST_NAME and the table is named customers.

    SELECT 1 FROM customers 
WHERE last_name = :P1_LAST_NAME

    To learn more, see the syntax examples at the bottom of the page.

    PL/SQL

    Useful if you need complex logic. Select a validation type:

    • PL/SQL Expression

    • PL/SQL Error

    • Function Returning Boolean

    • Function Returning Error Text

    For example, suppose you need to create a validation for an address form that requires the user to enter a province if the address is not in the United States. You could create the validation as a Function Returning Boolean, using the following PL/SQL:

    BEGIN
  IF :P1_COUNTRY = 'US' AND :P1_PROVINCE IS NULL THEN
     RETURN FALSE;
  ELSE
    RETURN TRUE;
  END IF;
END;

    You could also create the same validation implemented as a PL/SQL Expression as follows:

    NOT (:P1_COUNTRY='US' AND  :P1_PROVINCE IS NULL);

    To learn more, see the syntax examples at the bottom of the page.
  7. For Validation:
    1. Error Message - Depending upon the validation method, enter the validation or message text that displays if the validation fails.

      You can use #LABEL# as placeholder for the label of the associated page item.

    2. Always Execute - Determines if validations execute when a page is submitted. Use this attribute with the Execute Validations attribute for buttons or certain page items that submit a page. Option include:

      • Yes - The validation always executes independent of validation settings for buttons or items on a page. Note that defined conditions still apply.

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

    3. Click Next.
  8. Define conditions that apply to this validation and click Create.

15.2.3.2 Creating a Validation for an Entire Page

To create a validation for an entire page:

Note:

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

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. To access the Create Validation Wizard. Under Page Processing, locate Validations. Click the Create icon.

    The Create Validation Wizard appears.

  3. For Validation Level, select Page and click Next.
  4. For Sequence and Name:
    1. Sequence - Enter the sequence number for this item.
    2. Validation Name - Enter a name for the validation.
    3. Error Display Location - Select the display location of the validation error message. Validation error messages can display on an error page or inline with the submitted page. Inline validations can display in the notification area (defined as part of the page template) or within the field label.
    4. Click Next.
  5. For Validation Type, select a method as described in Table 15-2and click Next.

    Table 15-2 Page Validation Methods

    Validation Method Descriptions

    SQL

    Compares to values in the database. Select a validation type:

    • Exists

    • NOT Exists

    • SQL Expression

    To learn more, see the syntax examples at the bottom of the page.

    PL/SQL

    Useful if you need complex logic. Select a validation type:

    • PL/SQL Expression

    • PL/SQL Error

    • Function Returning Boolean

    • Function Returning Error Text

    To learn more, see the syntax examples at the bottom of the page.
  6. For Validation:
    1. Validation Code - Enter the code corresponding to the validation type selected.
    2. Error Message - Depending upon the validation method, enter the validation or message text that displays if the validation fails.

      You can use #LABEL# as placeholder for the label of the associated page item.

    3. Always Execute - Determines if validations execute when a page is submitted. Use this attribute with the Execute Validations attribute for buttons or certain page items that submit a page. Option include:

      • Yes - The validation always executes independent of validation settings for buttons or items on a page. Note that defined conditions still apply.

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

    4. Click Next.
  7. Define conditions that apply to this validation and click Create.

See Also:

"About Determining When Validations Execute"

15.2.3.3 Creating a Validation for a Tabular Form Column

To create a validation for a tabular form column:

Note:

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

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. To access the Create Validation Wizard. Under Page Processing, locate Validations. Click the Create icon.

    The Create Validation Wizard appears.

  3. For Validation Level:
    1. Tabular Form - Select the associated tabular form region for this Validation.
    2. Identify the validation level - Select Column.
    3. Click Next.
  4. For Identify the Column that is to be validated, select a column and click Next.
  5. For Sequence and Name specify the following and click Next.

    • Sequence - Enter the sequence number for this item.

    • Validation Name - Enter a name for the validation.

    • Error Display Location - Select the display location of the validation error message. Validation error messages can display on an error page or inline with the submitted page. Inline validations can display in the notification area (defined as part of the page template) or within the field label.

  6. For Validation Type, select a method, follow the on-screen instructions and click Next.
  7. For Validation:
    1. Define the validation. The attributes that display depend upon the Validation Type selected.
    2. Error Message - Depending upon the validation method, enter the validation or message text that displays if the validation fails.

      You can use #COLUMN_HEADER# as placeholder for the column header of the associated tabular form column.

    3. Always Execute - Determines if validations execute when a page is submitted. Use this attribute with the Execute Validations attribute for buttons or certain page items that submit a page. Option include:

      • Yes - The validation always executes independent of validation settings for buttons or items on a page. Note that defined conditions still apply.

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

    4. Click Next.
  8. For Conditions, define conditions that apply to this validation.
  9. Click Create Validation.

See Also:

"About Determining When Validations Execute"

15.2.3.4 Creating a Validation for a Tabular Form Row

To create a validation for a tabular form row:

Note:

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

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. To access the Create Validation Wizard. Under Page Processing, locate Validations. Click the Create icon.

    The Create Validation Wizard appears.

  3. For Validation Level:
    1. Tabular Form - Select the associated tabular form region for this Validation.
    2. Identify the validation level - Select Tabular Form Row.
    3. Click Next.
  4. For Sequence and Name specify the following and click Next.
    1. Sequence - Enter the sequence number for this item.
    2. Validation Name - Enter a name for the validation.
    3. Error Display Location - Select the display location of the validation error message. Validation error messages can display on an error page or inline with the submitted page. Inline validations can display in the notification area (defined as part of the page template) or within the field label.
  5. For Validation Type, select a validation type and follow the on-screen instructions and click Next.
  6. For Validation:
    1. Validation Code - Enter the code corresponding to the validation type selected.
    2. Error Message - Depending upon the validation method, enter the validation or message text that displays if the validation fails.

      You can use #COLUMN_HEADER# as placeholder for the column header of the associated tabular form column.

    3. Always Execute - Determines if validations execute when a page is submitted. Use this attribute with the Execute Validations attribute for buttons or certain page items that submit a page. Option include:

      • Yes - The validation always executes independent of validation settings for buttons or items on a page. Note that defined conditions still apply.

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

    4. Click Next.
  7. For Conditions:
    1. When Button Pressed - Select a page buttons which when selected permits this validation to be performed, subject to other conditions.
    2. Condition Type -Select a condition type from the list that must be met in order for this component to be rendered processed.
    3. Click Next.
  8. Click Create Validation.

See Also:

"About Determining When Validations Execute"

15.2.3.5 Editing a Validation in Component View

To create a validation for a tabular form row:

Note:

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

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. Under Validations, select the validation.

    The Edit Page Validations page appears.

  3. Edit the appropriate attributes.

    To learn more about an attribute, see field-level Help.

  4. Click Apply Changes.

See Also:

"Viewing Field-Level Help"

15.2.4 About Determining When Validations Execute

When creating a validation, 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:

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

    For example, select Yes 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.

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

    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 example, 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 No

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

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

See Also:

15.2.5 About Defining How Validation Error Messages Display

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 Message - Enter the error message text in this field.

  2. 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.

    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. 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 in Page Designer"

15.2.6 Processing Validations Conditionally

You can control when and if a validation is performed by configuring the following Conditions attributes:

  1. 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. Execution Scope - Applicable only to tabular forms. Specify the execution scope:

    • For Created and Modified Rows - The validation executes only for created and modified rows in your tabular form.

    • All Submitted Rows - The validation executes for every submitted row.

  3. 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, click the Help tab.

See Also:

15.2.7 About Altering the Go to Error Link

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"

15.2.8 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, Oracle 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.