APEX Interactive Grid: Column Widths and noStretch

Setting column widths in Interactive Grid is totally different than how you may have set column widths in Interactive Reports.  While it is nice to blindly let APEX and the browser handle it, there are times when you need to explicitly set a column width, or at least set the width of one column relative to another, and for that you need to know how Interactive Grid handles column widths.

Recall that Interactive Reports let the browser figure out the column width, using table-layout:auto;  We could do little tricks like making the column heading longer or shorter to trick the browser into making the column wider or narrower.  That won’t work with Interactive Grids.  Interactive Grids are Fixed Table Width – table-layout:fixed;.  APEX will, by default, try to fill the full table width with the displayed columns, adjusting  – stretching or shrinking – the width of columns to  fit the full width of the table.

So how to set Interactive Grid column widths?

First,  the Width property (visible in the Appearance property group) for an Interactive Grid column does not set the width of the column.

ColAppearWidth

Instead, run the Interactive Grid, then set the column widths interactively using Drag and Drop on the columns themselves.

Select the || divider to dynamically adjust column width:

ChangeWidth

Select the 4-way divider between columns to activate Drag and Drop column order:

DragDrop

Hover over the divider between column headings to grab either the column width adjustment icon or the drag-and-drop column order icon.

Adjust column widths and column order as desired.  (Notice that APEX will adjust column widths so the full width of the table is filled.  This auto-adjustment may not be what you want – more on “noStretch” later on in this post).  Then save the report: Action –> Report –> Save.   The column order and the relative column widths are saved with the report.   When a user adjusts column widths, or does any other actions, a Reset action will restore the column order and column widths to the default set by the Developer’s Save Report.  Much easier that messing with numbers!

reportSave

You can, in the Column action, set a minimum column width. This sets just that – sets a minimum column width for the column that APEX tries to honor.

ColMinWidth

What about Max width?  You may have a Yes/No column, or a single-digit column, and do not want that column to get auto-stretched to some absurd-looking width.

SillyWidth

 

This is where the noStretch option comes in.

Setting noStretch on a column will hopefully (Oracle Safe Harbor) be declarative as of  APEX 5.2.0.

Until then, to set noStretch, as of APEX 5.1.1, in the Advanced –> JavaScript for the column you do not want stretched, set the noStretch grid column option to true:

function(config) {
   config.defaultGridColumnOptions = {
       noStretch: true
   };
   return config;
}

If you want noStretch true for all columns, the solution is similar, but this time we adjust the configuration in the Advanced–> JavaScript region for the Grid:

function(config) {
   var cfg = cfg;
  cfg.stretchColumns = false;
  return config;
}]
    

With noStretch on, APEX will not resize your noStretch column(s) to fill the full table width:

noStretchOn

 

While this works perfectly if the current view is your Grid view, remember that there are also Chart, Group By, Icon and Detail views – the above code will fail if the current view is not Grid.  So one should make that code that code a bit smarter, so it only acts on – changes the configuration for – a Grid view:

function(config) {
   var cfg = cfg;
  "views.grid.features".split(".").forEach( function (p) {
      if ( !cfg[p] ) {           cfg[p] = {};      cfg = cfg[p];  });
  cfg.stretch.noStretch = true;
Columns = false;
  return config;
}

In version APEX 5.1.0, setting noStretch is a bit different.  If you can, upgrade to APEX 5.1.1 or higher.  There are significant updates to Interactive Grid widgets and APIs in APEX 5.1.1.  IF you cannot upgrade and need noStretch, it can be implemented per column, by adding JavaScript to the Page Execute When Page Loads element:

var igrid = apex.region ("my igrid").widget().interactiveGrid("getViews", "grid");igrid.modelColumns.COLUMN1_NAME.noStretch = true;igrid.modelColumns.COLUMN2_NAME.noStretch = true;
igrid.view$.grid("refreshColumns");igrid.view$.grid("refresh");

That’s it!

I highly recommend checking out the APEX Sample Interactive Grid packaged application. Your best source of Interactive Grid documented examples.

Good luck!
  

 

Going to the Grid: What the APEX Interactive Grid Means to You and Your End Users

I will be speaking at Kscope 17 in San Antonio, TX on APEX 5.1 Interactive Grid:

Going to the Grid: What the APEX 5.1 Interactive Grid Means for You and Your End Users

Karen Cannell , TH Technology
When: Jun 26, 2017, Monday Session 2 , 11:45 am – 12:45 pm
Room: Cibolo Canyon 5
KScope_Pic
Topic: Application Express – Subtopic: APEX New Release

The long-awaited APEX 5.1 Interactive Grid region is here – but what does it mean to you and your end users? Need some practical guidance on when, why, and how to adopt the interactive grid region type? This session is for those who have seen the introductory demonstrations, are looking to upgrade to APEX 5.1, and need some advice. Does the interactive grid replace interactive reports? No more tabular forms? This session answers practical functional and technical questions raised by this new region type:

• When and why should I upgrade existing regions to interactive grid?
• Is there an upgrade wizard?
• What features will I gain; what features will I lose?
• What about customizations – will they upgrade?
• How does an editable interactive grid compare to my existing tabular form?
• Which features must still be manually written? Do I still need to write all that collection logic?
• How can I customize appearance?
• How can I add dynamic actions?
• Can I extend the interactive grid functionality?
• Will my end users like it? What about data entry users?

This session compares and contrasts interactive grids with the interactive reports and tabular forms we are familiar with. We will pay particular attention to maintaining or replacing features and common customizations in existing applications: checkboxes, 32K limits, cascading select lists, row-level validations, interactions between columns, and navigation between fields. How does the interactive grid region measure up? Should you upgrade all your interactive reports and tabular forms now?

How we do settings of which features are on or off for a particular Grid and for a particular column is now controlled by javascript. Sound scary? It is really not, you just need to learn where to put what piece of code when.  How to access data in the Grid data model?  We will show you that too.

If you cannot attend, don’t worry, I will be posting bits of that presentation here over the next few weeks.  IF you can attend, I will see you there!

Rest up ~ our Kscope 17 schedule is packed, so don’t expect much sleep or downtime.

APEX 5 IR Guts and Performance

APEX 5 Interactive Reports (IR) are powerful out of the box, but one can significantly improve performance by strategic settings of certain key parameters.  The full presentation covers all the options.

When your data volumes are low to medium, there may not be much noticeable difference. But when data volumes are high, or the query is resource intensive, the following advice and settings can have a significant performance impact.

In brief:

  • Tune your query, then fine-tune your SQL query. Any slowness here will be magnified in APEX
  • Check MAXROWCOUNT.   The more rows, the longer it takes APEX to retrieve them.  do users really need ALL the rows? OR is it reasonable to ask users to filter first. (APEX 5.1 Interactive Grid will include features to FORCE users to filter first – nice!) Consider  supplying users who need to Download All a separate pag,e os not all users are handicapped by a high MAXROWCOUNT value.
  • Check Max Rows Per Page
  • Check your Pagination setting.  The X to Y of Z is popular, but the “of Z” part is expensive – APEX needs to retrieve all rows then set up pagination. That All Rows part takes time.  Consider using X to Y, and adding a page item that calculates the Z separately. (THere are various options to do this, a topic for another blog post, ranging from a straight COUNT(*) to a sophistcated use of APEX_IR to get the count of the as-filtered IR query)

These are your big-impact settings.

For more info, see the full presentation via the link below or Slideshare:

As you move to APEX 5 Interactive Grid, these three settings till apply – but you have better pagination options, and pagination works differently – heck, all of Interactive Grid works differently – better!  So watch here for upcoming information on Interactive Grid.

APEX5 IR Guts and Performance

Smart use of the IR settings makes for a better end user experience ~ and that’s the whole point!

APEX 5 Reset IR w Multiple IR on Page

With APEX 5 Interactive Reports (IRs) we have the luxury of having multiple IRs on the same APEX page.

That is wonderful, until it comes time to Reset a particular IR. The usual RIR and CIR syntax operates on ALL IRs on the page. Probably not what you want.

To refresh a single IR, use the standard APEX_IR API REFRESH_REPORT procedure.

Briefly:

  • Add a Static ID to your IR. As best practice, do this for all your IRs.  The Static Id attribute is under the Advanced attribute section.
  • Create a button to trigger the IR refresh. Set the Action to Defined by Dynamic Action.
  • Create a dynamic action, on Click of your new  button.
  • Add two True events, one Execute PL/SQL for the APEX_IR.REFRESH_REPORT call, one Refresh to refresh the IR region.
  • The PL/SQL calls APEX_IR.RESET_REPORT:
DECLARE
    v_region_id apex_application_page_regions.region_id%type;
BEGIN
 -- get the IR region id
 SELECT region_id 
   INTO v_region_id
   FROM apex_application_page_regions
  WHERE application_id = :APP_ID
    AND  page_id = :APP_PAGE_ID
    AND  static_id = 'my-region-id'; -- use the Static Id set in the IR Advanced attribute section
    
 APEX_IR.RESET_REPORT(
   p_page_id => :APP_PAGE_ID,
   p_region_id => v_region_id,
   p_report_id => NULL );   -- resets the last-used report
END; 

If you need to reset a particular, saved report, you will need to query for that report_id and enter it instead of NULL in the APEX_IR.RESET_REPORT call.

The Refresh True action is a simple Refresh on your IR Region.

Be sure to uncheck the Fire on Page Load option for both True actions.

That’s it!

Migrate BI to APEX 5?

Just back from presenting Migrating BI to APEX 5 at RMOUG Training Days 2016.  Great conference!  Great experts on all Oracle technology. If you have to pick one short sweet conference a year, this is it.

Ever thought of replacing your under-utilized, expensive or outdated BI tool with a suite of APEX Interactive Reports?  In *SOME* cases this makes sense:

  • Your Data Display requirements are reasonable – i.e. users are happy with seeing and working with a few thousand rows or less at a time.
  • Your BI feature requirements include APEX IR Actions (select, sort, filter, chart, pivot, group by aggregate, save, download), and
  • Your BI feature requirements do NOT include BI analysis, unlimited drill-downs, automatic or integrated analysis (such as percents, rank, etc), drag and drop report creation/analysis, and/or MS-Excel-like features. IF you want these, you have to build them.
  • You have APEX resources to plan, design, build and maintain the APEX app
  • You have Database Architects/Developers to plan, design, build and manage the data structures in the database required to consolidate and serve your data ( materialized views, indexes, or other rollups as needed as licensed for).
  • You are prepared to design, build and tune all for performance (as you always should anyways!)
  • You do NOT require out-of-the-box PDF Printing for the as-displayed data set.  Those who own and extensively use BI Publisher may not want to give up this printing luxury IF moving to APEX means doing so. There are many many printing uses cases for which there are many solutions – ensure you have a solution that fits (and is reasonable to implement) before you jump.

Given all this, it just might work for you  It has for many customers, successfully.  The caveats are:

  • If you need a feature that APEX does not natively supply, you must build it.
  • Dynamic Actions are great -but need to be implemented wisely. They may not always perform well with volumes of data.
    • ex: Dynamic parameter selection => Good.
    • Dynamic parameter selection AND dynamic refresh of the IR with the new parameters (a new query against the source data structure) may/will not perform so nicely, depending on the volume of data.
  • Some features are just not reasonable to build in APEX:
    • ex: True Excel-Like behavior
    •        Dynamic Aggregate adjustments

So – want to replace that aging Discoverer installation?  Consider APEX 5.

In planning pages, menus and features, consider these tips:

  • Plan and meticulously tune all structures – materialized views, CUBEs or ROLLUPS, or whatever works for your data. Anything slow here is magnified slow in APEX.
  • Give users mandatory parameters.  This forces up-front filtering, to reduce the result set to a reasonable size AND gives you a ready-made drill path.  We want reasonable size for reasonable performance of all interactive features.
  • Try 3 to 5 Parameters – More gets tedious for end users if they have to select every time.
    • A Temporal (Year. Quarter, Month), and Spatial ( Country, State, City ) and one or few others specific to your data.
    • Consider using Page Zero or building  a Plugin for displaying the same parameter set on all or several pages. (Yes, Plug-Ins can be used locally!)
  • Use a flag to control when data displays. This allows users to filter (using your parmeters Plugin) first, then wait for data to display.  Plan so users do not incur a big wait right up front.
  • Consider multiple IRs on one page, each containing different aggregates of you data depending on the parameters.  The parameters chosen control which ONE of thes IRs displays at any given time.
  • Consider multiple IRs on one page, each containing different Action Item features.  Authorizations for authenticated users control which ONE of thes IRs displays at any given time.
  • Plan and build drill paths wisely.  Intelligently build useful drill paths.  A drill on every column is not necessary. Drills on key columns are nice to have.

Know Your Users, and know what they really do with the data.  That helps you to design and build truly useful data sets and features.

Still not convinced? On the Fence ?

Consider waiting for APEX 5.1 Interactive Grid.  Previews of this new region type show some promising features that BI folks may find interesting:

  • Drag and drop headings
  • Lazy loading – an option to display the frame then the rest of the data
  • Loading data in pages, as opposed to one big result set.

Doesn’t seem like much, but these are big useability improvements , especially when we are considering paging through volumes of data.  Were I to be starting a BI migration project now,  I would investigate the APEX 5.1 Interactive Grid previews and plan my project accordingly.

In the meantime, see my Migrating tBI to APEX 5 slides here, and  if you have specific questions, reach out:

APEX 5 Interactive Reports, Part II

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.

Fig1_Pre5_apexirdIds

Figure 1 – Pre-APEX 5 apexir_ Ids

Fig2_Axp5IrIds

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”).

