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).
Buttons can perform four 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, or do nothing (for example if the button's behavior is defined in a Dynamic Action).
You create a button by running the Create Button Wizard from the Page Definition. How you create a button depends upon whether the Page Definition is in tree or component view. To learn more, see "About Tree and Component View".
Component view groups user interface elements and application logic by component type. To create a button in Component view, under buttons and click the Create icon.
To create a region button in Component view:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
If necessary, create a region. See "Understanding Regions".
Under Buttons, click the Create icon.
Select a position for the button and click Next:
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).
For Button Attributes:
Button Name - Enter a name for this button. Note that 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 will have the purpose of resetting the current page without doing a submit.
Label - Enter a label to be displayed for the button.
Button Style - Available options:
HTML Button
Template Based Button
Image
If the button is an image, you need to supply an image name. If the button is template controlled, you need to select a template name.
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.
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.
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"
Click Next.
The options that display for Display Properties depend upon the selected region position.
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.
Show - Select one of the following:
Beginning on New Line - If selected, the button is drawn on a new line. If not selected, then the button is drawn in a new HTML table cell to the right of the previous field. If the button is the first field displayed, then the begin on new line check box should be selected.
Beginning on New Field - If selected, the button is drawn in its own cell. The cell will be below or to the right of the previous field. Select this option if the item is the first field in the region. If this check box is not selected, then the button is drawn within the cell of the previous item. Not selecting this option enables you to align the button to the right of a form text field.
Click Next.
For Action When Clicked:
Action - Select a behavior when the button is clicked:
Submit Page - Submits 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 properties for resetting pagination, setting the request value, clearing cache, and setting item values, on the target page.
Redirect to URL - Redirect to a target URL.
Defined by Dynamic Action - Does nothing. The button's behavior is defined by a Dynamic Action.
Download Printable Report Query - This creates a Submit Page button and also a corresponding branch. When the button is clicked, the output is downloaded from the Report Query.
Note that this action is only available if you have a report query defined in your application's Shared Components.
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.
Options include:
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. To learn more, see "Determining When Validations Execute".
Click Next.
For Conditional Display, select a condition type from the list that must be met in order for this component to be rendered.
Click Create Button.
Tree view displays regions, page items, and application logic as nodes in a tree. To create a button in Tree view, you select a region and then one of two options:
Create Region Button displays a button in a region position. For example, to add a button in a region position, as defined by the region template.
Create Page Item Button displays a button within or between button items. for example, use this option to place a button after a page item.
To create a region button in Tree view:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
If necessary, create region. See "Understanding Regions".
Right-click the region to contain the button and select one of the following:
Create Region Button - Displays a button in a region position. For example, to add a button in a region position, as defined by the region template.
Create Page Item Button - Displays a button within or between button items (for example, to place a button after a page item).
For Button Attributes:
Button Name - Enter a name for this button. Note that 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 will have the purpose of resetting the current page without doing a submit.
Label - Enter a label to be displayed for the button.
Button Style - Available options:
HTML Button
Template Based Button
Image
If the button is an image, you need to supply an image name. If the button is template controlled, you need to select a template name.
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.
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.
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"
Click Next.
The options that display for Display Properties depend upon the selected region position.
For Display Properties:
For Create Region Button:
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.
For Create Page Item Button:
Sequence - Enter the sequence for this component. The sequence determines the order of evaluation.
Show - Select one of the following:
Beginning on New Line - If selected, the button is drawn on a new line. If not selected, then the button is drawn in a new HTML table cell to the right of the previous field. If the button is the first field displayed, then the begin on new line check box should be selected.
Beginning on New Field - If selected, the button is drawn in its own cell. The cell will be below or to the right of the previous field. Select this option if the item is the first field in the region. If this check box is not selected, then the button is drawn within the cell of the previous item. Not checking this option, enables you to align the button to the right of a form text field.
Click Next.
For Action When Clicked:
Action - Select a behavior when the button is clicked:
Submit Page - Submits 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 properties for resetting pagination, setting the request value, clearing cache, and setting item values, on the target page.
Redirect to URL - Redirect to a target URL.
Defined by Dynamic Action - Does nothing. The button's behavior is defined by a Dynamic Action.
Download Printable Report Query - This creates a Submit Page button and also a corresponding branch. When the button is clicked, the output is downloaded from the Report Query.
Note that this action is only available if you have a report query defined in your application's Shared Components.
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.
Options include:
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. To learn more, see "Determining When Validations Execute".
Click Next.
For Conditional Display, select a condition type from the list that must be met in order for this component to be rendered.
Click Create Button.
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:
Navigate to the appropriate Page Definition in Component view. See "Switching Between Tree and Component View".
If necessary, create an HTML region. See "Understanding Regions".
In Component view, locate the Buttons section and click the Create icon.
The Create Button wizard appears.
Click the Create Multiple Buttons link.
The Create Multiple Button Wizard appears.
From Region, select the region to contain the buttons.
From Template, select a template. If no template is selected, buttons of style HTML will be created.
In HTML Attributes, specify HTML attributes for these buttons. This text will be added to the HTML element definition. For example, you could set the class of a text button as follows:
class="myclass"
To quickly populate the remaining fields, make a selection from the Quick Button list on the right side of the page.
Click Create Buttons.
When you want to edit a button, you start from the Buttons section on the Page Definition. You can edit the attributes of a button, edit multiple buttons at once, or change a button position within a region.
You can edit button attributes on the Edit Pages Buttons page.
To edit attributes for an existing button:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Page Buttons page:
Tree view- Under Page Rendering, double-click the button name.
Component view - Under Button, select the button name.
The Edit Page Buttons page appears.
To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".
Click Apply Changes.
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.
Options include:
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. To learn more, see "Determining When Validations Execute".
Use the Buttons page to delete multiple buttons or view a history of recent changes.
To edit multiple buttons at once:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Page Buttons page:
Tree view- Under Page Rendering, right-click the button name and select Edit All.
Component view - 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.
To delete multiple buttons at once:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Page Buttons page:
Tree view- Under Page Rendering, right-click the button name and select Edit All.
Component view - Click the Edit All icon. The Edit All icon resembles a small grid with a pencil on top of it.
The Buttons page appears.
Click Delete Multiple Buttons.
The Delete Multiple Buttons page appears.
Select the buttons to delete and click Remove Buttons.
In Component view, you can quickly edit a button label or change a button position within a region on the Reorder Buttons page. The Reorder Region Buttons icon resembles a light gray downward arrow and upward arrow and displays next to the region name.
To edit buttons using the Reorder Region Buttons icon:
Navigate to the appropriate Page Definition in Component view. See "Switching Between Tree and Component View".
Under Buttons, click the Reorder Region Buttons icon.
The Reorder Buttons page appears. Use this page to edit the button label, select a region position, or change the button order.
To edit the button label, enter a name in the Label field.
To change the region position, make a selection from the Position list.
To change the order in which buttons display, click the up and down arrows in the far right column.
Note that you can also control the order in which buttons display by editing the Sequence attribute. See "Editing Button Attributes".
Click Apply Changes.
Note:
To change the region where a button resides, you must edit the button attributes. See "Editing Button Attributes".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 will fail. For example:
<input type="BUTTON" value="Finish" onclick="apex.submit('Finish');">
Note that in this example Finish is the name of the REQUEST and this example is case-sensitive.
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 Application 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 will only be considered if a user clicks the button.
See Also:
"Controlling Navigation Using Branches"You can choose to have a button display conditionally by editing attributes on the Edit Pages Button page.
To have a button display conditionally:
Create the button. See "Creating a Button Using a Wizard".
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Page Buttons page:
Tree view- Under Page Rendering, locate the button and double-click the button name.
Component view - Under Buttons, click the button name.
Scroll down to Conditions.
Make a selection from the Condition Type list.
Enter an expression in the fields provided.
Click Apply Changes.
See Also:
"About Bind Variable Syntax"