Prior to APEX 4, if you wanted to perform an action based on a browser event you needed to write custom JavaScript (JS) code. Writing custom JavaScript code poses several issues:

The following JavaScript example shows how to toggle a field based on a browser event prior to APEX 4. This code snippet needs to be included in your page. Since there are multiple ways to include it in your page, it can be hard for someone to track down where the code is stored.

/**
 * Toggle Empno based on P1_DEPTNO's value
 */
function showHideEmpno(){
  if ($('#P1_DEPTNO').val().length > 0)
    $('#P1_EMPNO').closest('tr').show();
  else
    $('#P1_EMPNO').closest('tr').hide();
}//showHideEmpno

//Wait for page to be ready
$(document).ready(function() {
  //Show/Hide Empno after page load

showHideEmpno();

  //Register browser event (onChange)
  $('#P1_DEPTNO').change(function(){showHideEmpno();});
});

Starting in APEX 4.0 you can declaratively trigger actions based on browser events using Dynamic Actions. Dynamic Actions are a preferred method over custom JavaScript functions because:

The following steps describe how to toggle the Employee field, as you did in the previous example, using a Dynamic Action. This example will not go into detail for each step since the goal is to quickly compare the manual method with the new method by creating Dynamic Actions. The second section of this chapter will describe each of the available options in detail.

You should now see the Show Hide EmpNo Dynamic Action in the Page Rendering section as shown in Figure 7-9.

Figure 7-9. Show Hide EmpNo Dynamic Action

When you refresh Page 1 the Employee select list will only appear when the Department item is not null. 07_example-1.sql is the application for this demo.

Dynamic Actions have a lot of benefits; however, there are some situations where you may want to do things the old (manual) way, primarily for performance and control issues. For example, if you have a client-side action that needs to be performed as quickly as possible, then manually coding it using JavaScript may be a better approach. Dynamic Actions can add a small amount of overhead compared to certain manual techniques. In most situations this additional overhead is not significant.

The Identification section, as shown in Figure 7-12, is similar to other objects in APEX. You can define a name and a sequence. Although the name will not be displayed to the end user, a meaningful name is useful for other developers modifying your application.

Figure 7-12. Edit Dynamic Action: Identification

The sequence number determines the order in which Dynamic Actions are performed. If an action is set to fire on page load the sequence number will determine the order of the actions, regardless of their triggering event, during the page load. After the page is loaded the sequence is only relevant if you have multiple Dynamic Actions that are executed by the same event.

APEX Dynamic Actions bind events to object(s) that you specify in the When section. When the defined event occurs on the object(s) APEX will run the appropriate actions. The When section for the Show Hide EmpNo Dynamic Action is shown in Figure 7-13.

Figure 7-13. Edit Dynamic Action: When

There are three main components to the When section: Event, Selection Type, and Condition. If you click each of these labels, you'll get some excellent documentation about each of these components.

Event: Dynamic Actions are triggered by browser-based events. These events are invoked by user actions or by JavaScript. The event determines which event will trigger the Dynamic Action to run. In the example, you wanted the Dynamic Action to run when the user changed the value for P1_DEPTNO, so the Change event was selected.