Fig3_apx42gReprt

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.

Fig4_Apx42Go

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.

Fig5

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. &amp;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 &amp;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&amp;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:

&amp;lt;host server and port&amp;gt;/i/libraries/apex/widget.interactiveReport.js?v=5.0.0.00.NN 

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:

  1. Replace the apexir_ component with its corresponding APEX 5 irr- component
  2. 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)..

Fig6_ColorCodedIR

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.

APEX Presentations ~ Through the Years

I was recently asked to summarize my APEX Presentations. I realized I had them in several places, but not in one consolidated space. So here it is – a summary of my APEX Presentations through the years:

APEX 5 Interactive Reports

Updated for the APEX 5 release, these links contain the presentations from KScope 15, and white papers as published in RMOUG’s SQL>UPDATE magazine.

For APEX 5, Interactive Reports have been reengineered from the inside out. Any developer who uses IRs, has made customizations for appearance or features or performance outside of the standard API’s, even pagination plugins, needs to be aware of the new CSS and JavaScript engine.  APEX 4 and earlier customizations will likely not work in APEX 5 without some refactoring. Be prepared!

Presentations: APEX 5 (Released) Interactive Report Deep Dive, KScope 2015 Presentation
   APEX5 Interactive Reports New Features and Upgrade Cheat Sheet – Presentation RMOUG 2015
