17.3 Understanding Page Processes

This section describes how to create a page process.

17.3.1 About 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.

See Also:

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

17.3.2 Managing Page Processes in Page Designer

This section describes how to create a page process.

See Also:

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

Tip:

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

17.3.2.1 Creating Page Processes in Page Designer

To create a page process:

  1. View the page in Page Designer. See "Viewing a Page in Page Designer."

  2. In either the Rendering or Processing tab, locate the node where the process will occur. Right-click and select Create Process.

    Process attributes display in the Property Editor.

    Tip:

    The Messages tab displays a red or yellow badge to identify messages you need to address. Selecting a message displays the associated attribute in the Property Editor. You must address red error message before you can save.

  3. View all attributes in the Property Editor. Select Show All from the Property Editor Menu.

    Tip:

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

  4. Under Identification:

    1. Name - Enter the name of the process.

    2. Type - Specify which process type to execute. The Type you select determines what Setting attributes display.

  5. Under Settings, edit the appropriate attributes.

    Required attributes display a red triangle in the upper left corner next above attribute label.

  6. Under Execution Options:

    1. Sequence - Specify the sequence for this computation. The sequence determines the order of execution.

    2. Point - Select the point at which this process is executed.

    3. Run Process - Select the frequency that this process is executed.

  7. Under Success Message:

    1. Error Message - Enter the success message for this process. If the process runs and does not generate an error, then this process success message displays in the notification section of the resulting page displayed.

  8. Under Error:

    1. Error Message - Enter the error message for this process. This message displays if an unhandled exception is raised. After any error processing stops, a rollback is issued and an error message displays.

    2. Display Location - Select where this process error message displays, when the process fails to complete successfully.

  9. Click Save.

See Also:

"Creating Pre-Rendering Branches, Computations, and Processes" and "Creating Page Submission Branches, Validations, Computations, and Processes"

17.3.2.2 Editing Page Process Attributes in Page Designer

To edit an existing page process:

  1. View the page in Page Designer. See "Viewing a Page in Page Designer."

  2. In either the Rendering or Processing tab, expand the nodes to locate the process and then select it.

    Process attributes display in the Property Editor.

  3. View all attributes in the Property Editor. Select Show All from the Property Editor Menu.

  4. Under Property Editor - Process, 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.

17.3.2.3 Controlling When a Page Process Executes in Page Designer

To control when a process executes, edit the following attributes:

  1. View the process attributes in the Property Editor. See "Editing Page Process Attributes in Page Designer."

  2. Edit the following attributes:

    1. Execution Options, Sequence - Specify the sequence for this component. The sequence determines the order of execution.

    2. Execution Options, Point - Select the point in the processing at which this branch action is considered.

  3. Click Save.

17.3.2.4 Creating Page Process Success and Error Messages in Page Designer

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. View the process attributes in the Property Editor. See "Editing Page Process Attributes in Page Designer."

  2. Edit the following attributes:

    1. Success Message, Success Message - Enter the success message for this process. If the process runs and does not generate an error, then this process success message displays in the notification section of the resulting page displayed. If you are branching to another page via a URL redirect, you may need to check the preserve success message attribute.

    2. Error, Error Message - Enter the error message for this process. This message displays if an unhandled exception is raised. After any error processing stops, a rollback is issued and an error message displays.

    3. Error, Display Location - Select where this process error message displays, when the process fails to complete successfully.

      Option include:

      • Inline in Notification - The process error message displays in the Notification area (defined as part of the page template).

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

  3. Click Save.

See Also:

"Page Templates"

17.3.2.5 Making a Page Process Conditional in Page Designer

To create a conditional page process, edit the following attributes:

  1. View the process attributes in the Property Editor. See "Editing Page Process Attributes in Page Designer."

  2. Edit the following attributes:

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

    2. Condition, 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, Condition Type - Select a condition type from the list that must be met in order for this component to be rendered or processed.

  3. Click Save.

17.3.3 Managing Page Processes in Component View

This section describes how to create a page process.

See Also:

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

Tip:

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

17.3.3.1 Creating Page Processes in Component View

