This section provides an overview of dynamic actions and explains how to create and modify them.
See Also:
"About Page Specific Utilities"Dynamic actions provide a way to define complex client-side behavior declaratively without the need for JavaScript. Using the Dynamic Action Create wizard, you specify an action that is performed when a defined set of conditions occur. You can also specify which elements are affected by the action, and when and how they are affected.
When working with dynamic actions, you should be mindful of the fact that the more dynamic actions you add to a page, the greater your overall page size will be. This is because the dynamic action framework emits additional code to the client for each dynamic action defined, which then also must be downloaded and executed by the framework in the client. Please see "Debugging Dynamic Actions" for information on how to debug problems.
The process of implementing a dynamic action involves the following:
Edit or create an item, button, region, DOM object, or jQuery selector on a page. This component is referenced within the dynamic action in defining when it fires.
Create a dynamic action from the application page that invokes the action.
Run your application to test the dynamic action.
For Dynamic Action implementation examples, go to the Learning Library at the following location, click the All Content tab and enter search criteria for Application Express (APEX) Product OBEs:
http://www.oracle.com/technetwork/tutorials/index.html
Creating a Dynamic Action involves specifying when the action will happen (with optional conditions), what action or actions are performed, and what elements are affected by the action.
Standard dynamic actions are used for simple actions that show, hide, enable, and disable page elements when a page item's value changes
To create a standard dynamic action:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Create Dynamic Action Wizard:
Tree view - Under Page Rendering, locate Dynamic Actions. Right-click and select Create.
You can also invoke the wizard by right-clicking on a specific page item or region that you want to be the trigger for the dynamic action. This makes definition faster because certain When values will be pre-filled
Component view - Under Page Rendering, scroll down to Dynamic Actions and click the Create icon.
For Implementation, select Standard and click Next.
For Identification, enter the following and click Next.
Name - Enter the name of the dynamic action.
Sequence - Enter the sequence of this component. The sequence determines the order of evaluation.
For When, specify when the action is performed and click Next. Available options include:
Selection Type - Select the type of page element that triggers the dynamic action. A corresponding name field displays to specify the name of the page element.
Note:
Only available if the event selected supports definition of a page element. Selecting any of the following events will hide this field: Page Load, Page Unload, Resize, Before Page Submit. All other event types show this field.Item(s), Button, Region, DOM Object, or jQuery Selector - Specify the name of the page element as follows:
Item(s) - Enter or select one or more page item names that trigger the dynamic action. For multiple items, please separate page items with a comma.
Button - Select the button that will trigger the dynamic action. If the button is a Template button, the button selected must use a button template that includes an ID attribute set to #BUTTON_ID#. The dynamic action framework relies on this ID value to reference the button.
Region - Select the region name that triggers the dynamic action. The region selected must use a region template that includes a container element with an ID attribute set to #REGION_STATIC_ID#. The dynamic action framework relies on this ID value to reference the region.
The region can fire the event itself, such as in the case of Before Refresh or After Refresh events, or can be a container to catch events that fire on items or other elements in the region. Only the following subset of events support this: Change (change), Click (click), Double Click (dblclick), Get Focus (focus), Key Down (keydown), Key Press, Key Release (keyup), Lose Focus (blur), Mouse Button Press (mousedown), Mouse Button Release (mouseup), Mouse Move (mousemove).
DOM Object - Enter either the Document Object Model (DOM) object or the ID of a DOM object that triggers the dynamic action.
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that trigger the dynamic action.
Condition - To conditionalize the trigger, make a selection from the Condition Type list and enter text in the Value field. Based on whether this condition is met, it is possible to define both True (when it is met) and False (when it is not) actions. If No Condition is specified, only True actions will fire. For further information, see the item level Help.
For True/False specify the True Action that is performed when the previously specified event occurs and conditions are satisfied and then click Next.
Show - The item displays when the event is true or No Condition is specified.
Hide - The item does not display when the event is true or No Condition is specified.
Enable - The item is enabled when the event is true or No Condition is specified.
Disable - Disables the affected elements. By disabling the affected elements, the page item will be non-editable and does not retain the item's value when the page is submitted.
Create Opposite False Action - For the selected true action above, create an opposite action to occur when the event is false. The Standard branch of the wizard allows selection of either Show, Hide, Enable or Disable actions for the True Action and provides the facility to create the logical opposite of this. For example, if you select Show for the True Action, checking the Create Opposite False Action check box would also create a Hide false action.
Note:
Create Opposite False Action only available if a Condition has been specified.For Affected Elements (available only for actions that support affected elements), specify the elements affected by this dynamic action and how they are affected then click Next.
The final step in creating the dynamic action is different depending on whether the action you have selected supports selection of affected elements. Some actions, such as Submit Page, do not require affected elements to be selected. Other actions, such as Show, do. If the action selected does not support the selection of affected elements, the last page will just be a Confirm page where you can review details of the dynamic action. If the action selected does support selection of affected elements, options on this page include:
Selection Type - Select the type of page element that is affected by the dynamic action. Depending on the selected type, additional options display. Use these options to specify additional settings and values required to specify how the element is affected.
Item(s), Region, DOM Object, or jQuery Selector - Specify the name of the page element as follows:
Item(s) - Select the item name that is affected by the dynamic action.
Region - Enter or select the region name that is affected by the dynamic action. The region selected must use a region template that includes a container element with an ID attribute set to #REGION_STATIC_ID#. The dynamic action framework relies on this ID value to reference the region.
DOM Object - Enter either the Document Object Model (DOM) object or the ID of a DOM object that is affected by the dynamic action.
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that is affected by the dynamic action.
Click Create.
Advanced dynamic actions are used for complex actions such as setting a value, adding a class, and using a dynamic action plug-in. This option also allows the selection of different events that will trigger the dynamic action.
To create an advanced dynamic action:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Create Dynamic Action Wizard:
Tree view - Under Page Rendering, locate Dynamic Actions. Right-click and select Create.
You can also invoke the wizard by right-clicking on a specific page item or region that you want to be the trigger for the dynamic action. This makes definition faster because certain When values will be pre-filled
Component view - Under Page Rendering, scroll down to Dynamic Actions and click the Create icon.
For Implementation, select Advanced dynamic action type and click Next.
For Identification, enter the following and click Next.
Name - Enter the name of the dynamic action.
Sequence - Enter the sequence of this component. The sequence determines the order of evaluation.
For When, specify when the action is performed and click Next. Available options include:
Event - Dynamic actions can be defined to fire based on events that happen on the page. There are three different categories of events that can be utilized, Browser events, Framework events and Component events. Here are the details of all the supported events, including the internal JavaScript event name in brackets.
Browser Events
Change (change) - Fires when a control loses the input focus and its value has been modified since gaining focus. This is the default setting.
Click (click) - Fires when the pointing device button is clicked over the triggering element.
Double Click (dblclick) - Fires when the pointing device button is double clicked over the triggering element.
Get Focus (focusin) - Fires when the triggering element receives focus by either a pointing device or by tabbing into the element.
Key Down (keydown) - Fires when a key on the keyboard is pressed. Use this event when you want to capture special keystrokes such as arrow keys, after a key has been pressed.
Key Press (keypress) - Fires when a key on the keyboard is pressed resulting in text being entered. Use this event when you want to capture actual text entry.
Key Release (keyup) - Fires when a key on the keyboard is released. Use this event when you want to capture special keystrokes such as arrow keys, after a key has been released.
Lose Focus (focusout) - Fires when the triggering element loses focus either by the pointing device or by tabbing out of the element.
Mouse Button Press (mousedown) - Fires when the pointing device button is pressed over the triggering element.
Mouse Button Release (mouseup) - Fires when the pointing device button is released over the triggering element.
Mouse Enter (mouseenter) - Fires once when the pointing device is moved into the triggering element.
Mouse Leave (mouseleave) - Fires once when the pointing device is moved away from the triggering element.
Mouse Move (mousemove) - Fires when the pointing device is moved while it is over the triggering element.
Page Load (ready) – Fires when the page loads.
Page Unload (unload) - Fires when a page is unloaded.
Resize (resize) - Fires when the browser window is resized.
Resource Load (load) - When the triggering element is the window element (using a DOM Object value of window in the When attributes), the event fires when the browser finishes loading all content within a document, including window, frames, objects and images. For other elements, it fires when the target element and all of its content has finished loading.
Scroll (scroll) - Fires when a scrollable triggering element is scrolled. This could be the browser window (using a DOM Object value of window in the When attributes), scrollable frames or elements with the overflow CSS property set to scroll (or auto when the element's explicit height is less than the height of its contents).
Select (select) - Fires when a user selects some text in a text field.
Framework Events
After Refresh (apexafterrefresh) - Fires after the triggering element has been refreshed. The event is only valid for triggering elements that perform Partial Page Refresh and fire this event, for example Interactive Reports, Classic Reports, and all item types with cascading LOV support. Plug-ins might support this event as well.
Before Page Submit (apexbeforepagesubmit) - Fires prior to a page being submitted.
Before Refresh (apexbeforerefresh) - Fires before the triggering element has been refreshed. The event is only valid for triggering elements that perform Partial Page Refresh and fire this event, for example Interactive Reports, Classic Reports, and all item types with cascading LOV support. Plug-ins might support this event as well.
Component Events
These events will only be available when there is a component (either an item, region, or dynamic action) available to your application that triggers a custom event. These events will appear in the following format Event name [Component Name], for example the Change Order event triggered by the Shuttle native item type will appear as Change Order [Shuttle]. In Oracle Application Express, these events are triggered from native components shipped with plug-in components you have installed into your application.
Events triggered by native components:
Change Order [Shuttle] (shuttlechangeorder) – Fires when the order of a value in the right hand select list is changed (either using Move Top, Move Up, Move Down, or Move Bottom). There are currently no other events triggered by native components in Oracle Application Express.
Events triggered by plug-in components:
These will be available when added to your current application and will be in the format Event name [Component Name]. For help related to events raised by plug-ins, please refer to Help text on the plug-in configuration page, by navigating to Shared Components, Plug-ins, plug-in name, Help Text, where the plug-in author may have included documentation.
Selection Type - Select the type of page element that triggers the dynamic action. A corresponding name field displays to specify the name of the page element.
Note:
Only available if the event selected supports definition of a page element. Selecting any of the following events will hide this field: Page Load, Page Unload, Resize, Before Page Submit. All other event types show this field.Item(s), Button, Region, DOM Object, or jQuery Selector - Specify the name of the page element as follows:
Item(s) - Enter or select one or more page item names that trigger the dynamic action. For multiple items, please separate page items with a comma.
Button - Select the button that will trigger the dynamic action. If the button is a Template button, the button selected must use a button template that includes an ID attribute set to #BUTTON_ID#. The dynamic action framework relies on this ID value to reference the button.
Region - Select the region name that triggers the dynamic action. The region selected must use a region template that includes a container element with an ID attribute set to #REGION_STATIC_ID#. The dynamic action framework relies on this ID value to reference the region.
The region can fire the event itself, such as in the case of Before Refresh or After Refresh events, or can be a container to catch events that fire on items or other elements in the region. Only the following subset of events support this: Change (change), Click (click), Double Click (dblclick), Get Focus (focus), Key Down (keydown), Key Press, Key Release (keyup), Lose Focus (blur), Mouse Button Press (mousedown), Mouse Button Release (mouseup), Mouse Move (mousemove).
DOM Object - Enter either the Document Object Model (DOM) object or the ID of a DOM object that triggers the dynamic action.
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that trigger the dynamic action.
Condition - To conditionalize the trigger, make a selection from the Condition Type list and enter text in the Value field. Based on whether this condition is met, it is possible to define both True (when it is met) and False (when it is not) actions. If No Condition is specified, only True actions will fire. For further information, see the item level Help.
Specify the action that is performed when the previously specified event occurs and conditions are satisfied and then click Next.
For True Actions (Advanced only) - The Advanced branch of the wizard allows selection of all actions and allows selection of different True and False Actions. For both the True Action and False Action pages you specify. Depending on the selected action, additional options display. Use these options to specify additional settings and values required to perform the action.
Component
Clear - Clears the affected elements.
Disable - Disables the affected elements. By disabling the affected elements, the page item will be non-editable and does not retain the item's value when the page is submitted.
Enable - Enables the affected elements.
Hide - Hides the affected elements. Also has the option to Hide all page items on the same line.
Refresh - Triggers a refresh of the affected elements. Note that not all elements support a refresh, you can use it for interactive reports, classic reports and all item types with cascading LOV support. Plug-ins might support this action as well.
Set Focus - Sets the focus to the affected elements. This will default to the first of the affected elements if there are multiple. This can be especially useful when used in conjunction with the Show and Enable actions to take the user straight to the appropriate item.
Set Value - Sets the value of the affected elements. This supports the following Set Types: Static Assignment, JavaScript Expression, SQL Statement, PL/SQL Expression, PL/SQL Function Body. SQL Statement Set Type supports setting between 1 and 100 page item values, by selecting between 1 and 100 columns in the query. All other Set Types only support setting 1 page item. See the Execute PL/SQL Code action for an alternative way to set multiple values on the page.
Show - Shows the affected elements. Also has the option to Show all the page items on the same line.
Execute
Execute JavaScript Code - Allows you to define or call custom, page specific JavaScript code to use within the dynamic action framework. If you are defining JavaScript code that is specific to just one page, you can also make use of the new page level attribute 'Function and Global Variable Declaration' to define this. Functions and variables defined here can subsequently be referenced from this action.
Execute PL/SQL Code - Executes some PL/SQL code on the server. If an error occurs during execution, the user will be alerted. To specify page items that are set on the page when the call to the server returns, based on their values in session state, define Page Items to Return. When the Page Items to Return option is used, and you want to prevent subsequent Change based dynamic actions from firing for the Page Items to Return, set Suppress Change Event to Yes.
Notification
Alert - Displays an Alert.
Confirm - Displays a confirmation dialog. If the user chooses Cancel then the proceeding actions are not executed and the current event is canceled.
Style
Add Class - Adds 1 or more CSS classes to the affected elements.
Remove Class - Removes one, more or all classes from the affected elements.
Set Style - Sets any style, CSS, property to the affected elements.
Miscellaneous
Cancel Event - Cancels subsequent dynamic actions or events from firing, based on certain conditions. This could be useful in the following situations:
If you have multiple dynamic actions on a page that are based on the same event (such as Click) and they refer to the same element on the page, the Cancel Event action can be used to prevent subsequent dynamic actions from firing, conditionally based on its When Condition.
If a dynamic action has many true or false actions, Cancel Event can be used to halt subsequent actions from being processed. Currently this has limited value as it is not possible to define a dynamic action's actions to fire conditionally, so this would just always prevent subsequent actions being processed, which could be useful in debugging.
Used to cancel page submission, when used in conjunction with the Before Page Submit event of dynamic actions. For example, suppose you define a dynamic action that fires on the Before Page Submit even. For the Condition, you define JavaScript Expression and in the Value enter an expression such as $v('P2_ENAME') == 'DO NOT SUBMIT'. Then, if you define a True Action that uses the Cancel Event action, the page will not be submitted when the ENAME field is equal to DO NOT SUBMIT.
Submit Page - Submits the page. Also, has the option to disable the current page during page submission and display a processing style GIF.
Plug-ins
my_plugin_action[Plug-in] - Depending on your application configuration, you may also have additional plug-in dynamic actions available here. These will be displayed as my_plugin_action [Plug-in]. Plug-in dynamic actions are installed within the application's shared components. The plug-in developer will have assigned an appropriate category for the action (Component, Execute and so forth).
Fire On Page Load (Advanced only) - Select this option to also trigger this action when the page loads. This may or may not be checked by default, depending on the type of Action selected.
For Affected Elements (available only for actions that support affected elements), specify the elements affected by this dynamic action and how they are affected then click Next.
The final step in creating the dynamic action is different depending on whether the action you have selected supports selection of affected elements. Some actions, such as Submit Page, do not require affected elements to be selected. Other actions, such as Show, do. If the action selected does not support the selection of affected elements, the last page will just be a Confirm page where you can review details of the dynamic action. If the action selected does support selection of affected elements, options on this page include:
Selection Type - Select the type of page element that is affected by the dynamic action. Depending on the selected type, additional options display. Use these options to specify additional settings and values required to specify how the element is affected.
Item(s), Region, DOM Object, or jQuery Selector - Specify the name of the page element as follows:
Item(s) - Select the item name that is affected by the dynamic action.
Region - Enter or select the region name that is affected by the dynamic action. The region selected must use a region template that includes a container element with an ID attribute set to #REGION_STATIC_ID#. The dynamic action framework relies on this ID value to reference the region.
DOM Object - Enter either the Document Object Model (DOM) object or the ID of a DOM object that is affected by the dynamic action.
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that is affected by the dynamic action.
Click Create.
Once you create a dynamic action, you can modify attributes defined during the creation process, specify attributes not available during the process (such as specifying an Authorization Scheme) and add additional true or false actions.
See Also:
"Creating a Dynamic Action", "Adding Additional True or False Actions", "Defining the Frequency and Scope"To edit a dynamic action:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Dynamic Action page:
Tree view - Under Page Rendering, locate Dynamic Actions. Right-click the dynamic action and select Edit.
You can also go straight to editing a dynamic action's true or false actions by expanding the tree node for the dynamic action, then right-clicking and selecting Edit for the specific action you want to edit.
Component view - Under Page Rendering, scroll down to Dynamic Actions and click the dynamic action you want to edit.
The Edit Dynamic Action page appears.
Make changes and click Apply.
Dynamic actions contain a condition that can be specified to control when True and False actions fire. For example, consider an application that displays employee information to managers. If the employee is exempt, their salary displays, otherwise their hourly wage displays.
The Dynamic Action creation wizard allows only one true and one false action to be specified. To add more than one action you must use the create wizard to create the dynamic action and then edit the action to add additional true or false actions.
To add an action:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Dynamic Action page:
Tree view - Under Page Rendering, locate Dynamic Actions. Right-click the dynamic action and select Edit.
You can also right-click directly on the True or False nodes right under the dynamic action node in the tree. Select Create here and this will take you directly to the page to create the additional true or false action. This is a simpler means of creation and eliminates the next step.
Component view - Under Page Rendering, scroll down to Dynamic Actions and click the dynamic action you want to edit.
The Edit Dynamic Action page appears.
To add an action that executes when the conditions are met or when no condition is specified, scroll down to True Actions and click Add True Action.
Otherwise, scroll down to False Actions and click Add False Action.
The Create/Edit Action page appears.
Under Identification:
Sequence - Enter the sequence for this component. This indicates the evaluation order.
Action - Select the action that triggers when the condition is true or false.
Under Execution Options:
Fire on Page Load - Select if you want the action to also trigger when the page loads.
Stop Execution on Error - Specify whether any proceeding actions should be executed, if an error occurs while executing the current action. Only available when the selected Action has been defined to expose this attribute, for example Execute PL/SQL Code.
For Affected Elements (only available if the selected action supports definition of affected elements):
Note:
Some or all of these fields may not be available to select, depending on the type of action selected. For example the Disable action does not support selecting a Region as the affected element.Selection Type - Select the type of page element that is affected by the dynamic action. A corresponding name field displays to specify the name of the page element.
Item(s), Region, DOM Object, or jQuery Selector - Specify the name of the page element as follows:
Item(s) - Enter or select the item name that is affected by the dynamic action.
Region - Enter or select the region name that is affected by the dynamic action. The region selected must use a region template that includes a container element with an ID attribute set to #REGION_STATIC_ID#. The dynamic action framework relies on this ID value to reference the region.
DOM Object - Enter either the Document Object Model (DOM) object or the ID of a DOM object that is affected by the dynamic action.
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that is affected by the dynamic action.
For Comments, enter developer comments or notes. These comments never display when the application is running.
Click Create.
The Edit Dynamic Action page displays with the added action listed under True Actions or False Actions.
After creating the dynamic action, the scope of the action can be modified to trigger only once, for the lifetime of the current page, or until triggering elements are updated by a Partial Page Refresh (PPR).
To specify scope:
Navigate to the appropriate Page Definition. See "Accessing the Page Definition".
Access the Edit Dynamic Action page:
Tree view - Under Page Rendering, locate Dynamic Actions. Right-click the dynamic action and select Edit.
Component view - Under Page Rendering, scroll down to Dynamic Actions and click the dynamic action you want to edit.
The Edit Dynamic Action page appears.
Scroll down to Advanced and for Event Scope make one of the following selections:
bind - Binds the event handler to the triggering elements for the lifetime of the current page, but will no longer be bound if the triggering elements are updated by Partial Page Refresh (PPR).
live - Binds the event handler to the triggering elements for the lifetime of the current page, including any elements that are updated by Partial Page Refresh (PPR).
once - Binds the event handler to the triggering elements for a once only event.
Click Apply Changes.
Debugging dynamic actions in Oracle Application Express is slightly different than other debugging, because much of the processing done with the dynamic action framework is done on the client, not on the server. To debug dynamic actions, Oracle Application Express outputs debug information to the browser's JavaScript console if your browser supports it (for example Firefox with Firebug installed will show the debug information in its Console pane). The debug information will tell you when a dynamic action fires, the name of the dynamic action, and also specifically which action has fired.
To debug a dynamic action:
Ensure the application containing the dynamic action has Debugging enabled. See "Accessing Debugging Mode".
Run the page containing the dynamic action.
Open the browser's JavaScript console.
From the Developer toolbar, click Debug.
The page refreshes. If you have any dynamic actions that are set to fire on page load, you will see the following text output to the console:
Dynamic Action Fired: [Dynamic action name] ([specific action fired])
Since debug information is only output when running in Debug mode, leaving Debug mode switched on enables you to further test if dynamic actions are firing when you expect them to. For example if you have defined a dynamic action that fires when a certain item's value changes, change that item's value and the console will show the debug output if the dynamic action fires.