Dynamic actions were first introduced in APEX 4.0. They allow developers to declaratively define actions based on browser events. This chapter will cover all aspects of dynamic actions including creating and modifying dynamic actions and how dynamic actions can interact with each other. This chapter is divided into three main sections. It will first compare the manual way of manipulating browser events using custom JavaScript to create a dynamic action. The second section will cover all the options and features available with dynamic actions. The last section will present a detailed example of using multiple dynamic actions.

This chapter assumes you are familiar with APEX and have a basic understanding of the following web technologies:

• JavaScript
• jQuery
• CSS
• HTML

If you are unfamiliar with any of these languages or need additional information, please go to www.w3schools.com. The JavaScript examples provided in this chapter will use jQuery, which is included as part of APEX 5.

Custom JavaScript vs. Dynamic Actions

The best way to highlight dynamic actions is to compare them to the manual method using custom JavaScript. This section will examine a simple problem you may have faced when developing an APEX application and show how to resolve it first manually and then using a dynamic action. The purpose is to demonstrate the manual versus dynamic action way to handle browser-based events in APEX.

Suppose you have a select list for a department (P1_DEPTNO) and employees (P1_EMPNO) on page 1. If no department is selected, the list of employees should not be displayed, as shown in Figure 8-1. Once a department is selected, the list of employees should appear, as shown in Figure 8-2. The two subsections that follow compare the different ways to implement the functionality shown in the figures.

Manual (Custom JavaScript) Method

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