The events are grouped into three main categories: Browser Events, Framework Events, and Component Events. Browser events are standard HTML events. (For more information about HTML event types please refer to the jQuery documentation on events: http://api.jquery.com/category/events.) Framework events are triggered by APEX specific events. For example, the After Refresh event is triggered after a report region is refreshed as part of report pagination. Component events are triggered by specific objects within APEX or by plug-ins.

Selection Type: The event option will determine what events APEX needs to "listen" for. The Selection Type and Selection determines the object(s) to listen on. In the example, Item(s) was selected. This means that APEX will wait for a change to occur on P1_DEPTNO. Once a user changes the P1_DEPTNO select list, the Show Hide EmpNo Dynamic Action will be triggered. There are four different selection types to choose from: Item(s), Region, DOM Object, and jQuery Selector.

If the selection type is set to Item(s), you need to specify a comma delimited list of items in the Item(s) field. APEX will listen to all the specified items and apply the same action(s), regardless of which item was selected. When the Dynamic Action is triggered, APEX passes the specific item that triggered it as part of a JavaScript object (more on this later).

The Region selection allows you to select a single region for APEX to listen on. A good example of this is if you wanted to display a custom wait message each time an Interactive Report is refreshed. In this case, you'd set the event to Before Refresh and set the selection type to Region and select the region that contains your Interactive Report.

When using a region as the selection type, it is important to ensure that the region's template contains an ID. If the region's template is set to No Template, APEX will not be able to register its listener on the region since the region does not contain an ID. For more information read the following blog post: http://www.talkapex.com/2011/01/missing-id-in-no-template-region.html

Instead of listening on APEX specific objects such as item(s) or a region, you can also specify a DOM object or a jQuery Selector. In most cases it will be easier to use the jQuery selector rather than referencing the DOM object. This is especially true if you need to select multiple elements with a common attribute. For example, if you wanted APEX to perform a Dynamic Action each time someone moved their mouse over a HTML element with a class of highlight-me you would select jQuery Selector and enter .highlight-me as shown in Figure 7-14. The jQuery Selector option uses jQuery notation. Detailed information about the jQuery selector notation can be found on the jQuery site: http://api.jquery.com/category/selectors.

Figure 7-14. When Selection Type: jQuery Selector

Condition: Dynamic Actions allow you to perform different actions based on a condition. The condition is evaluated in real time against the triggering element each time the event occurs. This condition is not the same as a standard APEX object condition. If the condition is true or not defined, then the True action(s) are executed. If the condition is false, the False action(s) are performed.

In the example the condition (previously shown in Figure 7-13) is set to is not null. This means that each time the triggering element P1_DEPTNO is changed, APEX will evaluate it to see if it is null or not. If it is null then it will hide the list of employees (false action). If a department is selected, it will show the list of employees (true action).

A list of conditions is shown in Figure 7-15. All conditions, except for is not null and is null, require that you enter some additional information in the Value field.

Figure 7-15. List of conditions

The value required for the first six comparison conditions is a static value. You can reference an item value but you must use the substitution string &PX_ITEM_NAME. notation. If you use a substitution string it will use the value of the item when the page is loaded which may not be the same value that is currently on the page when the condition is evaluated.

The two list conditions compare static comma delimited lists. If referencing a substitution string, the value of the item at the time the page is loaded will be used.

The last condition, JavaScript expression, allows you to compare values in real time when the condition is evaluated. All the other conditions are evaluated against the triggering element. If you use a JavaScript expression, you can compare any set of values. In most cases part of the expression will include the triggering element.

The JavaScript expression condition type contains several objects. They are

If you want to quickly see all the additional information that is available in each of the attributes listed above set the condition to JavaScript expression and in the Value field enter console.log(this);, as shown in Figure 7-16. Refresh the page and trigger the event. If you look at the console you will see the output of the "this" object as shown in Figure 7-17.

Figure 7-16. Configure condition to display this object

Figure 7-17. Console output of condition this object

To demonstrate a condition which uses a JavaScript expression, add an additional Number Field item on Page 1 called P1_X. Change the condition in the Show Hide EmpNo Dynamic Action from is not null to JavaScript Expression. In the Value text area enter: this.triggeringElement.value > $('#P1_X').val() as shown in Figure 7-18. Refresh the page and enter 20 in the P1_X field. When you change the department the list of employees will only appear when you select Operations (40) and Sales (30). You'll notice that if you change the value of P1_X the condition will evaluate accordingly without having to submit the page or set the value in session state.

Figure 7-18. JavaScript condition

The When section defines the events and objects that APEX should listen to. The Advanced section defines how the events are bound to the objects. There are three different ways to attach an event to an object, as shown in Figure 7-19.

Figure 7-19. Event Scopes

For more information about attaching events, please refer to the following documentation: http://api.jquery.com/category/events/event-handler-attachment. The jQuery API contains additional event handler attachment options that are currently not available in APEX.

The True and False Actions sections, as shown in Figure 7-20, contain action(s) to perform based on the Dynamic Action's condition. If multiple actions exist in each section they will be synchronously executed in order, determined by their sequence number.

Figure 7-20. True and False Actions

At the beginning of this chapter you created the Show Hide EmpNo Dynamic Action using the Standard wizard. The True/False Actions steps allowed you to define a true and false action (see Figure 7-7). One of the available options was to Create Opposite False Action. This meant that it created both the true action (show) and the false action (hide).

To help describe the options available in the Edit Action page, edit the true (Show) action by clicking its Edit icon, which looks like a pencil, as shown in Figure 7-20. You can also modify the Show action by double-clicking the Show action in the tree from the Page Edit screen as shown in Figure 7-21. The Edit Action page is shown in Figure 7-22. The following subsections will describe all the options available when modifying an action.

Figure 7-21. Edit Show Action

Figure 7-22. Create/Edit Action page

Identification

The Identification section allows you to define the sequence and the action. The sequence affects the order, within the scope of the Dynamic Action, that the actions will run in.

The options in the actions select list are broken up into seven categories. The categories have no impact on the system and are there to help organize the list of available actions. This list also includes plug-in Dynamic Actions which are suffixed with "[Plug-in]" as shown in Figure 7-23. Clicking the Action label will display a pop-up window with a brief description for each of the built-in actions. Some actions require additional configuration, which is covered in the Settings and Affected Elements sections.

Figure 7-23. Action select list

Execution Options

The Execution Options section determines when to run the action based on the Dynamic Action's condition. An action can either be run when the condition is true or false. Setting the value to True or False will determine which section the action is listed in Figure 7-20.

You can choose whether or not to fire the action once the page is loaded. In order for the option to be run on page load this option needs to be selected and the Dynamic Action's condition result must match the True/False setting. For example, both of the actions in the Show Hide EmpNo Dynamic Action are set to fire on page load. Only one of these will actually be run during the page load based on the value of P1_DEPTNO.Some actions, such as Execute PL/SQL Code and Set Value, allow you to select a third option: Stop Execution On Error, as shown in Figure 7-24. If the action causes an error and this option is set, any other actions that are part of the same Dynamic Action will not run.

Figure 7-24. Stop Execution On Error

After showing users the previous example, they requested some modifications to the department/employee behavior. Instead of selecting an employee from a select list they would like to select an employee from a report. The full list of requirements is

Using Dynamic Actions, you'll be able to implement all these requirements. In order to simplify the solution, it has been broken it up into small sections.

Before you start working on this example you'll need to modify a few things from the first example. You will find an application that was configured with the following modifications in the Source Code/Download area of the Apress web site at www.apress.com. You can skip this section if you import the application 07_example-2_base_application.sql.

Figure 7-26. Application Builder main page

If you now run the application it should look like Figure 7-27.

Figure 7-27. Initial setup

To meet the first requirement, you'll need to create a report region which lists the employees in the selected department. To create this report:

Figure 7-30. Column Formatting/HTML Expression

If you refresh Page 1 it will look like Figure 7-31. If you change the department, nothing happens, since you haven't applied any Dynamic Actions.

Figure 7-31. Department Employees report added

The first Dynamic Action to create is to refresh the Department Employees report when the P1_DEPTNO select list changes. The following steps will create the Dynamic Action when the department is changed:

Reload the page and change the department. It appears as though nothing has happened. In Firefox, if you look at the console, as shown in Figure 7-33, an AJAX request was made, however no data was found.

Figure 7-33. AJAX request on department change

If you reexamine the query you'll notice that the predicate, where e.deptno = :p1_deptno, references P1_DEPTNO. In order for the report to reflect the new value you'll need to create a Dynamic Action to set P1_DEPTNO's session value before the report is refreshed. To set the value in session state:

Figure 7-34. Set P1_DEPTNO in session state

If you refresh the page and change the department the report should be updated. Figure 7-35 shows the page when Accounting is selected as the department.

Figure 7-35. Department Employees report updated by Dynamic Action

Now that the Department Employees report refreshes when the department is changed, the next step is to add the ability to highlight each row when a user hovers over it. If you inspect the HTML for the table that displays the employees, you'll notice that each row has a class of highlight-row as shown in Figure 7-36.

Figure 7-36. Table HTML

The highlight-row class can be used to add a CSS style to highlight the row when you hover over it. The CSS style is

/* Using the DEPT_EMP_REPORT id ensures that this highlighting will only affect the

 Department Employees report */
#DEPT_EMP_REPORT .highlight-row:hover > td {
  background-color: yellow;
}

