8.5 Understanding Page Processes

A page process performs an action at a specified point during the rendering or submission of the page. For example, you can create a page process to execute logic or to make a call to the Application Express engine. A page process is a unit of logic that runs when a specific event occurs, such as loading or submitting a page.

From a functional perspective, there is no difference between page-level and application-level processes. The difference between these two process types is where the process is defined, that is at the page-level or at the application level.

Tip:

To learn more about execution behavior in the case of a validation error, see "What Happens When a Validation Fails?"

Topics:

See Also:

"Understanding Application Processes" and "About Cross Page Utilities"

8.5.1 About Creating a Page Process

You create a process by running the Create Process Wizard. During the wizard, you define a process name, specify a sequence and the point at which the process executes, and select a process category. You can change nearly all of these attributes on the Edit Page Process page.

Topics:

8.5.1.1 Creating a Page Process

To create a page process:

  1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

  2. Access the Create Page Process Wizard:

    • Tree view - Under the appropriate page rendering event (such as Before Header, After Header and so on), locate Processes. Right-click and select Create.

    • Component view - Under Processes, click the Create icon.

  3. For Process Type, select the category of the process you want to create as described in Table 8-14.

    Table 8-14 Page Process Categories

    Process Category Description

    PL/SQL

    Runs the PL/SQL you provide. Use this process type to execute a block of PL/SQL entered directly into the process or to simply call an existing API.

    Reset Pagination

    In Report regions, resets pagination back to the first result set. The Application Express engine keeps track of where the user is within a given result set. This process category returns the user to the beginning result set. In other words, this category resets the counters associated with the report region to return the first part of the result set the next time the result set displays.

    Plug-ins

    Plug-ins allow developers to declaratively extend the built-in types available with Application Express. This option is only available when a plug-in type process exists in this application.

    See Also: "Implementing Plug-ins"

    Session State

    Sets the values of existing session state items to null. Select this process type to clear the cache for applications, sessions, or items and to clear existing user preferences.

    See Also: "Managing Session State Values" and "Managing User Preferences" in Oracle Application Express Administration Guide

    Data Manipulation

    Data Manipulation process types are frequently used by wizards to support data manipulation language (DML) actions. Application Builder supports the following declarative data manipulation processes:

    • Select Automatic Row Fetch and Automatic Row Processing (DML) to create an automatic data manipulation language (DML) process.

    • Use Multi Row Update and Multi Row Delete with tabular forms.

    • Use Add Rows to Tabular Form with a tabular form.

    Web Services

    Implements a Web Service as a process on a page. Running the process submits a request to the service provider.

    See Also: "Invoking a Web Service as a Process"

    Form Pagination

    Implements pagination through the detail records associated with a master detail form. Most often used in master detail forms (such as in the Master Detail Wizard), this process checks the master table to determine which set of detail records you are in and determines what the next detail record should be.

    See Also: "Creating a Master Detail Form"

    Send E-Mail

    Provides a declarative interface for the APEX_MAIL.SEND_MAIL package. The process type support attachments.

    Close popup window

    Applies to processes running within a popup window. Upon execution, this process type closes the current popup window.

    Run On Demand Process

    Creates an application-level process that can only be executed when called from a specific page. When you create this process type at the page-level, you are creating reference to an existing application-level process.

    See Also: "About On Demand Application Processes"

  4. Follow the on-screen instructions.

8.5.1.2 Creating a Tabular Form Page Process

To create a tabular form page process:

  1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

  2. Access the Create Page Process Wizard:

    • Tree view - Under the appropriate page rendering event (such as Before Header, After Header and so on), locate Processes. Right-click and select Create.

    • Component view - Under Processes, click the Create icon.

  3. For Process Type:

    • Tabular Form - Select the associated tabular form region.

    • Select the category of the process you want to create as described in Table 8-15:

      Table 8-15 Tabular Form Process Categories

      Process Category Description

      PL/SQL

      Runs the PL/SQL you provide. Use this process type to execute a block of PL/SQL entered directly into the process or to simply call an existing API.

      Plug-ins

      Plug-ins allow developers to declaratively extend the built-in types available with Application Express. This option is only available when a plug-in type process exists in this application.

      See Also: "Implementing Plug-ins"

      Data Manipulation

      Data Manipulation process types are frequently used by wizards to support data manipulation language (DML) actions. Application Builder supports the following declarative data manipulation processes:

      • Select Automatic Row Fetch and Automatic Row Processing (DML) to create an automatic data manipulation language (DML) process.

      • Use Multi Row Update and Multi Row Delete with tabular forms.

      • Use Add Rows to Tabular Form with a tabular form.

      Web Services

      Implements a Web service as a process on a page. Running the process submits a request to the service provider.

      See Also: "Invoking a Web Service as a Process"

      Send E-Mail

      Provides a declarative interface for the APEX_MAIL.SEND_MAIL package. The process type support attachments.

  4. Follow the on-screen instructions.