• The code can be stored in different locations such as an external file, HTML region, region header, as part of a page process, and so on. This can make it hard to find the exact location of the code if you need to debug or modify it.
• If developing in a team environment, each developer may use different techniques, and the code might not be reusable.
• Not all APEX developers understand JavaScript.

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 ($v(’P1_DEPTNO’) == ’’)
    $x_HideItemRow(’P1_EMPNO’);
  else
    $x_ShowItemRow(’P1_EMPNO’);
}//showHideEmpno
//Wait for page to be ready
$(document).ready(function() {
  //Show/Hide Empno after page load
  showHideEmpno();

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

Dynamic Action Method

Starting in APEX 4, you can declaratively trigger actions based on browser events using dynamic actions. Dynamic actions are a preferred method over custom JavaScript functions because of the following reasons:

• They are declarative, which allows developers to easily identify where the code is stored.
• They have a built-in framework to maintain consistency across an application.
• They make it easy for non-JavaScript developers to apply browser event–based actions.

The following steps describe how to toggle the Employee field, as was done in the previous example, using a dynamic action. This example does not cover each step in detail since the goal is to quickly compare the manual method with the dynamic action. The next section of this chapter will describe each of the available options in detail.

1. In the Page Designer, click the Dynamic Actions icon at the top of the left pane, as shown in Figure 8-3.

   

   Figure 8-3. Click the Dynamic Actions icon

2. Right-click the Events folder and select the Create Dynamic Action option from the menu, as shown in Figure 8-4.

   

   Figure 8-4. Create Dynamic Action menu item

3. The left pane shows the new (yet still unspecified) dynamic action, as shown in Figure 8-5. Some of the missing required information is highlighted in red. To see the complete list of missing components, click the Messages tab, as shown in Figure 8-6.

   

   Figure 8-5. Newly created dynamic action

   

   Figure 8-6. Page Designer Messages notifications

4. In the left pane, click the dynamic action currently labeled as X New and modify its properties in the right pane, as shown in Figure 8-7.

   

   Figure 8-7. Dynamic Action properties

5. On the left pane, select X Show and edit its properties in the right pane, as shown in Figure 8-8.

   

   Figure 8-8. True Action properties

6. In the left pane, right-click the newly created Show action and select Create Opposite Action, as shown in Figure 8-9. This will create a new False action that will hide the employee row.

   

   Figure 8-9. Create Opposite Action menu item

7. Click the Save button in the top-right corner of the page and run the page to test the new dynamic action. An employee should appear only when a department has been selected.

Dynamic actions have a lot of benefits; however, there are some situations where you may want use custom JavaScript, 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 add a minimal amount of overhead compared to certain manual techniques. In most situations, this additional overhead is not significant nor will it degrade the performance of your application.

Dynamic Actions in Detail

This section will cover all the options available for dynamic actions and will reference the OnChange DeptNo dynamic action that was created in the previous section.

An easy way to understand dynamic actions is to break down their components into two main parts: drivers and actions. The driver determines what causes a dynamic action to run and when an action is triggered. Actions contain the code to perform the tasks. In the previous example, the driver is when the P1_DEPTNO select list is changed. The actions is to either show or hide the P1_EMPNO select list. Figure 8-10 highlights the driver and actions concept as part of a flow chart. In Figure 8-10, DA stands for dynamic action.

When modifying a dynamic action, the When and Advanced sections allow you to define the driver. The True and False actions define the actions to perform based on a real-time condition.

To edit a dynamic action, simply click the Dynamic Actions icon (shown earlier in Figure 8-3) and click the desired dynamic action. Alternatively, you can select the rendering icon in the left pane, as shown in Figure 8-11. Then expand the P1_DEPTNO item and click its dynamic actions, as shown in Figure 8-12.

Editing a dynamic action will display its properties in the right pane. The following sections will cover each of these options, except for the standard sections (Condition, Authorization, Configuration, Comments) that are found in most APEX objects. If a section does not appear in your current view, try to toggle between the property editor’s view options, Show Command and Show All, as shown in Figure 8-13.

Identification

The Identification section, as shown in Figure 8-14, 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.

Dynamic actions can have multiple actions, so it is recommended that you come up with a naming scheme that works for your organization. One naming scheme that has proven useful is to name the dynamic action based on the triggering event.

Execution Options

The Execution Options section, as shown in Figure 8-15, sets the sequence number. 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 relevant only if you have multiple dynamic actions that are executed by the same event.

When

APEX dynamic actions bind events to objects that you specify in the When section. When the defined event occurs on the objects, APEX will run the appropriate actions. Figure 8-16 shows the When section for the onChange Deptno dynamic action.

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. You can find the documentation in the Help tab in the central pane, as shown in Figure 8-17.

Event

Dynamic actions are triggered by browser-based events. These events are invoked by a user’s actions or by JavaScript. The event determines which event will trigger the dynamic action to run. In the example, the dynamic action is set to run when the user changed the value for P1_DEPTNO, so the Change event was selected.

Events are grouped into four main categories: Browser, Framework, Component, and Custom events. Browser events are standard HTML events (for more information about HTML event types, please refer to the jQuery event documentation: 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. Custom events allow you to define a JavaScript event name to listen to. Use this option only if the required event is not available in the list of drop-down events. The following site covers custom events in detail: https://learn.jquery.com/events/introduction-to-custom-events.

Selection Type

The event option will determine which events APEX needs to “listen” for. The Selection Type option and its corresponding object determine the objects 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 onChange DeptNo dynamic action will be triggered. There are five different selection types to choose from: Item(s), Button, Region, jQuery Selector, and JavaScript Expression.

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 actions, 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).

Similar to Item(s), when specifying a selection type of Button, you need to select a button from the current page. This allows you to easily control what happens when a user clicks a button in the page without submitting the page.

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, 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: www.talkapex.com/2011/01/missing-id-in-no-template-region.html. If using the new APEX 5 universal theme, this should not be an issue.

Instead of listening on APEX-specific objects such as items or a region, you can specify a jQuery selector or a JavaScript expression. In most cases, the jQuery selector should be sufficient; however, they are cases when you want to use JavaScript expressions for more complex selections.

For example, if you wanted APEX to perform a dynamic action each time someone moved their mouse over an HTML element with a class of highlight-me, you would select jQuery Selector and enter .highlight-me, as shown in Figure 8-18. The jQuery Selector option uses jQuery notation. You can find detailed information about the jQuery selector notation on the jQuery API site: http://api.jquery.com/category/selectors.

If JavaScript Expression is selected, it expects a DOM object, an array of DOM objects, or a jQuery object. Examples of a DOM object are objects such as document and window. The jQuery object can be any jQuery object such as a tree traversal. An example of this is using $(’p’).children() to select all the children of paragraph (p) elements. You can find more information about jQuery tree traversals here: http://api.jquery.com/category/traversing/tree-traversal/.

Condition

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

In the example, the condition (previously shown in Figure 8-16) is set to “is not null.” This means that each time the triggering element P1_DEPTNO is changed, APEX will evaluate it to see whether it is null. 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).

Figure 8-19 shows a list of conditions. All conditions, except for “is not null” and “is null,” require that you enter some additional information in the Value(s) field.

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.

• this.triggeringElement: The DOM object that triggered the dynamic action. this.triggeringElement.value will give you the value of the triggering element. If you defined multiple objects for Selection Type, this will let you know which one was triggered.
• this.browserEvent: The event object that caused the dynamic action to run. this.browserEvent.type will give you a string value of the type of event that occurred. If this were used in the example, this.browserEvent.type would have been “change.”
• this.data: Additional data that can be passed from the event. In most cases, this value will be null. Dynamic action plug-ins may populate this field to pass additional data.

If you want to quickly see all the additional information that is available in each of the attributes listed previously, set the condition to “JavaScript expression” and in the Value field enter console.log(this);, as shown in Figure 8-20. 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 8-21.

To demonstrate a condition that uses a JavaScript expression, add an additional Number Field item on page 1 called P1_X. Change the condition in the OnChange DeptNo dynamic action from “is not null” to JavaScript Expression. In the JavaScript Expression text area, enter this.triggeringElement.value > apex.item(’P1_X’).getValue(), as shown in Figure 8-22. Refresh the page and enter 20 in the P1_X field. When you change the department, the list of employees will appear only when you select Operations (40) and Sales (30). You’ll notice that if you change the value of P1_X, the condition will evaluate without having to submit the page or set the value in session state.

Advanced

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 8-23.

• Static: The default method that APEX attaches events to objects with is the bind method. Static means that the dynamic action will be run each time the event occurs on the object. If the object is replaced, the event is no longer attached to the object (it’s considered a new object), and the dynamic action will not be triggered. An object can be replaced during a partial-page refresh on a report or interactive report.
• Dynamic: Dynamic is similar to the bind option except that the event will be attached to the object for the lifetime of the page or any new objects of that type are added to the page. If a dynamic action is attached to a row in an interactive report, then this option will ensure that the dynamic action will be triggered each time the interactive report is refreshed.
• Once: If you want a dynamic action to fire only once, select this option. For example, you would use this option if you wanted to display a warning message the first time the user selected a department. Otherwise, it may get annoying to the user to consistently see the same warning message. If the action dynamic action is set to trigger on page load and is executed during the page load, it will still run one more time when its event is triggered.

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.

Actions

Prior to APEX 5, the True and False actions used were modifiable on the Dynamic Action edit page. Starting with APEX 5, they are now visible in the left pane under each dynamic action, as shown in Figure 8-24. They contain actions to perform based on the dynamic action’s condition. If multiple actions exist in each section, they will be synchronously executed in order (unless specified), determined by their sequence number.

Earlier in this chapter, you created the OnChange DeptNo dynamic action. The True/False Actions steps allowed you to define True and False actions (see Figure 8-8).

To help describe the options available when editing an action on the right pane, edit the True (Show) action by clicking it in the left pane, as shown in Figure 8-25. The action’s properties are now available in the right pane, as shown in Figure 8-26. The following subsections will describe all the options available when modifying an action.

Identification

The Identification section allows you to select the action that the action will perform. The options in the Action select list are broken up into six categories, as shown in Figure 8-27. The categories have no impact on the system and are there to help organize the list of available actions. This list also includes plugin dynamic actions that are suffixed with [Plug-in]. When the Action option selected, click the Help tab in the central pane to get 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.

Settings

The Settings section is available only for certain actions. Each Settings section is different depending on the action selected. In the example, the only available option is to show all page items on the same line. This section will cover the settings options for two different action types: Execute JavaScript Code and Execute PL/SQL Code.

Execute JavaScript Code: When the action is set to Execute JavaScript Code, the Settings section contains a text box where you can enter some JavaScript code to run. To help, APEX provides the this object that contains five different elements. this.triggeringElement, this.browserEvent, and this.data were already covered in the “Dynamic Actions Condition” section.

• this.action: This contains information about the action along with some additional information such as action attributes. Action attributes are useful in plug-in development. Please refer to Chapter 12 for more information about plug-ins.
• this.affectedElements: This is a jQuery object array of all the elements that should be affected as part of this action. If your JavaScript code needs to modify anything on the page, you should reference this object to find out which elements to modify. The affected elements are defined in the Affected Elements section that will be covered in the next subsection.

You can get an overview of these objects by clicking the Code label and clicking the Help tab in the central pane. To explore all the options available, enter console.log(this); in the Code section, refresh your page, trigger the dynamic action, and then look at the console window.

Execute PL/SQL Code: When the action is set to Execute PL/SQL Code, APEX will send an AJAX request to the database to execute the block of PL/SQL code. You can reference page and application items using bind variables in this block of code. It’s important to remember that the page and application items are the values in session state, which may not be the same as the values currently displayed on the page.

To submit page items as part of the AJAX request, enter them as a comma-delimited list in the Page Items to Submit field. If any of the items submitted as part of the action have session state protection enabled, the action will fail since the item requires a checksum, which is not provided in AJAX requests. This is done for security reasons to prevent malicious users from tampering with data.

Values from session state (page and application items) can be returned by the PL/SQL code by entering the item names in the Page Items to Return field. When doing so, the item’s value on the page will automatically be updated with the value in session state at the end of the action.

Affected Elements

The Affected Elements section allows you to define which elements on the page are impacted by the dynamic action. This section will show up only for actions that can affect an object on the page. In the example, the affected element type was Item(s) on P1_EMPNO since it needed to be shown and hidden. The different types of affected elements are as follows:

• Item(s): This is the comma-delimited list of items that will be affected by the action.
• Button: Select a button that will be affected by the action.
• Region: Select a region from the drop-down list. The list of regions will include both the current page regions and regions on page 0 (in other words, the global page).
• jQuery selector: This is a jQuery selector that can select multiple elements on the page. Read http://api.jquery.com/category/selectors for more information and examples.
• JavaScript expression: This is a DOM object, an array of DOM objects, or a jQuery object. Examples of a DOM object are objects such as document and window. The jQuery object can be any jQuery object such as a tree traversal. An example of this is using $(’p’).children() to select all the children of paragraph (p) elements. You can find more information about jQuery tree traversals at http://api.jquery.com/category/traversing/tree-traversal.
• Triggering element: The triggering element is the element that was defined in the When section for the dynamic action. In the example, it is P1_DEPTNO.
• Event source: The event source is the specific element that triggered the dynamic action to fire. This may be the triggering element or a child of the triggering element. For example, suppose that you created a dynamic action for a click event on the Select Employee region. If you click a blank part of the region, the event source will be the region itself, which is the same as the triggering element. If you click one of the select list items, the event source will be the select list (P1_EMPNO or P1_DEPTNO) since that is the element that caused the dynamic action to run.

Not all actions require or allow for affected elements to be defined. For example, it doesn’t make sense for the Alert action type, which triggers a pop-up notification, to have any affected elements.

Execution Options

The Execution Options section (as shown in Figure 8-28) determines when to run the action based on the dynamic action’s condition. An action can be run when the condition is either true or false. Setting the value to True or False will determine which section the action is listed in, as shown in Figure 8-25.

You can choose whether to fire the action once the page is loaded. 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 during the page load. For example, both of the actions in the OnChange DeptNo 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 at the time the dynamic action is executed. Some actions, such as Execute PL/SQL Code and Set Value, allow you to select additional attributes: Stop Execution On Error and Wait for Result, as shown in Figure 8-29.

• Stop Execution On Error: 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.
• Wait for Result: This determines whether this action should be run asynchronously. If no other dynamic action is dependent on this action being run, set to Yes.
  • Future versions of APEX will use asynchronous AJAX requests, and this attribute will be deprecated. See http://docs.oracle.com/cd/E59726_01/doc.50/e39143/toc.htm#HTMRN313 for more information.

Dynamic Actions in Action

The example that was used in the previous sections was a basic Show/Hide dynamic action. This section will cover how to create more complex dynamic actions. All the available actions won’t be covered in this chapter; however, this example will make you familiar with some of them and how they can interact with one another. A final copy of this example is included in the book’s files as an application. The file is 08_example-2_finished_application.sql.

Business Case

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 as follows:

• When a user selects the department, a modal window is displayed with a report listing all the employees in the selected department. The report will include the employee’s name, job, hire date, and salary.
• When the user hovers over a report row, the row will be highlighted yellow.
• If the user clicks a row in the report, the employee’s number is stored in a hidden field, and the employee name is selected for P1_EMPNO.
• Immediately after an employee is selected, the name should be bold for a few seconds to emphasize that it has been selected.

Using dynamic actions, you’ll be able to implement all these requirements. To simplify the solution, it has been broken up into small sections.

Setup

Before 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 08_example-2_base_application.sql.

1. Change the P1_EMPNO type to Text Field. Leaving it as a text field will help debug any issues with the dynamic action, and later in this example it will be set to hidden.
2. Create a new field called P1_ENAME and set its properties as the same as in Figure 8-30. This field will be used to display the selected employee’s name.

   

   Figure 8-30. P1_ENAME properties

3. Remove the existing dynamic action, which is onChange DeptNo, that is currently attached to the P1_DEPTNO item.

Create Department Employees Report

To meet the first requirement, create a Classic Report region that lists the employees in the selected department. To create this report, follow these steps:

1. Create a standard report region called Department Employees using the following query:

   select e.empno,
          initcap(e.ename) ename,
          initcap(e.job) job,
          e.hiredate,
          e.sal
   from emp e
   where e.deptno = :p1_deptno

2. Modify the region’s attributes and set Page Items to Submit as P1_DEPTNO, as shown in Figure 8-31.

   

   Figure 8-31. Region’s Source

3. Modify the report column attributes so that EMPNO is not displayed by setting its column type to Hidden Column.
4. Some additional attributes need to be added to the ENAME column that will be used to send data to P1_EMPNO and P1_ENAME when the user clicks a row in the report. To edit the ENAME column, click the column name in the left pane, and its properties will be in the right pane. In the Column Formatting section, enter <span data-empno="#EMPNO#" data-ename="#ENAME#">#ENAME#</span> in the HTML Expression field, as shown in Figure 8-32. The HTML Expression field allows you to customize the appearance of each column.

If you refresh page 1, it will look like Figure 8-33. If you change the department, nothing happens, since you haven’t applied any dynamic actions.

Refresh Department Employees Report

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:

1. In the left pane, right-click the P1_DEPTNO page item and select Create dynamic action from the content menu.
2. Modify the dynamic actions properties as follows:
   • Name: onChange DeptNo
3. Modify the True Action (currently set to Show by default) properties to the same configuration in Figure 8-34. The items to change are highlighted.

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

Highlight Row

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 CSS styles for a column in the department employee’s table when you hover over it, the style changes to Figure 8-36.

Using the CSS definition from Figure 8-36, you can modify the CSS to highlight the row when you move it to yellow. The new CSS should look like the following code sample (where REGION_ID is the region’s ID). Adding #REGION_ID restricts the new highlight rules to just the Department Employees report.

/* Using the DEPT_EMP_REPORT id ensures that this highlighting will only affect the
 Department Employees report */
#<REGION_ID> .t-Report--rowHighlight .t-Report-report tr:hover .t-Report-cell{
  background-color: yellow !important;
}

