Add JavaScript Your Way, Part 1

Choose the best option for adding JavaScript to your Oracle APEX applications.

By Dan McGhan

December 18, 2019

With Oracle Application Express (Oracle APEX), a low-code development platform, it is possible to create complete applications without writing a single line of code. But just as SQL and PL/SQL enable APEX developers to better leverage the database back end, JavaScript is key to making applications more interactive in a web browser.

In this two-part article, I’ll walk you through several options for adding JavaScript to APEX apps, including dynamic actions, dynamic actions with JavaScript hooks, page- and component-level attributes, and application files. Think of these options as a progression, with each one requiring more knowledge of JavaScript, APEX’s JavaScript APIs, and web development in general. New APEX developers should start by learning dynamic actions and progress to subsequent options only when they are ready and the application requirements cannot be satisfied without a more advanced approach.

Keep in mind that adding JavaScript to your applications can mean some extra risk when you’re upgrading APEX. This is because the HTML generated by the APEX engine can change with new releases. JavaScript code that is dependent on the HTML (structure, IDs, classes, and so on) from one APEX version may stop working until the code is updated to accommodate the changes in a new version. Here are a few tips for minimizing any JavaScript and APEX compatibility issues:

• 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.

Dynamic Actions

It’s often said that the most efficient way to do something is not to do it at all. The dynamic action framework extends that logic to adding JavaScript to your APEX applications. With dynamic actions, developers define interactive behavior by using declarative menus, and the APEX engine then generates the necessary JavaScript and adds it to the web page at runtime.

Using purely declarative dynamic actions (those without JavaScript hooks) dramatically reduces the risk associated with upgrading to a new version of APEX. This is because the APEX development team coordinates changes in the HTML output with the JavaScript generated at runtime.

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:

• What’s the driver (component + event)?
• Is there a client-side condition?
• What are the true and the false actions?
• Is the page load event relevant in addition to the main event?

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.

In part 2 of this article, I will describe how to add JavaScript to APEX apps by using dynamic actions with JavaScript hooks, page- and component-level attributes, and application files.

Next Steps

LEARN more about JavaScript and Oracle.

TRY Oracle Cloud Free Tier.

READ Add JavaScript Your Way, Part 2

Illustration by Wes Rowell