All APEX developers should be aware of the APEX 5 new features in order to pass these features on to their users and to leverage new development efficiencies. All developers who have customized interactive report appearance, altered Actions, written IR dynamic actions or otherwise enhanced an IR in any earlier APEX version (most of us?) need to know the behind-the-scenes details of APEX 5.0 IRs. The changes are significant, and unless the APEX standard APIs have been used the customization may not upgrade smoothly.
As usual for a new APEX release, APEX 5 introduces new IR features: new and enhanced Acton Menu features, some cosmetic uplifts and some report management improvements. All of these are covered in Part 1 of this series. With APEX 5, the major IR changes are behind the scenes – APEX IRs have been rebuilt from the inside out. Both the “inside” changes – the JavaScript engine – and the “outside” changes- CSS classes and Ids – are significant. The important note for developers is that because of this re-architecting, even when developers used the APEX-standard dynamic action or plugin frameworks, if the customization code references the pre-APEX id’s and class elements, the customization code will need to be refactored to upgrade.
Why so many changes, and why such a drastic change? Several reasons. The revised IR code allows for:
- Multiple IRs on one page (perhaps the biggest new feature, to be described in detail in later sections of this paper)
- Modal dialogs
- The Universal Theme and Theme Roller customizations
- APEX overall usability and accessibility
These features, particularly multiple IRs on a single page, were just not possible with the pre-APEX IR architecture. The new code makes sense, when one considers that multiple IRs on a single page was not possible with the legacy IR structure – something had to change. With all of the other IDE and end-user interface changes in APEX 5, the IR changes make sense.
The downside is, developers who have tooled outside of the APEX sandbox must now invest some time in upgrading to the new IR structure and JavaScript. All IR customizations made outside of the standard APIs may not work in APEX 5. Developers who have made such changes will need to refactor their customizations.
The following sections discuss the APEX 5 IR structural changes in detail. The Know Your Users section applies to all developers, and is repeated here as a reminder that all configuration and customization should have one goal, to serve user requirements. The Changes section addresses the CSS and JavaScript changes such developers need to know to plan their upgrade to APEX 5.
Know Your Users
IRs are very powerful in that they deliver a lot of end user functionality with minimal developer effort. However, it is the developer’s responsibility to maximize IR effectiveness by using the declarative settings to tailor the IR to end user needs. This means the developer needs to be aware of such things as overall security needs, how user use the data set, which Action Menu features should be prohibited or restricted, how much training end users will require, which download options are required, and how users are likely to use Saved reports. It is the developer’s job to prepare and deliver the appropriate IR query and action set to support them. If customizations beyond standard IR features are required, they should first be implemented using standard APEX Pis, and only as a last resort achieved through custom coding.
In short, Know Your Users. Watch what they do, because what they really do is not necessarily what they say the do or need. Deliver the functionality they need, restrict the features they should not have, and ensure the data set they receive is useful to them.
Changes
Turn and face the strange ch ch ch changes …
D. Bowie
APEX IRs have been reengineered to accommodate multiple interactive reports on one page, and in keeping with the APEX5 overall style, usability and accessibility improvements. The underlying architecture is quite different than previous versions. It is important the developers understand these changes, particularly when adding dynamic actions, plugins or any other customizations.
CSS Changes
The main CSS changes are in a different pattern of class and id nomenclature. The old apexir_<element> id constructs are gone, replaced by a series of a-IRR-<element> classes and revised id names. Figure 1 shows the pre-APEX 5 IR HTML and CSS structure. Note the apexir_<element> id and class names. Figure 2 shows the APEX IR structure. Note the new [STATIC_ID]_<element> id name, and the a-irr-<element> class names.
Figure 1 – Pre-APEX 5 apexir_ Ids
Figure 2 – APEX 5 STATIC_ID_ Ids and a-IRR- Classes
The APEX 5 pattern is readily visible: apexir_<element> ids are now renamed to STATIC_ID_ <element>, where STATIC_ID is the static id of the IR region, whether it was declared by the developer or assigned by APEX, in which case it has the format R123456789012345. It is much easier to understand the underlying ID structure, especially when there are multiple IRs on the page, when declared static ids that make sense are used. There is a Static Id attribute on every IR – in earlier versions it was most often left blank. With APEX 5, the Static Id is important in passing filters to specific IRs, and in the structure of the IR itself.
JavaScript Changes
Pre-APEX 5, the APEX IR JavaScript is contained in the file widget.interactiveReport.js. Post APEX-5, the APEX IR JavaScript is contained in the file widget.interactiveReport.js. The similarity ends there…. well, almost. Reviewing the two files, one recognizes the same functions – actually widget methods – that correspond to the action menu actions, but the construction of the functions – the definition of the widget methods – is different, as is their implementation.
The Supported Way
The SUPPORTED way to influence APEX IRs is to “use the standard APIs”. That includes apexrefresh, and the APEX_IR API. Let’s see what we can do with these.
apexrefresh is the documented, supported way to refresh APEX components from JavaScript. That includes refreshing APEX IRs. The syntax is simple:
apex.event.trigger(‘#myIRRegionStaticID”, “apexrefresh”);
For more specific IR settings, use the supported, documented APEX_IR API (https://docs.oracle.com/database/121/AEAPI/apex_ir.htm for APEX 5). To user most calls of APEX_IR, one needs to get the region id of your interactive report. As simple example, the code sequence to programmatically reset an IR to its default configuration uses the APEX_IR.RESET_REPORT procedure: is:
DECLARE
v_region_id APEX_APPLICATION_PAGE_REGIONS.REGION_ID%TYPE;
BEGIN
SELECT region_d INTO v_region_id
FROM APEX_APPLICATION_PAGE_REGIONS
WHERE application_id = :APP_ID
AND page_id = :APP_PAGE_I
AND static_ic = ‘MY_IR_STATIC_ID’;
APEX_IR.RESET_REPORT(
P_page_id => :APP_PAGE_ID,
P_region_id => v_region_id,
P_report_id => NULL);
END;
Of course such code would be improved before production use by wrapping in a procedure, adding error catching and validations as needed for your situation.
In addition to the APEX_IR possibilities, there always the declarative RIR and CIR settings, discussed in Part I of this series in the Summer 2015 RMOUG SQL> UPDATE.
So we can do all the basics using supported, documented means. But what about our more complex situations, where we have already strayed into unsupported territory with IR enhancements in earlier APEX versions?
The UNSupported Way
In APEX 4.2 and earlier, when there is always only one IR on a page, the widget is attached to the gReport element – the IR – and there is always only one gReport element on the page. One can inspect the JavaScript on the page and readily see calls to widget functions.
For example, inspection of the Search Column icon, shown in Figure 21, clearly shows the onclick action is a call to gReport.dialog2(“SEARCH_COLUMN”).
Figure 3 – APEX 4.2 gReport.dialog2 Call on Search Column Icon
Further inspection of the IR JavaScript and HTML reveals that gReport.dialog2(‘parameter’) is the widget method for opening the ‘parameter’ dialog window, where ‘parameter’ values correspond to the Action Menu options.
Inspection of the APEX 4.2 Go button on the toolbar shows us the gReport.search call, shown in Figure 4.
Figure 4 – APEX 4.2 IR Toolbar Go Button gReport.search Call
With APEX 4.2, because we can clearly see how these two widget methods, gReport.dialog2 and gReport.search are used, we are actually quite confident in using them in our customizations, even when we know their direct use is unsupported. This is jQuery in APEX – we trust that this stuff is solid. 🙂
Well, in APEX 5, the familiar gReport.dialog2(…) and gReport.search(…) functions calls are not there. In fact, the familiar gReport element is not there at all. Figure 5 shows the IR Toolbar Go button HTML in APEX 5. No gReport in site – no jQuery is visible here.
Figure 5 – APEX 5 IR Toolbar Go Button – No gReport.search!
Note again that all out-of-the-box APEX IRs will automatically use the new jQuery widgets, seamlessly. The problem is, in APEX 5, all calls to the undocumented gReport stuff do not work. Any customization that makes gReport method calls, or extends the interactive report widget will need to be refactored.
So how do things match up? What replaces gReport? Let’s go back to some jQuery UI widget basics. The APEX team has used the jQuery widget factory to build (rebuild) the interactive report and action menu widgets (and many others within APEX 5).
The best reference I have found on jQuery UI widgets is on jQuery UI, How to Use the Widget Factory, at https://learn.jquery.com/jquery-ui/widget-factory/how-to-use-the-widget-factory/ If you are not familiar with jQuery widgets and the jQuery widget factory, this how-to article will help understand jQuery widgets in general, which will help you understand how the APEX interactive report and action menu widgets work.
Note: If you are not familiar with jQuery and jQuery UI widgets, then seriously consider NOT making any unsupported customizations to the APEX IR widgets, at least until you learn more and become entirely confident in your ability to support yourself and your code. This post does not contain sufficient information to make your first customization attempt.
The best reference for explaining how the APEX 5 IR widget works is by John Snyder, at http://hardlikesoftware.com/weblog/2015/05/12/apex-5-0-interactive-report-customization/.
Armed with the information in these two articles, we can figure out our APEX 5 IR widget code.
Widgets are attached to DOM elements. Widget methods are the functions that define what the widget does – the actions. Methods prefixed with _ are private methods. Every widget has an options method that lists the options (attributes). To view all options, use the option keyword:
$(selector).widgetName("option");
To view a specific option, simply state the option:
$(selector).widgetName(“option”, "optionname");
Adding a second parameter sets the value of the option:
$(selector).widgetName(“option”, "optionname",100);
The basic call to a widget method takes the format
$(selector).widgetName("method");
If the widget method has parameters, add the parameters after the method name:
$(selector).widgetName("method", “param_1”, “param_2”);
Now let’s apply that context to our APEX IR.
The key information John gives us is that in APEX 5, the IR widget appends “_ir” to the static id of the IR, and “_actions_menu” to the actions menu widget . So if my IR has a static id of DEMO_IR, we know the ids for the IR widget and for the IR actions menu. To view all the options for these widgets, in the Console window use these commands:
$(“#DEMO_IR_ir”).interactiveReport(“option”);
to show all the IR widget options, and
$(“#DEMO_IR_actions_menu”).menu(“option”);
to show all the action menu options.
There are quite a few options for both – to learn more about the IR and action menu widgets, definitely run these jQuery commands in your browser Developer Tools Console window. View the options, then experiment with calling some of the options. The IR widget options correspond to the IR attributes. The menu widget options correspond to the IR action menu options, and the iems correspond to the menu actions. These will be familiar to developers who are familiar with IR settings.
The IR widget options include: actionsMenu, afterRefresh, aggregate, chart,columnSearch, compute, controlBreak, fixedHeader, flashback, groupBy, help, highlight, and more. Those familiar with IR action menu settings will recognize these as IR attributes, including action menu settings.
The action menu options include 15 items, with id’s, like irSaveReport, irSaveDefault, irReset, irDownload and irNotify. (There are more – inspect for yourself!)
Following John’s blog, and experimenting with various options in the Console, I was able to find these interesting things:
$("#DEMO_IR_ir").interactiveReport("option","currentRowsPerPage");
returns the current rows per page setting.
$("#DEMO_IR_ir").interactiveReport("refresh");
refreshes the IR.
$("#DEMO_IR_actions_menu").menu("find","irDownload");
returns the irDownload object.
[$("#DEMO_IR_actions_menu").menu("find","irDownload").action();
invokes the action method of the irDownload object – it opens the IR Download dialog. Translated, it finds the irDownload object of the DEMO_IR interactive report actions menu and calls its action method.
I leave the rest to your own experimentation. Clearly we are not totally in the dark here, once we know how the widgets work.
Note: The IR static id is optionally declared by the developer. If a static id is not declared, APEX assigns a long ugly one – therefore, it is best to assign a static id when one plans on using referencing it in JavaScript.
It is unclear at this point whether and when a JavaScript API will be provided to standardize and facilitate calls to the IR functions – particularly those for Reset, pagination, and Search options. Talks at KScope15 suggested a future release of an IR API is likely, but no hint of what or when. Until then, remember that customizations that do not use standard APEX APIs are not supported.
As in earlier APEX versions, developers who customize the APEX IR JavaScript widget are in unsupported territory. &nbsp;Which does not mean altering the IR widget or using its calls directly cannot be done, it means that doing so is not supported, and will likely not upgrade smoothly or at all to future versions. (Sound familiar?)
Note: In earlier APEX versions, there was less declarative JavaScript capability and therefore more developer customizations. As APEX advances and incorporates more declarative JavaScript, it is &nbsp;more important to stay within the standard APIs when making customizations, to avoid difficulties when upgrading.
A few code comparisons will illustrate further emphasize the differences between the APEX 4.2 widget and the APEX 5 widgets.
The pre-APEX 5 RESET function is:
/**
* Reset current&nbsp; worksheet report to initial state
* @function
* */
this.reset = function() {
that.action('RESET', false, false, false);
};
The APEX 5 RESET function is a private method:
/**
* Reset current worksheet report to initial state
* @function
* */
_reset: function() {
this._action( "RESET" );
},
Not exactly the same, but close, and note the APEX 5 private method.
The pre-APEX 5 Search function is:
/**
* Runs the basic search functionality of the worksheet.
* @param {String} [pThis] if set to SEARCH check
* @param {Number} [pRows]
*
* */
this.search = function(pThis, pRows) {
var lSearch = that.item.search();
var lSearch_Col = that.item.search_column();
var lReport = $v('apexir_REPORT_ID');
var lTemp;
if (pThis='SEARCH') {
if (pRows) {
that.get.addParam('p_widget_num_return', pRows);
} else {
if ($x('apexir_NUM_ROWS')) {
that.get.addParam('p_widget_num_return', $v('apexir_NUM_ROWS'));
}
}
}
if ( apex.item( lSearch ).isEmpty() ) {
that.get.AddArrayItems2($x_FormItems('apexir_TOOLBAR'),1);
that.pull(lReport);
} else {
if (pThis='SEARCH') {
//lTemp = [$v('apexir_CURRENT_SEARCH_COLUMN'),'contains',$v(lSearch),$v('apexir_NUM_ROWS')];
that.get.AddArrayItems2($x_FormItems('apexir_TOOLBAR'), 1);
pThis = 'QUICK_FILTER';
} else {
lTemp = [this.current_col_id, '=', $v(lSearch)];
pThis = 'FILTER';
that.get.AddArray(lTemp,1);
}
that.action(pThis, 'ADD');
}
$s(lSearch, '');
};
The APEX 5 SEARCH function is a private method:
/**
* Runs the basic search functionality of the worksheet.
* @param {String} [pThis] if set to SEARCH check
* @param {Number} [pRows] Optionally set to control the number of rows displayed, needs to
* be done with the searc because the user could enter a new search, then select the rows
* which would issue the search
*
**/
_search: function( pThis, pRows ) {
var lData, lFArrays,
o = this.options,
lSearch = this._getElement( "search_field" ).val();
// If pRows passed, this has been changed and the new value used, but only allow if
// either actions menu
// row select, or search bar row select is enabled
if ( pRows && ( o.rowsPerPage || o.rowsPerPageSelect ) ) {
o.currentRowsPerPage = pRows * 1;
}
lFArrays = this._utilGetFormElAttributes( this._getId( "toolbar_controls" ) );
lData = {
f01: lFArrays.ids,
f02: lFArrays.values
};
if ( lSearch === "" ) {
this._pull( null, this.reportId, lData );
} else {
this._action( "QUICK_FILTER", lData );
}
},
The APEX IR interactiveReport widget _get function controls all the functions of the interactive report. The complete widget.interactiveReport.js.5.0.0.00.NN can be inspected from its location:
[code]&lt;host server and port&gt;/i/libraries/apex/widget.interactiveReport.js?v=5.0.0.00.NN [/code]
Where the <host server and port> are the http/https and host server name and port of your APEX installation, and NN is the exact version number in your APEX 5 installation’s widget.interactiveReport.js library.
The above code excerpts are not meant to be any sort of how-to – their purpose is only to illustrate that there are differences and any developer who has pre-APEX 5 customizations that rely on the pre-APEX 5 form of widgetinteractiveReport.js will need to review their code carefully and refactor when upgrading to APEX 5.
gReport to Widget Method?
So, what to do with all those unsupported gReport calls? Refactor to use the APEX 5 widget calls and remain unsupported? I cannot tell you. Perhaps more will be revealed in APEX 5.1 ?
To Risk to Not to Risk?
A comparison of the main functions of the pre-APEX 5 and APEX 5 interactive report JavaScript is presented in Table 2 of the APEX 5 Upgrade Cheat Sheet, in the Appendix. This comparison alone is not very helpful – it simply illustrates that a similar, but not exact function/widget method exists for each of the APEX IR actions. Developers that have customizations that rely on the old IR JavaScript must review each function carefully and update their code accordingly.
Again, it is not expected that customized use of the IR JavaScript functions will be supported. Developer beware …
The recommendation is to use dynamic actions that call the APEX_IR API functions and procedures to achieve the desired results. This method mmay mean more coding, but this approach, using the APEX dynamic actions and the published APIs – will be supported going forward. Direct use of the IR and action menu widget methods is not supported. IF you go this way, be prepared to refactor (again) going forward.
Upgrade (refactor) Example
The following simple example demonstrates the changes needed in an existing dynamic action to work successfully in APEX 5.
This simple Execute JavaScript dynamic action changes the background color of a row based on a certain value in the FLAGS column. Yes, this simple highlight could have been done with a pre-set IR Highlight action, however, to not clutter the control panel, to prevent users from editing this affect and for other business reasons this appearance change was done via JavaScript. (This dynamic action was one of several on the IR, each of sufficient complexity that it was not practical to implement all of them as IR actions).
var rows = $('table.<strong>apexir_WORKSHEET_DATA</strong> tbody tr:gt(0)');
rows.each(function(idx) {
var Flags = $(this).children("td[headers=<strong>'FLAGS</strong>']").text();
if( Flags == 'Outlier')
{
$(this).children("td").css("background-color","#FCF067");
}
});
Simple enough, but this does not upgrade to APEX 5 because the apexir_WORKSHEET_DATA id no longer exists, so the table.apexir_WORKSHEET_DATA search returns nothing. In fact, in APEX 5, this dynamic action does nothing at all.
The changes needed to make this dynamic action work in APEX 5 are:
- Replace the apexir_ component with its corresponding APEX 5 irr- component
- Ensure the column name/alias is in fact the APEX 5 column id.
To find the APEX 5 column id, use browser developer tools to inspect the column in question. The column id will be in the format C999999999999 by default, and will be the column alias when there is a clear column name..
The updated code looks like this:
var rows = $('table.<strong>a-IRR-table</strong> tbody tr:gt(0)');
rows.each(function(idx) {
var Flags = $(this).children("td[headers='<strong>FLAGS</strong>']").text();
if( Flags == 'Outlier')
{
$(this).children("td").css("background-color","#FCF067");
}
});
And in fact the updated code highlights outlier rows, as desired, as shown in Figure 6 (below)..
Figure 24 – APEX 5 IR Dynamic Action Updated
The above highlight-row dynamic action upgrade is a very simple example. Your examples may be as simple, or very much more complex. The time to refactor will of course depend on the amount and complexity of the customizations to be upgraded. In this author’s case, the upgrade was straightforward – accomplished in less than two hours including testing, for the series of 6 moderately complex dynamic actions on the page. Your mileage may vary.
APEX 5 IR Upgrade Cheat Sheet
As promised, this post includes a “cheat sheet” for mapping pre-APEX 5 CSS and Ids to their APEX 5 equivalents. The cheat sheet is included in the appendix. Note that a cheat sheet is just a guide – it does not replace doing your homework and learning your subject matter. If you have read the above sections, you have all the information you need to map out your refactoring – you won’t need a cheat sheet.
Every developer should inspect their code and their particular interactive report in APEX 5 and validate their own mappings. The reason is, each interactive report may be configured differently. Different configurations will incur different combinations of IR class and id settings. This author’s recommendation is to use the enclosed cheat sheet as a guideline in beginning your upgrade work, but always always inspect and double-check the mappings in your specific IR and in your specific APEX 5 environment.
Summary
APEX 5 IRs contain some noteworthy new features for end users and developers. For end users, the most significant of those are the improved look-and-feel, modal dialogs, the enhanced GROUP BY action, the new PIVOT action, and the option for multiple IRs on a single page. Part 1 of this series covered the APEX 5 new and enhanced features for end users. For developers, the APEX 5 IR construction changes are more significant as the underlying architecture has completely changed. Developers who have done customizations on IRs in previous APEX version may need to refactor their code to follow the new APEX 5 IR structure and widget methods. With APEX 5, the overall power of APEX IRs has increased, but when it comes to customizations, some upgrade work may be necessary.
References
Manually Refreshing APEX Components
http://docs.oracle.com/cd/E59726_01/doc.50/e39147/extend_app002.htm#HTMDB30267
APEX 5.0 Interactive Report Customization, John Snyders
http://hardlikesoftware.com/weblog/2015/05/12/apex-5-0-interactive-report-customization/
jQuery UI: How to Use the Widget Factory
https://learn.jquery.com/jquery-ui/widget-factory/how-to-use-the-widget-factory/
The APEX 5 APEX_IR API Documentation
https://docs.oracle.com/database/121/AEAPI/apex_ir.htm
Appendix
The APEX 5 IR Upgrade Cheat Sheet
As I mention above (or was that in Part I?), one really does not need a cheat sheet for this upgrade – the more important thing is to note the pattern of class names and CSS element names in the new APEX IR structure:
apexir_<element> ids are now renamed to STATIC_ID_ <element> ids
But for those who want one, the Cheat Sheet I put together over a year ago now is at then end of the complete document, in the link below. No doubt I missed some details – but go for the pattern, THINK and figure things out. You’ll do fine. If you get stuck, contact me 🙂
Complete APEX IR Part II, w Appendix
Note: This complete article is in the RMOUG Fall 2015 SQL>UPDATE. The online newsletter can be accessed here.