This section describes how to create 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.

17.3.3.1.1 Creating a Page Process

To create a page process:

  1. Navigate to the appropriate page. See "Viewing a Page in Component View."

  2. Access the Create Page Process Wizard. Under Processes, click the Create icon.

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

    Table 17-3 Page Process Types

    Process Category Description

    Clear Session State

    Clears session state stored within Oracle Application Express. 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

    Close Dialog

    Closes the current modal or non-modal dialog page.

    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.

    Form Pagination

    Process to retrieve the previous or next record from a database table or view. This process can be used to provide pagination on Form pages, so that end users can retrieve the previous or next record without navigating back to a report.

    PL/SQL Code

    Process to execute PL/SQL code 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."

    Reset Pagination

    Process to reset pagination of reports on the current page.

    Send E-Mail

    Process to send an email and optionally one or more attachments from the application.

    User Preferences

    Process to set User Preferences for the end user.

    See Also: "Managing User Preferences" in Oracle Application Express Administration Guide

    Web Services

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

    See Also: "How to Invoke a Web Service as a Process."

  4. Follow the on-screen instructions.

17.3.3.1.2 Creating a Tabular Form Page Process

To create a tabular form page process:

  1. Navigate to the appropriate page. See "Viewing a Page in Component View."

  2. Access the Create Page Process Wizard. Under Processes, click the Create icon.

  3. For Process Type:

    • Tabular Form - Select the associated tabular form region.

    • Process type - Select a process type as described in Table 17-4:

      Table 17-4 Page Process Types

      Process Category Description

      Clear Session State

      Clears session state stored within Oracle Application Express. 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

      Close Dialog

      Closes the current modal or non-modal dialog page.

      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.

      Form Pagination

      Process to retrieve the previous or next record from a database table or view. This process can be used to provide pagination on Form pages, so that end users can retrieve the previous or next record without navigating back to a report.

      PL/SQL Code

      Process to execute PL/SQL code 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."

      Reset Pagination

      Process to reset pagination of reports on the current page.

      Send E-Mail

      Process to send an email and optionally one or more attachments from the application.

      User Preferences

      Process to set User Preferences for the end user.

      See Also: "Managing User Preferences" in Oracle Application Express Administration Guide

      Web Services

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

      See Also: "How to Invoke a Web Service as a Process."

  4. Follow the on-screen instructions.

17.3.3.2 Editing Page Process Attributes in Component View

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. See "Viewing a Page in Component View."

  2. Access the Edit Page Process page. Under Processes, click the process name.

    The Edit Page Process page appears.

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

  4. Click Apply Changes.

17.3.3.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 on the Edit Page Process page. You can prevent a process from running during subsequent visits to a page by selecting the options under Run Process.

To control when a process executes:

  1. Access the Edit Page Process page. See "Editing Page Process Attributes in Component View."

  2. Edit the following attributes:

    1. Processing Point, Sequence - Specify the sequence for this component. The sequence determines the order of execution.

    2. Processing Point, Process Point - Select the point in the processing at which this branch action is considered.

    3. Processing Point, Run Process - Select how often this process executes.

  3. Click Apply Changes.

17.3.3.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. Access the Edit Page Process page. See "Editing Page Process Attributes in Component View."

  2. Edit the following attributes:

    1. Messages, Process Success Message - Enter a message that displays when the process runs successfully.

    2. Messages, Process Error Message - Enter the message that displays when an unhandled exception is raised. See field-level Help for more details of supported substitution strings for both success and error messages.

    3. Messages, Error message display location - Identifies where the process error message displays. Process error messages can display on an error page, or inline with the existing page in the "notification" area (defined as part of the page template).

  3. Click Apply Changes.

See Also:

"Page Templates"

17.3.3.5 Making a Page Process Conditional

To create a conditional page process:

  1. Access the Edit Page Process page. See "Editing Page Process Attributes in Component View."

  2. Edit the following attributes:

    1. Conditions, 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. Conditions, 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. Conditions, Condition Type - Select a condition type from the list that must be met in order for this component to be rendered processed.

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

  3. Click Apply Changes.