3.5 Adding Interactivity to Pages

Add interactive behavior to your pages using Dynamic Actions.

Define one or more dynamic actions to run in response to an event that happens while a user interacts with the page. Common events include the change in value of a page item or selection of a list, the closing of a modal dialog, refreshing of a region, and many others. Button and menu clicks can use Triggered Actions. Handle all other events by defining a Dynamic Action event handler. APEX offers a large set of native dynamic actions that you can extend by using dynamic action plug-ins.

Some dynamic actions modify aspects of the page in the browser like showing or hiding items and enabling or disabling them. Other ones engage the APEX server to refresh a region's data or execute server-side code. Any actions involving a server request support declaratively sending the latest values of page items or report columns to the server. Just set the Items to Submit property to a comma-separated list of item or column names. While a report region's primary key column is always available to send, enable other columns' Available on Client setting as needed. Since the Execute Server-side Code dynamic action can also modify page item values, list any you want APEX to update in the page in the companion Items to Return property.

In the patients search page we're studying, recall that when the cards region is refreshed, the map region should also get refreshed. The event named Page Change [Cards] fires when a cards region is refreshed, so you can define a dynamic action related to this event to get the job done.

You'd start by selecting the Search Results region, and choosing Create Dynamic Action from the context menu. Then in the Property Editor you select the Page Change [Cards] event. You can give the dynamic action event handler a name like When Results Refreshed to make the intent more clear to colleagues who might have to enhance the page in the future. The set of built-in action types includes ones to hide or show elements, refresh elements, enable or disable elements, set or clear the value of items, execute custom code in the client or server, and many others. In this case, you need the one to refresh the Map region. So, you configure the type of the related action to be Refresh and set Map as the region to refresh. Those few clicks make the map automatically refresh whenever the cards region results change.

End users would definitely appreciate if the map would zoom and center itself around the filtered list of patients to display to save them having to do manual adjustments. Since a dynamic action is one of the kinds of plug-in components members of the APEX community can create and distribute, imagine you find a Center & Zoom Map Around Points dynamic action plug-in on apex.world or as part of a blog article or tutorial.

You can download and import it into your APEX app to put it to use. You select the Map region in the component tree and again choose Create Dynamic Action. You name this second event handler When Map Refreshed and set it to react to the After Refresh event on the Map region. Finally, you define the dynamic action to be of type Center & Zoom Map Around Points [Plug‑in]. The figure below shows the result in Page Designer.

Figure 3-24 Dynamic Actions Add Interactive Behavior

Description of "Figure 3-24 Dynamic Actions Add Interactive Behavior"

Now at runtime, as shown below, as the end-user fine-tunes their patient search both the cards and map regions reflect the narrowed results, and the map adjusts to fit the remaining patients' locations into the view.

Figure 3-25 Map Reflects Filtered Result and Auto-Centers and Zooms

Description of "Figure 3-25 Map Reflects Filtered Result and Auto-Centers and Zooms"