Papers:     APEX 5 Interactive Reports Part I: New Features and Enhancements
     APEX 5 Interactive Reports Part II: Structural CSS and JS Widget Code Changes
 

Migrating Critical Business Application to APEX – Successfully

Presentation: Migrate Business Applications to APEX, Successfully – Presentation 

I had a blast at COLLABORATE14 in Las Vegas, NV, April 6-11, 2014.  I had a chance to catch up on Oracle 12c skills, learn more about ADF Mobile with APEX for hybrid mobile applications, XQuery and XML DB and of course refresh friendships with all those at IOUG.  My Friday presentation was on Migrating Critical Business Applications to APEX, covering tips and tools for migrating any legacy app to APEX.

APEX Data Load Options, or, How Do I Load Data, Let Me Count the Ways …

Presentations: APEX Data Loading Options

There are many many ways to load data into an Oracle application. This presentation discusses data load methods specific to APEX – the data load wizard, external files, custom methods and using the APEX Listener for a true MS Excel file upload. This is practical what works, what doesn’t information to help one decide the best approach for data loading problems.

Meaningful Maps, Gantts and Charts

Presentations: Meaningful Maps, Gantts and Charts

APEX 4.0 introduces improved charts and maps, but how to make sense of them? This presentation covers all the basics for understanding APEX 4.0 Charts, Maps and Gantt Charts.  Plenty of information to get one building meaningful charts and maps in APEX applications.

Tight Tabular Forms

Presentations: Tight Tabular Forms

APEX tabular forms are handy, but kind of loose, if you use them out of the box. This presentation covers the improvements in APEX 4.0 for tabular form validations, plus some tips on adding validations using the APEX_APPLICATION arrays, and building manual tabular forms using the APEX_ITEM API.

Migrate BI to APEX: What Works, What Doesn’t, and Lessons Learned Along the Way

Presentation: Migrate BI to APEX – What Works, What Doesn’t, and Lessons Learned Along the Way

This presentation covers a real migration from a major-vendor BI tool to APEX Interactive Reports for end-user information needs. Covers feature considerations such as drills, pivots, output; dynamic crosstab options and construction, including use of 11g PIVOT and AMIS PIVOT object type solution.  Careful crosstab query construction makes APEX Interactive Reports more powerful than one may think. APEX 4.0 new features address the needs for user-defined grouping, shared reports, scheduled report delivery, multiple views of the same data set and improved charting.  Check it out!

Note:  I am working on an APEX 5 version of this presentation – improvements in APEX 5 interactive reports, including the PIVOT feature, may tip the scales and make a switch from an expensive, underutilized BI tool to APEX a better use of resources.

Oracle Application Express: Tactics to Tackle APEX Bugs

Paper:               Tactics to Tackle_APEX Bugs,  Paper