Normally you would include this in a CSS file and store it on a web server which would be referenced in the HTML header. For the purpose of this example, inline CSS will be "injected" into the application using a Dynamic Action.

If you refresh the page and hover over each row you should notice that the current row is highlighted yellow. You can change the color by modifying the value in the style tag that was added.

The next Dynamic Action will handle what happens when a row is clicked. According to the requirements, when a row is clicked the employee number should be set in a hidden field (P1_EMPNO) and the employee name should be displayed.

To meet this requirement, the additional custom data attributes that were added to the ENAME column in the report will be leveraged. If you inspect the HTML of an employee name in the report column, you'll notice the additional attributes, data-ename and data-empno, as shown in Figure 7-37.

Figure 7-37. HTML 5 Custom Data Attributes

The following steps will create the Dynamic Action which will handle the row click event:

If you refresh the page and click on a row in the Department Employees region the associated employee's name should be displayed beside the Employee label as shown in Figure 7-38.

Figure 7-38. Select Employee—Row Click

The displayed employee name needs to be emphasized after the employee has been selected. To emphasize the name, immediately hide the employee name, bold it, and then have it fade in. Once the fade in is complete, remove the bold font setting.

To emphasize the employee name, one Dynamic Action will be needed with multiple actions. There are various ways to do this, but the goal of this example is to demonstrate how multiple actions within a Dynamic Action work.

