This section provides an overview of dynamic actions and explains how to create and modify them.
See Also:
"Accessing 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. 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. 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, JavaScript Expression, 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
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:
You can define dynamic actions can to fire based on events that happen on the page. Oracle Application Express includes four different categories of events: Browser events, Framework events, Component events, and Custom events. This section describes all supported events, including the internal JavaScript event name in brackets.
Note:
The events displayed differ according to the page's current User Interface type. If you want to select an event that corresponds to a different type, then you have the option of selecting Show unsupported, which displays all events including those that do not correspond to the current type.Change (change) - Fires when a control loses the input focus and its value has been modified since gaining focus. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Click (click) - Fires when the pointing device button is clicked over the triggering element. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Double Click (dblclick) - Fires when the pointing device button is double clicked over the triggering element. Supported User Interface types: Desktop.
Get Focus (focusing) - Fires when the triggering element receives focus by either a pointing device or by tabbing into the element. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
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. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
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. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
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. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Lose Focus (focusout) - Fires when the triggering element loses focus either by the pointing device or by tabbing out of the element. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Mouse Button Press (mousedown) - Fires when the pointing device button is pressed over the triggering element. Supported User Interface types: Desktop.
Mouse Button Release (mouseup) - Fires when the pointing device button is released over the triggering element. Supported User Interface types: Desktop.
Mouse Enter (mouseenter) - Fires once when the pointing device is moved into the triggering element. Supported User Interface types: Desktop.
Mouse Leave (mouseleave) - Fires once when the pointing device is moved away from the triggering element. Supported User Interface types: Desktop.
Mouse Move (mousemove) - Fires when the pointing device is moved while it is over the triggering element. Supported User Interface types: Desktop.
Orientation Change (orientationchange) - Fires when a device's orientation changes (by turning it horizontally or vertically). The 'this.browserEvent' JavaScript object contains an 'orientation' property that will equal either 'portrait' or 'landscape'. Supported User Interface Type: 'jQuery Mobile Smartphone'.
Page Load (Desktop User Interface uses ready, jQuery Mobile Smartphone User Interface uses pageint) – Fires when the page loads. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Page Unload (unload) - Fires when a page is unloaded. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Resize (resize) - Fires when the browser window is resized. Supported User Interface types: Desktop.
Resource Load (load) - When the triggering element is the window element (using a JavaScript Expression 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, this event can only be used for elements associated with a URL: images, scripts, frames, iframes. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Scroll (scroll) - Fires when a scrollable triggering element is scrolled. This could be the browser window (using a JavaScript Expression 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). Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Scroll Start (scrollstart) - Fires when a scroll begins. Supported User Interface Type: jQuery Mobile Smartphone.
Scroll Stop (scrollstop) - Fires when a scroll ends. Supported User Interface Type: jQuery Mobile Smartphone.
Select (select) - Fires when a user selects some text in a text field. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Swipe (swipe) - Fires when a horizontal drag of 30px or more (and less than 75px vertically) occurs, within a 1 second duration. Supported User Interface Type: jQuery Mobile Smartphone.
Swipe Left (swipeleft) - Fires when a swipe event occurs moving in the left direction. Supported User. Interface Type: jQuery Mobile Smartphone.
Swipe Right (swiperight) - Fires when a swipe event occurs moving in the right direction. Supported User Interface Type: jQuery Mobile Smartphone.
Tap (tap) - Fires after a quick touch event. Supported User Interface Type: jQuery Mobile Smartphone.
Tap and Hold (taphold) - Fires after a held touch event (held for close to 1 second). Supported User Interface Type: jQuery Mobile Smartphone.
Touch Cancel (vmousecancel) - Normalized event for handling touch or mousecancel events. Supported User Interface Type: jQuery Mobile Smartphone.
Touch End (vmouseup) - Normalized event for handling touchend or mouseup events. Supported User Interface Type: jQuery Mobile Smartphone.
Touch Move (vmousemove) - Normalized event for handling touchmove or mousemove events. Supported User Interface Type: jQuery Mobile Smartphone.
Touch Start (vmousedown) - Normalized event for handling touchstart or mousedown events. Supported User Interface Type: jQuery Mobile Smartphone.
Virtual Click (vclick) - Normalized event for handling touchend or mouse click events. On touch devices, this event is dispatched after Touch End. Supported User Interface Type: jQuery Mobile Smartphone.
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. The native components that support this are Interactive Reports, Classic Reports, Charts, List View and all item types with cascading LOV support. Plug-ins might support this event as well. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
Before Page Submit (apexbeforepagesubmit) - Fires before a page being submitted. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
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. The native components that support this are Interactive Reports, Classic Reports, Charts, List View and all item types with cascading LOV support. Plug-ins might support this event as well. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
These events are available when there is a component (either an item, region, or dynamic action) available to your application that triggers a custom event. These events appear in the following format Event name [Component Name], for example the Change Order event triggered by the Shuttle native item type appears as Change Order [Shuttle]. Component events are either triggered from native components shipped with Oracle Application Express, or from 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. Supported User Interface types: Desktop and jQuery Mobile Smartphone.
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, 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. Supported User Interface types: Determined by the plug-in's User Interfaces > Supported for settings.
Custom Event:
By selecting Custom an additional field displays enabling you to define of a custom event. This is useful when the native or plug-in provided events are insufficient.
This section describes how to manage dynamic actions in Page Designer.
Creating a dynamic action involves specifying when the action happens (with optional conditions), what action or actions are performed, and what elements are affected by the action.
View the page to contain the item in Page Designer. See "Viewing a Page in Page Designer."
Click the Dynamic Actions tab in the left pane.
Under Dynamic Actions, right-click Events and select Create Dynamic Action.
Tip:
You can also select an event type and then right-click to select Create Dynamic Action.Attributes for the dynamic action display in the Property Editor.
Tip:
The Messages tab displays a red or yellow badge to identify messages you need to address. Selecting a message displays the associated attribute in the Property Editor. You must address red error message before you can save.View all attributes in the Property Editor. Select Show All from the Property Editor Menu.
Under Property Editor - Dynamic Actions, edit the following attributes:
Tip:
To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.Identification, Name - Enter the name of the dynamic action.
Execution Options, Sequence - Enter the sequence for this computation. The sequence determines the order of execution.
When, Event - Specify the event that causes the dynamic action to fire. See "About Dynamic Action Events."
When, Selection Type - Select the type of page element or construct to be used to trigger the event. For examples of using a specific selection type, see Help on the associated attribute.
Note:
Only available if the event selected supports definition of a page element. Selecting any of the following events hides this field: Page Load, Page Unload, Resize, Before Page Submit, Orientation Change. All other event types show this field.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, separate page items with a comma.
Button - Select the button that triggers 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, for example, 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).
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that trigger the dynamic action.
JavaScript Expression - Enter a JavaScript expression to return a DOM or jQuery object that triggers the dynamic action.
Next, define the action that to be performed if the event evaluates to True or False.
To edit an existing action:
Expand the Dynamic Action tree to view the True or False nodes.
Under True or False, select the action.
Edit the action in the Property Editor.
To add a new action:
Expand the Dynamic Action tree.
Right-click the dynamic action and select either Create TRUE Action or Create False Action.
Edit the action in the Property Editor.
Click Save.
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 actions.
To edit a dynamic action:
View the page to contain the item in Page Designer. See "Viewing a Page in Page Designer."
Click the Dynamic Actions tab in the left pane. Dynamic action are organized by events.
Expand the appropriate event and select the dynamic action.
Attributes for the dynamic action display in the Property Editor.
In Property Editor - Dynamic Action, edit the appropriate attributes.
Tip:
To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.To edit an existing action:
Expand the Dynamic Action tree to view the True or False nodes.
Under True or False, select the action.
Edit the action in the Property Editor.
To add a new action:
Expand the Dynamic Action tree.
Right-click the dynamic action and select either Create TRUE Action or Create False Action.
Edit the action in the Property Editor.
Click Save.
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:
View the page in Page Designer. See "Viewing a Page in Page Designer."
Click the Dynamic Actions tab in the left pane.
Under Dynamic Actions, select the dynamic action.
The Property Editor - Dynamic Action appears.
View all attributes in the Property Editor. Select Show All from the Property Editor Menu.
Under Advanced, select an Event Scope. Options include:
Static
Dynamic
Once
Tip:
To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.Click Save.
To delete a dynamic action:
View the page to contain the item in Page Designer. See "Viewing a Page in Page Designer."
Click the Dynamic Actions tab in the left pane.
Expand the appropriate event and locate the dynamic action to be deleted.
Right-click the dynamic action and select Delete.
Click Save.
This section describes how to manage dynamic actions in Component View.
Creating a Dynamic Action involves specifying when the action happens (with optional conditions), what action or actions are performed, and what elements are affected by the action.
Navigate to the appropriate page. See "Viewing a Page in Component View."
Under Page Rendering, scroll down to Dynamic Actions and click the Create icon.
The Dynamic Action wizard appears.
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 execution.
For When, enter the following and click Next.
Event - Specify the event that will cause the dynamic action to fire. See "About Dynamic Action Events."
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 hides this field: Page Load, Page Unload, Resize, Before Page Submit, Orientation Change. All other event types show this field.Specify the name of one or more page elements that will trigger the dynamic action. For multiples, separate page element names with a comma.
Item(s) - Enter or select one or more page item names that trigger the dynamic action. For multiple items, separate page items with a comma.
Button - Select the button that triggers 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, for example, 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).
jQuery Selector - Enter the jQuery selector syntax to return one or more page elements that trigger the dynamic action.
JavaScript Expression - Enter a JavaScript expression to return a DOM or jQuery object that triggers the dynamic action.
Condition - To provide a condition, make a selection from the Condition list. Depending on the condition type, you may be required to enter a Value to test the condition against. If no condition is specified, only True Actions fire. If a condition is specified, the True Action fires when the condition is met, the False Action fires when it is not.
On True Action, specify the action performed when the previously specified event occurs and conditions are satisfied and click Next.
Action - Select the True action you want to fire when the Condition is met or when No Condition has been specified. Depending on the selected action, additional options display.
Tip:
To learn more, see field-level Help. See "Viewing Field-Level Help."Fire On Page Load - Select this option to trigger this action when the page loads. Depending upon the type of selected action, this option may or may not be selected.
Generate Opposite False Action - Select this option to also generate the opposite false action. Actions treated as opposite are Show / Hide, Enable / Disable and Add Class / Remove Class. This option only displays if one of the above actions are selected, and a When 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 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.
Tip:
To learn more, make a selection and see field-level Help. See "Viewing Field-Level Help."Click Create Dynamic Action.
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 actions.
To edit a dynamic action:
Navigate to the appropriate page. See "Viewing a Page in Component View."
Under Page Rendering, scroll down to Dynamic Actions and click the dynamic action you want to modify.
The Edit Dynamic Action page appears.
Edit the appropriate attributes.
To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."
Click Apply Changes.
This section describes how to add additional true actions.
Dynamic actions contain a condition that can be specified to control when True 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 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 actions.
To add an action:
Navigate to the appropriate page. See "Viewing a Page in Component View."
Under Page Rendering, scroll down to Dynamic Actions and click the dynamic action you want to modify.
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.
The Create/Edit Action page appears.
Under Identification:
Sequence - Enter the sequence for this component. This indicates the execution order.
Action - Select the action that triggers when the condition is true.
Under Execution Options:
Fire on Page Load - Select if you want the action to also trigger when the page loads.
Edit the appropriate attributes.
To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."
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.
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.
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. See "Viewing a Page in Component View."
Under Page Rendering, scroll down to Dynamic Actions and click the dynamic action you want to modify.
The Edit Dynamic Action page appears.
Scroll down to Advanced. For Event Scope, select one of the following:
Static (default) - 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).
Dynamic - 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). Specifying Dynamic causes an additional field Static Container (jQuery Selector) to be displayed. Specifying a Static Container can help improve the performance of the way events are handled with a Dynamic Event Scope. This should be an element on the page that itself does not get re-created, but contains the triggering elements that are re-created using Partial Page Refresh (PPR). This element reference must be defined as a jQuery selector.
For example if you have a dynamic action that does something to the rows of an interactive report region (which is re-created by PPR), this would need an Event Scope of Dynamic, in order for the dynamic action to still work after the report has been refreshed. And here, the Static Container value could be set to a jQuery selector selecting the region's Static ID value, for example: '#my_region'.
Once - Binds the event handler to the triggering elements for a once only event.
Click Apply Changes.
You can also execute JavaScript code by creating a dynamic action. JavaScript code can be executed with the types Execute JavaScript and Set Value. You can also use JavaScript code for the condition of a dynamic action by setting the condition type to JavaScript Expression.
See Also:
"Managing Dynamic Actions"This section describes how to debug dynamic actions in Oracle Application Express.
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 shows the debug information in its Console pane). The debug information tells you when a dynamic action fires, the name of the dynamic action and also the Action JavaScript Object, which contains all the information needed by the client to execute the action (for example, event name, when details, action, affected elements and so on).
To debug a dynamic action:
Ensure the application containing the dynamic action has Debugging enabled. See "Utilizing Debug 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 see the following text output to the console:
Dynamic Action Fired: [Dynamic action name] ({JavaScript Object containing all Dynamic Action information})
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 shows the debug output if the dynamic action fires.