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:
Note how this is similar to the current way of getting a handle on regions:
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.
apex.regions["unconventional-id"]. We do however recommend you keep your static IDs simple, like “
emp” or “
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
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.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;
.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.
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
A screenshot of the browser console is worth more than a thousand words, so here it is:
Notice the presence of
APEX_VERSION. To be consistent, we are using the same names as the bind variables used in the back-end.
You will also notice
WORKSPACE_FILES, which are new names. We wanted to add the
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|
|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.
Thanks for the explanation! I added them to my development notes 🙂
Extremely helpful information, I love the “ahm, what was my static ID again?” I don’t know how many times I have done that. Thank you for sharing!!