Presentation: Tactics to Tackle_APEX Bugs, Powerpoint

Know your application, know your tools, have a plan, and always remember that you know some stuff. You can debug Application Express apps and stay sane.

APEX development is a breeze, until something goes wrong and there’s no obvious clue of what happened or how to fix it, and there’s no UNDO. Or is there? This session presents tactics to tackle common APEX problems such as MRU internal error, Browser errors, SQL and PL/SQL issues, HTML, and JavaScript problems. We cover triage, debug tool options, and debug tactics, and then demonstrate applying those strategies to tackle common APEX problems.

This paper and presentation were written for APEX 4.0 (or earilier?) ~ APEX debugging techniques are much improved now! However, the strategies and tactics for addressing bugs: knowing your app, knowing your tool, instrumenting, researching first and using the forums still apply.

Oracle Application Express Interactive Reports: The Good, The Bad, The Ugly

Presentation: APEX Interactive Reports: The Good, The Bad & The Ugly

Paper:               APEX Interactive Reports: The Good, The Bad, The Ugly

I had fun writing this paper, mainly because the movie (old western, Clint, of course) theme song played in my head, and our house is defnitely a Clint-John Wayne-Sam Elliot-Any Old Western neighborhood.

Oracle APEX Interactive Reports have many Good points, but one-size does not fit all, so we developers still have some cleverness to apply to meet end user requirements in all cases. This paper outlines the Good, the Bad, the limitations, and shows some easy CSS edits to address the Ugly, the default appearance. Have fun!

APEX Interactive Reports offer amazing functionality out-of-the box, but this wealth of features comes with limitations. This session presents the Good, the Bad and the Ugly of APEX IR, then details and demonstrates workarounds to address the Bad (the limitations) and the Ugly (the appearance). Learn how to limit Search and Activity features for different user roles, how to eliminate part or all of the Search and Activity Bars and how to customize the look-and-feel to fit your corporate template.

(As with all my papers, I will keep this post up to date with the latest version of the paper.)

APEX Cheat Sheet

Download the APEX Cheat Sheet paper from here: APEX Cheat Sheet

When starting out with Application Express, it can be a bit confusing in terms of what syntax to use where, how to effect the item alignment needed, how to customize the look-and-feel… in general, how to get productive. Tha APEX Cheat Sheet paper is a collection of tips, how-to’s, syntax conventions and tricks to accelerate a developer’s APEX learning curve. The APEX Cheat Sheet paper has grown to be much longer than a “cheat sheet” but it does provide a solid quick-start to APEX development.

Note: While written for erly APEX versions – APEX 3! – some of the basics still apply, like the f?p syntax.  Someday I will do another Cheat Shet- the problem is there are so many new features, I will have to do multipe cheat sheets for each major feature.

APEX Under the Covers

Paper: APEX Under the Covers

In working with Oracle Application Express I have found the best way to learn “how they did that” is to look “under the covers” at the APEX code … The way to do that is to download an application, install it in my builder, and view how the author implemented the features of interest.

The white paper and presentation APEX Under the Covers walks the reader / viewer through the learning process of looking under the covers at some not-so-standard features implemented in APEX. The examples are not rocket science; they are intended only to get the brain thinking along lines where the reader may not yet have ventured, suggesting a few different approaches to achieving an end within APEX.

Note: This presentation was written for APEX 4, but the approach is the same with APEX 5 and beyond – learn from how they wrote APEX. For APEX 5, use and LOOK AT how they wrote the packaged applications. This is free training at its best!

APEX Debug Options

Paper: APEX Debug Options

Debugging Oracle Application Express can be a conundrum.   It’s PL/SQL, but I cannot see it, and I cannot step through it. PL/SQL generates the page, but I do not have access to the APEX page generator. There is JavaScript and CSS and HTML … Where to start?  The truth is there are many avenues for debugging APEX; some APEX-supplied, some external to APEX. The paper and presentation APEX Debug Options describes both APEX-supplied utilities and tools external to APEX for debugging APEX applications.

~ Keeping it Fresh: Cost-Effective Training

Layoffs, economizing, more for less, and oh-by-the-way keep up with the latest in Web development, languages, data modeling, coding techniques, testing, quality, the latest App Servers and find time to relax a bit and network with your peers. The temptation is to postpone or skip all training. I suggest however that this is the time we need training all the more. I maintain the most cost-effective training can be found at our user group conferences. Attend! Volunteer – get involved! IT is the most efficient, cost-effective way to stay current and learn new technologies, and you might have some fun along the way.