The following steps will create the appropriate Dynamic Action along with the additional true actions:

Refresh Page 1 and click on an employee in the Department Employees report; the employee name should appear in the Employee area. Once the name appears nothing happens to it. This is due to how the change event is triggered when called from JavaScript.

The change event is triggered when a user modifies a value from the browser. If the value is modified by JavaScript the change event is not fired. To resolve this issue you'll need to manually trigger a change event when P1_EMP_DISPLAY is modified. An event can easily be triggered using the jQuery trigger() function.

To trigger the change event on P1_EMP_DISPLAY modify the Row Click Dynamic Action and edit the Execute JavaScript true action. Change the last line in the code area from this:

$('#P1_EMPNO_DISPLAY').html(dataSpan.attr('data-ename'));

to this:

$('#P1_EMPNO_DISPLAY').html(dataSpan.attr('data-ename')).trigger('change'),

Apply the changes and refresh the run page. The employee name should be bolded and fade in for 2 seconds after a row is clicked. Once the fade in finishes the employee name is no longer bolded.

So far all the requirements have been met except for the modal window. Because it is easier to develop, debug, and demonstrate our example without the extra complexities of a modal window, this was saved for last. To implement the modal window a free Dynamic Action plug-in from http://apex-plugin.com will be used.

The plug-in that will be used for the modal window is called ClariFit Simple Modal. This plug-in can convert a region into a modal window. The following steps cover how to download and install the plug-in.

Now that the Dynamic Action plug-ins are installed, you can create the appropriate actions to display the Department Employees region in a modal window when P1_DEPTNO is changed. First, the Department Employees region should be hidden when the page is loaded since it should only appear when the department is changed. To hide the Department Employees region, add another true action as shown in Figure 7-41, to the On Page Load Dynamic Action which is fired when the page is loaded. Once this action is added refresh the page. The Department Employees region should be hidden.

Figure 7-41. Hide Department Employees Region on Page Load

The next thing to do is to add an action to display the Department Employees region in the modal window. Since the Change DeptNo Dynamic Action already exists you can add another true action to display the region. Add a new true action to Change DeptNo and configure it as shown in Figure 7-42. The selected action, ClariFit Simple Modal - Show, is the dynamic action plug-in that was imported.

Figure 7-42. Create show modal window action

If you refresh the page and change a department, the Department Employees region should appear as a modal window. When you select an employee, the employee name gets updated but the Department Employees region still remains as a modal window, as shown in Figure 7-43.

Figure 7-43. Modal window show

The last action to add will close the modal window when the user clicks on a row (i.e., selects an employee). Add a true action to the Row Click Dynamic Action and configure it as shown in Figure 7-44. If you refresh the page it should now meet all the requirements that were outlined at the beginning of this example.

Figure 7-44. Create close modal window action