Normally you would include the CSS in the page’s inline CSS area by selecting Page 1 in the left pane and then modifying its properties in the right pane. Figure 8-37 shows where to include the custom CSS. If you want to make the CSS available to the entire application, you can modify the custom CSS option in the Theme Roller, as shown in Figure 8-38.

For the purpose of this example, inline CSS will be “injected” into the application using a dynamic action.

1. In the left pane, click the Dynamic Actions icon (see Figure 8-3). Right-click the Page Load folder and select Create Dynamic Action. As the name suggests, this dynamic action will be executed once the page has loaded.
2. Change the dynamic actions name to onPageLoad.
3. Modify the True action (currently set to Show). Set the Action and Affected Elements properties, as shown in Figure 8-39.

   

   Figure 8-39. onPageLoad Action configuration

4. Use the following code snippet and put it in the action’s Settings Code text area. Note that the code does not reference the Department Employees region at all; rather, it references the this.affectedElements jQuery object. By doing so, this leverages APEX’s declarative dynamic action functionality. Referring to the region also means that only the Department Employees region will be affected with the yellow highlighting.

   var regionId = this.affectedElements.attr(’id’);
   
   var css = ’#REGION_ID .t-Report--rowHighlight .t-Report-report tr:hover .t-Report-cell{ background-color: yellow !important; }’;
   
   css = css.replace(’REGION_ID’, regionId);
   
   $(this.affectedElements).prepend(’<style type="text/css">’ + css + ’ </style>’ );

