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?
Autocomplete in the builder
Autocomplete in the console

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 3rd 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 NameNew NamePresent in apex.env
IMAGE_PREFIXAPEX_FILESYes
WORKSPACE_IMAGESWORKSPACE_FILESYes
APP_IMAGESAPP_FILESYes
THEME_IMAGESTHEME_FILESNo
THEME_DB_IMAGESTHEME_DB_FILESNo
PLUGIN_FILESNone- has always had a good nameNo
New substitution strings in APEX 21.2

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.

4 Comments

Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s