13.5 Creating Buttons

As you design your application, 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).

13.5.1 What Actions Can a Button Perform?

Buttons can perform different types of actions. A button can:

  • Submit a page (for example to save changes to a form page)

  • Redirect to either a different page or a custom URL

  • Do nothing (for example if the button's behavior is defined in a Dynamic Action).

13.5.2 Managing Buttons in Page Designer

This section describes how to manage buttons in Page Designer.

13.5.2.1 Creating a Button 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.

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

  8. Click Save.

See Also:

"About Regions"

13.5.2.2 Editing a Button in Page Designer

To create 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 the button attributes in the right pane.

    Property Editor organizes attributes into functional groups. To expand or collapse these groups, click the Show Common, Show All, Collapse All, and Expand All icons.

  3. To search for an attribute, enter a keyword in the Filter Properties field.

    The attribute appears.

  4. Edit the button attributes.

    Edited attributes display a blue marker to the left of the attribute name until the page is saved.

    Note:

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

  5. Click Save.

13.5.2.3 Displaying a Button Conditionally

You can choose to have a button display conditionally by editing attributes on the Edit Pages Button page.

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 changes to display Button attributes.

    Attributes are organized into functional groups. To expand or collapse these groups, click the Show CommonShow AllCollapse All, and Expand All icons.

  3. To search for a group or an attribute, enter a keyword in the Filter Properties field.
  4. Locate and expand Server-side Condition. Select a Type and enter appropriate information in the field provided.

    Tip:

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

  5. Click Save.

13.5.2.4 Configuring Button Attributes to Warn Users of Unsaved Changes

Developers can use the Warn on Unsaved Changes button attribute to warn users of unsaved changes when they attempt to navigate away from the page by clicking the button.

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 changes to display button attributes.

  3. Locate and expand Behavior.

    Tip:

    To search for an attribute, enter a keyword in the Filter Properties field. The attribute appears.

  4. For 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.

  5. Click Save.

Tip:

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

13.5.3 Managing Buttons in Legacy Component View

Developers create and edit buttons in Component View.

13.5.3.1 Creating a Button in Component View

To create a region button in Component View:

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

  2. If necessary, create a region. See "About Regions."

  3. Under Buttons, click the Create icon.

  4. On Button Region, select a region for the button and click Next.

  5. On Button Position:

    1. Position - Select a position for the button:

      • Create a button in a region position - Select this option to place the button in a region position. A region position is a position defined by a region template.

      • Create a button displayed among this region's items - Select this option to display the button within or between page items (for example, to add a button directly to the right of a form field).

    2. Click Next.

  6. For Button Attributes:

    Tip:

    To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

    1. Button Name - Enter a name for this button. For buttons with an action of Submit Page, the button name becomes the page request value. For example, if you name the button FLOW_RESET_BUTTON, then the button has purpose of resetting the current page without doing a submit).

    2. Label - Enter a label to be displayed for the button.

    3. Button Template - Define which template controls the display of the button. Button templates are defined on the templates page. You must have at least one button template defined to use button templates.

    4. Button Type - Use this attribute to select either the Normal or Hot template of the button template.

      If you select Hot, the button is rendered using the template stored in the Hot Template attribute of a button template. If no value is defined, the regular button template is used.

    5. Button Attributes - Text entered is added to the HTML element definition. The following example sets the class of a text button:

      class="myclass"
      

      For buttons based on templates, your template must include the #BUTTON_ATTRIBUTES# substitution string. You can use this to control tab stops. For example:

      tabindex="3"
      
    6. Click Next.

    Display Properties appears. The options that display for Display Properties depend upon the selected region position.

  7. For Display Properties:

    • If the button position is Create a button in a region position:

      • Sequence - Enter the sequence for this component. The sequence determines the order of evaluation.

      • Position - Select a position for this button.

      • Alignment - Select Right or Left.

      • Click Next.

    • If the button position is Create a button displayed among this region's items:

      • Sequence - Enter the sequence for this component. The sequence determines the order of evaluation.

      • Click Next.

  8. For Action When Clicked:

    1. Tip:

      To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

      Action - Select a behavior when the button is clicked.

    2. Execute Validations - Execute Validations controls the execution of validations when a page is submitted. For example, this is useful for a Delete button where you do not want to annoy the user with irrelevant validation error messages when they are deleting a record.

      To have a specific validation always execute independent of this setting, set the validation attribute, Always Execute, to Yes. To learn more, see "About Determining When Validations Execute."

    3. Click Next.

  9. For Conditional Display, select a condition type from the list that must be met in order for this component to be rendered.

  10. Click Create Button.

13.5.3.2 Creating Multiple Buttons in Component View

