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.
• About Branching with Buttons
  Learn about branching with buttons.
• Creating a Button
  Create buttons in Page Designer.
• 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.
• Editing a Button
  Edit buttons in Page Designer.
• Displaying a Button as a Menu
  Display a button as a menu by editing button attributes.
• Hiding a Button or Displaying It as Disabled
  Learn how to hide a button.
• 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.
• Avoiding Multiple Page Submits by Enabling Show Processing
  Prevent users from double-clicking a button by enabling the Show Processing attribute.
• Adding a Trigger Action to a Button
  Define a dynamic action directly beneath a button by creating a Trigger Action.
• 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.

• Trigger Action - The button's behavior is defined by one or more Trigger Actions. Does not submit the page or redirect to another page.

• 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 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.3 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, select App Builder.
   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.

13.3.4 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.5 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, select App Builder.
   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.6 Displaying a Button as a Menu

Display a button as a menu by editing button attributes.

By default, when you create a button, the Type attribute in the Property Editor is set to Standard. You can display a button as a menu by changing the Type attribute to Menu.

This task describes how to edit an existing button to display as a menu and define menu entries to link to other pages in the application. Then, this task explores some of the attributes that change how the button displays, including hiding a menu entry, adding a separator, hiding the menu, and changing the button template. The follow example assumes you have already created an application with three report pages built on the built on the Project Data sample dataset.

Note:

Many of the attributes described in this topic require Universal Theme 25.1. If your application is from an older release or if the button templates have modified manually, these options and behaviors described in this topic may not be available. To learn more, about updating the theme in an existing application, see About Updating or Migrating to the Universal Theme.

To display a button as a menu:

1. View the page in Page Designer:
   1. On the Workspace home page, select App Builder.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Name the button and change the button Type:
   1. 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.

   2. Identification, Button Name - Enter a button name (for example, VIEW_PROJECTS).

      Note that the Label attribute is populated automatically.

   3. Behavior, Type - Select Menu.

      A menu entry named New appears under Menus.

      
      

      
      Description of the illustration view_projects_button_menu.png

      
      
3. Edit the menu entry and create a link to another page in the current application:
   1. In the Rendering tab, select the New menu entry.

      The Property Editor displays Menu attributes in the right pane.

   2. Identification, Label - Enter the text to display on the menu entry (for example, All Projects).
   3. Link, Type - Select the action to perform when the menu is clicked. For this example, select Redirect to Page in this Application.
   4. Link, Target - Create a link to another page:
      • Find Link and click No Link Defined.

        The Link Builder - Target dialog appears.

      • Target, Page - Click the List of Values and select a page (for example, 2 All Projects).
   5. Click OK.