8.5.2 Editing Page Process Attributes

Once you create a process, you can control when the process executes and what the process does by editing attributes on the Edit Page Process page.

To edit an existing page process:

  1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

  2. Access the Edit Page Process page:

    • Tree view - Under the appropriate page rendering event (such as Before Header, After Header and so on), locate the Processes section. Right-click and select Edit.

    • Component view - Under Processes, click the process name.

    The Edit Page Process page appears.

  3. Edit the appropriate attributes. For more information, see item Help and the sections that follow.

  4. Click Apply Changes.

8.5.3 Controlling When a Page Process Executes

You control when a process executes by specifying a sequence number and a process point under Process Point. You can prevent a process from running during subsequent visits to a page by selecting the options under Run Process.

To change the processing point or source:

  1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

  2. Access the Edit Page Process page:

    • Tree view - Under the appropriate page rendering event (such as Before Header, After Header and so on), locate the Processes section. Right-click and select Edit.

    • Component view - Under Processes, click the process name.

    The Edit Page Process page appears.

    You control when a process executes by specifying a sequence number and a process point under Process Point.

  3. Locate the section, Process Point.

  4. In Sequence, enter a number. The sequence determines the order of evaluation.

  5. From Process Point, select the point at which the process executes.

  6. You can prevent a process from running during subsequent visits to a page by selecting the following options under Run Process:

    • Once for each page visit

    • Once for each session or when reset

  7. Enter the appropriate code for PL/SQL process types.

    For PL/SQL anonymous block processes, enter the appropriate code under Process.

    For Clear Cache processes, enter the appropriate code under Source.

  8. Optionally define an error message. See "Creating Page Process Success and Error Messages".

  9. Click Apply Changes.

8.5.4 Creating Page Process Success and Error Messages

You can define both success and error messages that display when a process runs. How an error message displays depends upon the processing point. For processes with a processing point of On Submit - Before Computation and Validations or On Submit - After Computations and Validations, you can specify whether the error message displays inline on the current page (the default) or on a separate page. For all other page processes, error messages display on a separate error page.

To create a page process error or success message:

  1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

  2. Access the Edit Page Process page:

    • Tree view - Under the appropriate page rendering event (such as Before Header, After Header and so on), locate the Processes section. Right-click and select Edit.

    • Component view - Under Processes, click the process name.

    The Edit Page Process page appears.

  3. Scroll down to Messages.

  4. In Process Success Message, enter a message that displays when the process runs successfully.

  5. In Process Error Message, enter the message that displays when an unhandled exception is raised. See item Help for more details of supported substitution strings for both success and error messages.

  6. For processes with a processing point of On Submit - Before Computation and Validations or On Submit - After Computations and Validations, you can specify where the error message displays.

    From Error message display location, select one of the following:

    • Inline in Notification - Error displays inline with the existing page in the "notification" area (defined as part of the page template). This is the default setting for new processes.

    • On Error Page - Error displays on a separate error page.

      If the page contains a manually created tabular form (using APEX_ITEM calls in the SQL statement), select On Error Page. Otherwise, changes made by the user are discarded when the page is re-rendered. When errors are displayed on a separate error page, the user can use the browser's Back button to preserve the entered values.

  7. Click Apply Changes.

See Also:

"Page Templates"

8.5.5 Making a Page Process Conditional

To create a conditional page process:

  1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

  2. Access the Edit Page Process page:

    • Tree view - Under the appropriate page rendering event (such as Before Header, After Header and so on), locate the Processes section. Right-click and select Edit.

    • Component view - Under Processes, click the process name.

    The Edit Page Process page appears.

  3. Scroll down to Conditions.

  4. Under Condition, specify the following:

    1. When Button Pressed - Select a page button. If a user clicks the button you select, the validation is performed (that is, depending upon to other defined conditions). This validation is performed if the page is submitted by a means other than the clicking the specified button.

      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.

      • Expression Attributes - Depending upon the selected Condition Type, enter values in the Expression attributes.

      • Execute Condition - Applicable only to tabular forms. Select either:

        For Each Row - Select this option if you refer to tabular form columns in your condition. This option causes the condition to evaluate each row of the tabular form.

        Once - Select this option if you do not refer to tabular form specific values.

      The validation is rendered or processed if the specified condition is met.

  5. Click Apply Changes.