13.3 Managing Buttons

You can use buttons to direct users to a specific page or URL, or to post or process information (for example, by creating Create, Cancel, Next, Previous, or Delete buttons). You can also configure buttons to display conditionally or warn users of unsaved changes.

• About Actions Buttons Can Perform
  Use buttons to submit a page or redirect to a different page or different URL.
• Creating a Button
  Create buttons in Page Designer.
• Editing a Button
  Edit buttons in Page Designer.
• About Branching with Buttons
  Learn about branching with buttons.
• About the Relationship Between Button Names and REQUEST
  The name you give a Submit button (that is, a button with an Action of Submit Page) determines the value of the built-in attribute REQUEST when the page is submitted.
• Displaying a Button Conditionally
  You can choose to have a button display conditionally by editing the Server-side Condition attribute in Page Designer.
• Configuring Button Attributes to Warn Users of Unsaved Changes
  Use the Warn on Unsaved Changes attribute to warn users of unsaved changes when they attempt to navigate away from a page.
• Displaying a Button Confirmation Dialog
  Display a Confirmation dialog after the button is clicked by enabling the Requires Confirmation attribute.

See Also:

Calling a Page from a Button URL and Accessing Page Specific Utilities

13.3.1 About Actions Buttons Can Perform

Use buttons to submit a page or redirect to a different page or different URL.

The Behavior, Action attribute determines the action to be performed when a button is clicked. Available options include:

• Submit Page - Submit the current page with a REQUEST value equal to the Button Name.

• Redirect to Page in this Application - Redirect to a page in the current application with optional additional attributes for resetting pagination, setting the request value, clearing cache, and setting item values on the target page.

• Redirect to Page in a different Application - Redirect to a page in a different application with optional additional attributes for resetting pagination, setting the request value, clearing cache, and setting item values, on the target page.

  Note:

  Redirecting to a page in different application relies on deep linking being enabled in the target application. To enable deep linking, go to the application's Security attributes and enable Deep Linking.

• Redirect to URL - Redirect to the target URL you specify.

• Defined by Dynamic Action - Does not submit the page or redirect to another page. Instead the button's behavior is defined by a Dynamic Action.

13.3.2 Creating a Button

Create buttons in Page Designer.

To create a button 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. If necessary, create a region to contain the item.
3. In the Gallery, click the Buttons tab.

   Passing the cursor over a button displays a tooltip that describes it.

4. Right-click the button, select Add To, and select the appropriate location.

   Tip:

   You also select the button with the mouse and drag it to the appropriate location in the Layout tab.

   The Property Editor displays button attributes in the right pane. Attributes are organized in groups.

   To find a group or attribute:

   • Search for a group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

5. Edit the appropriate attributes in the Property Editor.

   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:

About Regions

13.3.3 Editing a Button

Edit buttons in Page Designer.

To edit a region button 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. In either the Rendering tab or the Layout tab, select the button to edit.

   The Property Editor displays button attributes in the right pane. Attributes are organized in groups.

   To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

3. Edit the button attributes.

   Note:

   To view help for an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

4. Click Save.

13.3.4 About Branching with Buttons

Learn about branching with buttons.

Each page can include any number of branches. A branch links to another page in your application or to a URL. The Oracle APEX engine considers branching at different times during page processing. You can choose to branch before processing, before computation, before validation, and after processing. Like any other control in App Builder, branching can be conditional. For example, you can branch when a user clicks a button. When you create a branch, you associate it with a specific button. The branch is only be considered if a user clicks the button.

See Also:

Controlling Navigation Using Branches

13.3.5 About the Relationship Between Button Names and REQUEST

The name you give a Submit button (that is, a button with an Action of Submit Page) determines the value of the built-in attribute REQUEST when the page is submitted.

You can reference the value of REQUEST from within PL/SQL using the bind variable :REQUEST. By using this bind variable, you can conditionally process, validate, or branch based on which button the user clicks. You can also create processes that execute when the user clicks a button. And you can use a more complex condition as demonstrated in the following examples:

If :REQUEST in ('EDIT','DELETE') then ...
If :REQUEST != 'DELETE' then ...

These examples assume the existence of buttons named EDIT and DELETE. You can also use this syntax in PL/SQL Expression conditions. Be aware, however, that the button name capitalization (case) is preserved. In other words, if you name a button LOGIN, then a request looking for the name Login fails. For example:

<input type="BUTTON" value="Finish" onclick="apex.submit('Finish');">

In this example Finish is the name of the REQUEST and this example is case-sensitive.

13.3.6 Displaying a Button Conditionally

You can choose to have a button display conditionally by editing the Server-side Condition attribute in Page Designer.

To have a button display conditionally:

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. In either the Rendering tab or the Layout tab, select the button to edit.

   The Property Editor displays button attributes in the right pane. Attributes are organized in groups.

   To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

3. Configure the Server-side Condition:
   1. Find the Server-side Condition group.
   2. Server-side Condition, Type - Select a condition type that must be met in order for this component to be rendered or processed. What displays next, depends upon selected Type.
      What displays next, depends upon the Server-side Condition, Type you select.
   3. Configure the remaining attributes.

      Tip:

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

4. Click Save.

See Also:

Referencing Session State Using Bind Variable Syntax

13.3.7 Configuring Button Attributes to Warn Users of Unsaved Changes

Use the Warn on Unsaved Changes attribute to warn users of unsaved changes when they attempt to navigate away from a page.

To configure the Warn on Unsaved Changes attribute:

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. In either the Rendering tab or the Layout tab, select the button to edit.

   The Property Editor displays button attributes in the right pane. Attributes are organized in groups.

   To find a group or attribute:

   • Search for a group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

3. Behavior, Warn on Unsaved Changes - Select one of the following:
   • Page Default - Check for unsaved changes when the button is clicked if Warn on Unsaved Changes is enabled at page level.
   • Do Not Check - The unsaved changes check will not be performed when the button is clicked. Use this setting for Cancel, Delete, and Apply Changes buttons.
4. Click Save.

Tip:

The Warn on Unsaved Changes attribute is implemented using the apex.page.warnOnUnsavedChanges API.

See Also:

Configuring Pages to Warn Users of Unsaved Changes and warnOnUnsavedChanges in Oracle APEX JavaScript API Reference

13.3.8 Displaying a Button Confirmation Dialog

Display a Confirmation dialog after the button is clicked by enabling the Requires Confirmation attribute.

Enabling the Requires Confirmation attribute displays a confirmation dialog after a button is clicked. The button action, whether it be it to submit the page, to redirect to another page, or to invoke a dynamic action, will be delayed until the user has confirmed the action. If the user cancels, the action will not be performed. You can configure the dialog message and apply style options such as Information, Warning, Danger, or Success. The dialog's Confirm button label will match the actual button label.

To display a button confirmation dialog:

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. In either the Rendering tab or the Layout tab, select the button to edit.

   The Property Editor displays button attributes in the right pane. Attributes are organized in groups.

   To find a group or attribute:

   • Search for a group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

3. Behavior, Requires Confirmation - Enable this attribute.
   The Confirmation group appears.
4. Configure the attributes under Confirmation:
   1. Confirmation, Message - Enter the message to be displayed in the confirmation dialog. This attribute supports substitutions (application, page items, or system variables).
   2. Confirmation, Style - Select a style for the dialog. Options include:

      • Default

      • Information

      • Warning

      • Danger

      • Success

5. Click Save.