If you refresh the page and hover over each row, you should notice that the current row is highlighted in yellow, as shown in Figure 8-40. You can change the color by modifying the value in the dynamic action’s JavaScript code.

Row Click

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 8-41.

The following steps will create the dynamic action that will handle the row click event:

1. Create a dynamic action on the Department Employees region.
2. Make the changes highlighted in Figure 8-42 to the newly added dynamic action. The event scope was changed to Dynamic since the report will be refreshed after each change in department. If the dynamic action were to remain static, it would not work after the first report refresh.

   

   Figure 8-42. onClick Emp dynamic action configuration

3. Set the dynamic action’s Condition field to the following code. Without this condition, the dynamic action will fire on any click event in the entire region (not just in the visible employees table). Adding this condition ensures that only clicks in a row containing an employee will trigger the actions.

   $(this.browserEvent.target).closest(’tbody’, this.browserEvent.currentTarget).length > 0

4. Modify the True action to the settings highlighted in Figure 8-43.

   

   Figure 8-43. onClick Emp True action

5. Add the following code to the Settings Code field, and it will set P1_EMPNO and P1_ENAME. In this example, the values are being set with JavaScript. Alternatively, two actions to set the values could have been used.

   //dataSpan will represent the span tag that was created earlier
   //which contains the custom data attributes
   var dataSpan = $(this.browserEvent.target).closest(’tr’).find(’[data-empno]’);
   
   //Set the EMPNO and its display values using the data attributes
   apex.item(’P1_EMPNO’).setValue(dataSpan.data(’empno’));
   apex.item(’P1_ENAME’).setValue(dataSpan.data(’ename’));