4. Add a second menu entry:
   1. In the Rendering tab, right-click Menus and select Create Menu.

      A Menu Entry named New appears under Menus.

   2. In the Rendering tab, select the New menu entry.

      The Property Editor displays Menu attributes in the right pane.

   3. Identification, Label - Enter the text to display on the menu entry (for example, Project Tasks).
   4. Link, Type - Select the action to perform when the menu is clicked. For this example, select Redirect to Page in this Application.
   5. Link, Target - Create a link to another page:

      • Find Link and click No Link Defined.

        The Link Builder - Target dialog appears.

      • Target, Page - Click the List of Values and select a page (for example, (for example, 4 Project Tasks).
   6. Click OK.
5. Add a third menu entry:
   1. In the Rendering tab, right-click Menus and select Create Menu.

      A Menu Entry named New appears under Menus.

   2. In the Rendering tab, select the New menu entry.

      The Property Editor displays Menu attributes in the right pane.

   3. Identification, Label - Enter the text to display on the menu entry (for example, Project Milestones).
   4. Link, Type - Select the action to perform when the menu is clicked. For this example, select Redirect to Page in this Application.
   5. Link, Target - Create a link to another page:

      • Find Link and click No Link Defined.

        The Link Builder - Target dialog appears.

      • Target, Page - Click the List of Values and select a page (for example, (for example, 6 Project Milestones).
   6. Click OK.

   Tip:

   You can also add an icon to a menu entry by configuring the Appearance, Icon attribute.
6. View the new menu:
   1. Click Save and Run page.
   2. Click the new button and test it.
      The following example shows a button named View Projects with three menu entries.

      
      

      
      Description of the illustration new_button_menu.png

      
      
   3. Return to Page Designer. Click Page X on the Developer toolbar where X is the page number.
7. Hide a menu entry:
   1. In the Rendering tab, right-click a menu entry and select Comment Out.

      In Page Designer, the menu entry displays with a strikethrough.

   2. Click Save and Run page.

      Note the menu entry no longer displays.

   3. Unhide the menu entry. In the Rendering tab, right-click the menu entry and select Uncomment.

   Tip:

   To learn more see, Commenting Out Page Components in Page Designer.
8. Add a separator between menu entries:
   1. In the Rendering tab, right-click the first menu entry and select Create Menu.
   2. In the Rendering tab, select the New menu entry.

      The Property Editor displays Menu attributes in the right pane.

   3. Identification, Type - Select Separator.
   4. Repeat the previous steps add a separator between the second and third menu entry.

      Tip:

      You can also right-click the existing separator and select Duplicate and then move it the appropriate location.
   5. Click Save and Run page.

      Note that separators are added between the menu entries.

   6. Return to Page Designer. Click Page X on the Developer toolbar where X is the page number.
9. Change how the menu by editing Appearance attributes:
   1. In the Rendering tab, select the button (for example, VIEW_PROJECTS).

      The Property Editor displays Menu attributes in the right pane.

   2. Appearance, Button Template - Select Icon.
   3. Click Save and Run page.

      The View Projects button now displays as an icon with menu entries.

13.3.7 Hiding a Button or Displaying It as Disabled

Learn how to hide a button.

Note:

Some of the attributes described in this topic require Universal Theme 25.1. If your application is from an older release or if the button templates have modified manually, these options and behaviors described in this topic may not be available. To learn more, about updating the theme in an existing application, see About Updating or Migrating to the Universal Theme.

To hide a button or a display it as disabled:

1. View the page in Page Designer:
   1. On the Workspace home page, select App Builder.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Hide the button by editing the Server-side Condition attribute:
   1. In the Rendering tab, select the button.

      The Property Editor displays attributes in the right pane.

   2. Server-side Condition, Type - Select Never.

      In Page Designer, the button displays with a strikethrough.

   3. Click Save and Run page.

      The button no longer displays.

   4. Return to Page Designer. Click Page X on the Developer toolbar where X is the page number.

   Tip:

   You can also hide a button using the Comment Out option. Simply right-click the button and select Comment Out. To learn more see, Commenting Out Page Components in Page Designer.
3. Display the button but show it as disabled.

   To show a button as disabled, set Server-side Condition to Never as described in the previous step and enable the Show as Disabled switch.

   1. In the Rendering tab, select the button.

      The Property Editor displays attributes in the right pane.

   2. Appearance, Show as Disabled - Enabled the Show as Disabled switch.
   3. Click Save and Run page.

      The button again displays but is disabled.

13.3.8 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, select App Builder.
   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.

3. Configure the Server-side Condition:
   1. 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.
   2. 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.

13.3.9 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, select App Builder.
   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.

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.10 Avoiding Multiple Page Submits by Enabling Show Processing

Prevent users from double-clicking a button by enabling the Show Processing attribute.

The Show Processing attribute is useful if you have a slow process and provides feedback to the user that the button has already been clicked. Enabling Show Processing grays out the page and displays a processing style animation when the page is submitted.

To enable the Show Processing attribute, the button Action must be Submit Page.

To enable Show Processing:

1. View the page in Page Designer:
   1. On the Workspace home page, select App Builder.
   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.

3. Behavior - Configure the attributes:
   1. Behavior, Action - Select Submit Page.
   2. Behavior, Show Processing - Enable this attribute to gray out the page and display a processing style animation during page submission. This attribute is useful to prevent end user action during long running operations.
4. To save your changes click Save. To save and run the page, click Save and Run Page.

13.3.11 Adding a Trigger Action to a Button

Define a dynamic action directly beneath a button by creating a Trigger Action.

Trigger Actions enable you to define a dynamic action, action directly beneath the button in the Page Designer tree. To define a Trigger Action, edit the button attributes and change Behavior, Type to Trigger Action.

The following topic assumes you have already created a button.

To create a button Trigger Action:

1. View the page in Page Designer:
   1. On the Workspace home page, select App Builder.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Select the button and change the button Type:
   1. 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.

   2. Behavior, Type - Select Trigger Action.

      An Execute Server-side Code action is created under the button in the Rendering tab.

3. Select Execute Server-side Code.

   The Property Editor displays Trigger Action attributes in the right pane.

4. Edit the Trigger Action attributes in the Property Editor.

   Note:

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

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

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.