JavaScript API Enhancements in APEX 21.2 #JoelKallmanDay

For this year’s #JoelKallmanDay, I’m excited to tell you about some enhancements we’re bringing to the JavaScript API-s in APEX 21.2, which is right around the corner. In this release specifically, we’ve looked at bringing more structure to certain API-s and making them simpler to use. I will only cover some of the enhancements here. For even more JavaScript goodness, also read John Synders’ blog post.

apex.regions

apex.regions is a new member of the apex namespace. It is a collection of the regions on the page, indexed by the region ID. To demonstrate, say your page has an Interactive Grid with static ID “emp”- you could use it as such:

apex.regions.emp.refresh();

Note how this is similar to the current way of getting a handle on regions:

apex.region("emp").refresh();

The new way offers some nice benefits:

• It is shorter to type, even if by only 2 characters
• It requires fewer special characters like parenthesis or quotes
• Because the region ID is not passed in as a string parameter, both the code editors in the builder and the browser console are able to autocomplete it. No more “ahm, what was my static ID again?”

Having such a collection in place also allows us to get more information about the page without having to query the DOM. For example, this is how you could go about refreshing all Interactive Grids on the page, without having knowledge of how many there are, or and their static ID-s:

Object.values( apex.regions )
.filter( region => region.type === "InteractiveGrid" )
.forEach( region => region.refresh() );

Note that only the regions which have internally implemented the region interface are part of this collection. This consists of most native regions or plug-ins you would be interested in interacting with anyway, but static regions for example are not yet included. We can revisit this decision in future releases.

Also note that not all valid region static IDs are also valid JavaScript identifiers, so you might at times have to pass in the ID as a string, e.g.: apex.regions["unconventional-id"]. We do however recommend you keep your static IDs simple, like “emp” or “myFacetsRegion”.

apex.items

In similar fashion to apex.regions, there is also a collection of the items on the page under apex.items. The same benefits from above apply to having the items be part of a collection as well.

apex.items.P1_EMPNO is just easier to type than apex.items("P1_EMPNO")

In another example, this is how you could go about hiding all Number Fields on the page:

Object.values( apex.items )
.filter( item => item.item_type === "NUMBER" )
.forEach( item => item.hide() );

In contrast to apex.regions, apex.items includes all native item types, as they all implement the item interface. Most 3^rd party plug-ins will probably be included as well.

But wait, there’s more! We have also added a shorthand for getting and setting item values. Simply read the value property of the item or assign it a new value. Here are both enhancements working together:

// getting an item’s value:
var sal = apex.item("P1_SAL").getValue();
// is the same as
var sal = apex.items.P1_SAL.getValue();
// is the same as
var sal = apex.items.P1_SAL.value;

// setting an item’s value:
apex.item("P1_SAL").setValue(100);
// is the same as
apex.items.P1_SAL.setValue(100);
// is the same as
apex.items.P1_SAL.value = 100;

Note that .setValue() is still more powerful than .value =, as you can optionally also pass in a display value for items that support it, or pass in a flag to suppress the change event. In the vast majority of cases however, .value will suffice. Also note that reading the value property will return the same as getValue(). Sometimes, you might be interested in calling .getNativeValue() instead, as in the case of number fields.

apex.env

Last but not least, we’re also adding some structure to the app and page metadata available in the front-end. No more calling $v(“pFlowId”) to get the current app ID or reading the global apex_img_dir to get the path to the instance files. Not to mention how the current username has always been missing. All of this information will now live in the object apex.env.

A screenshot of the browser console is worth more than a thousand words, so here it is:

Notice the presence of APP_USER, APP_ID, APP_PAGE_ID, APP_SESSION and APEX_VERSION. To be consistent, we are using the same names as the bind variables used in the back-end.

You will also notice APEX_FILES, APP_FILES and WORKSPACE_FILES, which are new names. We wanted to add the IMAGE_PREFIX, APP_IMAGES and WORKSPACE_IMAGES to this object as well but decided not to introduce new functionality using these unintuitive, legacy names. “Images? But we can save any type of file. Prefix? But why only for the instance files?”

Therefore, we have introduced some new substitution strings both in the back-end and front-end, to stay consistent. Here’s a quick summary:

Legacy Name	New Name	Present in apex.env
IMAGE_PREFIX	APEX_FILES	Yes
WORKSPACE_IMAGES	WORKSPACE_FILES	Yes
APP_IMAGES	APP_FILES	Yes
THEME_IMAGES	THEME_FILES	No
THEME_DB_IMAGES	THEME_DB_FILES	No
PLUGIN_FILES	None- has always had a good name	No

Don’t worry, the legacy names will continue work for a long time. But we do recommend starting to use the more intuitive new names, both in the back- and front-end.

---

APEX 21.2 will bring a lot of enhancements to the JavaScript API-s and we can’t wait for you to try them out. As always, feedback is welcome- so please reach out to us in all the usual places. In case you have another idea or feature request you should also check out our new ideas app.