If you refresh the page and click a row in the Department Employees region, the associated employee’s name should be displayed beside the Employee label, and P1_EMPNO will be populated accordingly, as shown in Figure 8-44.

Once you confirm that everything is working, change P1_EMPNO to a hidden field. Since you’re modifying its value in JavaScript, change the Value Protected option on the item to No.

Emphasize Employee Change

The displayed employee name needs to be emphasized after the employee has been selected. To emphasize the name, immediately hide the employee name, make it red, and then have it fade in. Once the fade-in is complete, remove the highlighted red color.

There are various ways to do this in dynamic actions. You could modify the existing dynamic action and append some additional JavaScript. The following steps will help highlight another type of action and how multiple actions work within a dynamic action:

1. Create a new action in the onChange Emp dynamic action and set its properties to Figure 8-45.

   

   Figure 8-45. Set Style action

2. In the left pane, drag the newly created action above the existing Execute JavaScript Code action so that it runs first. Figure 8-46 shows the new order.

   

   Figure 8-46. Updated dynamic action execute order

3. Add an additional JavaScript action at the end of the current actions with the following configurations:

   - Action: Execute JavaScript Code

   - Affected Elements > Selection Type: Item(s)

   - Affected Elements > Item(s): P1_ENAME

   - Fire On Page Load: No