In Component View, you can create multiple Submit Page buttons within the same region at once using the Create Multiple Buttons Wizard.

To create multiple buttons at once:

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. If necessary, create a region. See "About Regions."
  3. In Component View, locate the Buttons section and click the Create icon.

    The Create Button wizard appears.

  4. Click the Create Multiple Buttons link.

    The Create Multiple Button Wizard appears.

  5. From Region, select the region to contain the buttons.
  6. From Template, select a template. If no template is selected, buttons of style HTML are created.
  7. In HTML Attributes, specify HTML attributes for these buttons. This text is added to the HTML element definition. For example, you could set the class of a text button as follows:
    class="myclass"
    
  8. To quickly populate the remaining fields, make a selection from the Quick Button list on the right side of the page.
  9. Click Create Buttons.

13.5.3.3 Editing a Button in Legacy Component View

Developers can edit a button in Component View.

13.5.3.3.1 Editing Button Attributes

To edit attributes for an existing button:

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. Under Button, select the button name.
  3. Edit the button attributes.

    To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

  4. Click Apply Changes.

13.5.3.3.2 About Execute Validations

The Action When Button Click, Execute Validations attribute on the Edit Page Buttons page controls the execution of validations when a page is submitted. For example, this is useful for a Delete button where you do not want to annoy the user with irrelevant validation error messages when they are deleting a record.

For Execute Validations, you can select:

  • Yes - If the page is submitted and this attribute is set to Yes, all validations defined for the page and all built-in validations execute (for example to check for a required value or to determine if the value is a valid number or date).

  • No - If set to No, none of the defined validations or the built-in validations execute.

To have a specific validation always execute independent of this setting, set the validation attribute, Always Execute, to Yes.

13.5.3.3.3 Editing Multiple Buttons at Once

Use the Buttons page to delete multiple buttons or view a history of recent changes.

To edit multiple buttons at once:

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. Under Buttons, click the Edit All icon. The Edit All icon resembles a small grid with a pencil on top of it.

    The Buttons page appears. The Buttons page contains a table listing the buttons in the region.

  3. Edit the attributes and click Apply Changes.
13.5.3.3.3.1 Deleting Multiple Buttons

To delete multiple buttons at once:

  1. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  2. Under Buttons, click the Edit All icon. The Edit All icon resembles a small grid with a pencil on top of it.

    The Buttons page appears. The Buttons page contains a table listing the buttons in the region.

  3. Click Delete Multiple Buttons.

    The Delete Multiple Buttons page appears.

  4. Select the buttons to delete and click Remove Buttons.
13.5.3.3.3.2 History

Use the History page to view a summary of recent edits to buttons.

13.5.3.4 Displaying a Button Conditionally

You can choose to have a button display conditionally by editing attributes on the Edit Pages Button page.

To have a button display conditionally:

  1. Create the button. See "Creating a Button in Component View".
  2. Navigate to the appropriate page. See "Viewing a Page in Legacy Component View."
  3. Under Buttons, click the button name.
  4. Scroll down to Conditions.
  5. Make a selection from the Condition Type list.
  6. Enter an expression in the fields provided.
  7. Click Apply Changes.

13.5.4 About Calling JavaScript from a Button

Calling JavaScript from a button is a great way to confirm a request. Oracle Application Express uses this technique for the delete operation of most objects. For example, when you delete a button, a JavaScript message appears asking you to confirm your request. Consider the following example:

  function deleteConfirm(msg)
  {
var confDel = msg;
if(confDel ==null)
  confDel= confirm("Would you like to perform this delete action?");
else
  confDel= confirm(msg);
  
if (confDel== true)
  doSubmit('Delete');
  }

This example creates a function to confirm a delete action and then calls that function from a button. Note that the function optionally submits the page and sets the value of the internal variable :REQUEST to Delete, thus performing the deletion using a process that conditionally executes based on the value of the request.

When you create the button, you must select Redirect to URL. Then, you would specify a URL target such as the following:

javascript:confirmDelete('Would you like to perform this delete action?');

Oracle recommends using dynamic actions as the preferred way of executing JavaScript code. Consider the following example:

  1. Create a button with action of Defined by Dynamic Action. See "Creating a Button in Component View."

  2. Create a dynamic action and using the action type Execute JavaScript Code to execute the previous code, for example:

    if (confirm("Would you like to perform this delete action?")) {
      apex.submit('Delete');
    }
    

This example uses JavaScript, but you could also easily implement this example without having to use JavaScript. Instead, you can use the declarative actions Confirm and Submit Page which are also translatable. To learn more, see "Managing Dynamic Actions."

13.5.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 submits. 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.5.6 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 Application Express 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.