By Dan McGhan
December 18, 2019
Be conservative in assumptions about APEX-generated HTML. Try to utilize your own custom HTML whenever possible.
Stick to documented APEX APIs. If an API is not documented, it’s not supported.
Avoid deprecated APIs (including those from third-party libraries such as jQuery). See the release notes for new versions of any libraries you’re using to learn about deprecated APIs.
I like to think of dynamic actions as having two parts: the dynamic action itself (think of this as the parent) and the actions attached to it (think of these as children). The dynamic action is where developers specify when something should happen based on an event, such as when a user clicks a button or changes an item’s value. An optional client-side condition can be specified along with the event, perhaps checking the value of an item before running any actions.
Actions specify what should happen when the dynamic action is triggered. There are lots of different actions to choose from, but people usually start with simple ones that have equal opposites, such as hide/show or enable/disable. If a dynamic action has a client-side condition, it’s possible to configure some actions to fire when the condition is true (true actions) and others that fire when the condition is false (false actions).
To demonstrate creating a dynamic action, I’ll use this Customer Details form from the sample database application:
Suppose you want to configure the form so that the Alternate Number field is disabled until the Phone Number field includes a value. Dynamic actions are perfect for implementing this type of interactive behavior, but before diving into the implementation, I recommend answering the following questions to help guide the creation of the dynamic action:
In this case, the answer to the driver question is the Phone Number field, because its value is determining what should happen elsewhere on the page. More specifically, the driver is the
change event on the Phone Number field. The condition is whether the value of Phone Number is null, which creates a fork between true and false actions. If the condition is true, the action is to disable the Alternate Number field, and if it’s false, the action is to enable the Alternate Number field.
The last question is whether the page’s
load event is relevant in addition to the
change event of the Phone Number field. When the HTML generated by APEX is sent to the browser, the Alternate Number field will be enabled by default. Even though the user has not changed the value of Phone Number, the dynamic action still needs to run to disable the Alternate Number field as needed. APEX will choose a smart default for Fire on Initialization, based on the type of action selected, but developers should be aware of the option for cases when the default needs to be overridden.
Note: If you’d like to follow along with the steps in this article, go to the APEX App Gallery and install the sample database application in your workspace. When the installation completes, run the app, navigate to the Customers page, and click the name of a customer to view the form.
To start the creation of the dynamic action, navigate to the Page Designer for the form page. On the Rendering tab on the left, right-click the P7_PHONE_NUMBER1 item (the driver) and select Create Dynamic Action.
On the Dynamic Action tab on the right, set Name to P7_PHONE_NUMBER1 changed. I generally recommend basing a name for a dynamic action on the driver rather than on the actions, because there are often many actions.
Note that Event, Selection Type, and Item(s) were all correctly selected because I started creating the dynamic action by right-clicking the driver. Open the Event select list to see the other events available, before continuing.
Just below the When attributes are the Client-side Condition attributes, where you can create the fork between true and false actions. In that section, set Type to Item is null. The Item field will correctly default to P7_PHONE_NUMBER1.
With the dynamic action settings configured, you’re ready to configure the actions. Return to the Rendering tab on the left, and click the Show action (created by default) to select it.
The action’s settings are on the right on the Action tab. Open the Action select list to see the available actions, and select Disable. Next, set Item(s) to P7_PHONE_NUMBER2, because that’s the field that should be disabled when the condition at the parent level is true.
There’s also a Fire on Initialization setting, which enables you to specify whether the action should execute when the page loads. Leave this setting enabled (the default), because you want P7_PHONE_NUMBER2 to be disabled when the page loads, if the condition is true.
With the true action configured, the only thing left to do is create the false action. Because the Disable action has an opposite action (Enable), APEX makes it very easy to create. Return to the Rendering tab (on the left side), right-click the Disable action, and select Create Opposite Action from the menu. This will create the Enable action under the False Actions branch.
If you save your changes and run the application page, you’ll see that the Alternate Number field is now disabled if the value of Phone Number is null. As is apparent, it’s quite easy to add dynamic behavior to your applications without writing any code, using dynamic actions.
Illustration by Wes Rowell