4. Set the Settings Code field to the following:

   this.affectedElements.hide().fadeIn(2000, function(){
     //The second parameter in the fadeIn function allows you to define a
     //function to be run once the fadeIn is completed.
     //This function will be used to reset the color
     $(this).css(’color’, ’’);
   });

Refresh Page 1, select a department, and then click an employee in the Department Employees report. When the name appears in the Employee field, it should fade in and be red. Once the fade-in is complete, it should return to its original color (black in this example).

Modal Window

So far all the requirements have been met except for the modal window. Because it is easier to develop, debug, and demonstrate the example without the extra complexities of a modal window, I saved this for last.

Similar to other requirements in this example, there are several ways to implement this solution. One option would be to use the new APEX 5 modal page feature; however, it would add unnecessary complexity to the application.

Instead, this solution will take advantage of some of the features found in the new APEX 5 Universal theme. This solution will leverage the jQuery UI Dialog widget (https://jqueryui.com/dialog/), which is already included in APEX 5. This solution will use a simple command to open and close the dialog window. You can find more options in the jQuery UI Dialog API documentation: http://api.jqueryui.com/dialog/.

1. In the left pane, click the Department Employees region. In the right pane, edit the Template to Inline Dialog, as shown in Figure 8-47. This built-in template uses the jQuery UI Dialog widget.

   

   Figure 8-47. Modify region’s template

2. Click the button Use Template Defaults, Medium (600x400), as shown in Figure 8-47. This will display a new modal window to edit the Inline Dialog template’s properties. Change Dialog Size to Small, as shown in Figure 8-48.

   

   Figure 8-48. Template Options

3. Refresh Page 1, and you’ll notice that the Department Employees region is no longer visible on the page. That is because it is a jQuery UI Dialog window, which needs to be opened and closed using JavaScript.
4. To open the dialog window, add another True action to the onChange DeptNo dynamic action. Modify the new action’s properties to look like Figure 8-49.

   

   Figure 8-49. Dialog open dynamic action properties

5. Use the following for the Code property:

   this.affectedElements.dialog(’open’);

6. To close the dialog window, add another True action to the onClick Emp dynamic action. Modify the new action’s properties to look like Figure 8-49.
7. Use the following for the Code property:

   this.affectedElements.dialog(’close’);

Refresh Page 1 to view the changes. When you change a department, the Department Employees region should appear as a modal dialog window. When you select an employee, the employee name gets updated, and the Department Employees region closes.

Summary

This chapter covered all aspects of dynamic actions, such as how to create a dynamic action and all the options available when configuring a dynamic action. The last section demonstrated several kinds of dynamic actions and how they can work with one another.