Faceted search only works for classic reports, maps, and card regions. But with just a little effort, you can extend this feature to any region type. I stumbled upon this method while working for a client. I’d love to give them credit, but I can’t always reveal my sources :). I do know that the client got the technique from a blog post that is no longer active:
https://blogs.oracle.com/apex/post/add-a-chart-to-your-faceted-search-page
I never had the pleasure to read the blog post, but I got a gist of what it must have said. I’ve written what I believe is a more generic utility to accomplish the task—perhaps an improvement on the original, but I don’t know for sure. (I tried using https://archive.org to look it up, but at the time of this writing the archive was temporarily offline.)

Overview

The overall approach is quite straightforward, but I’ll add some nuance later.

1. Create a faceted search based upon a classic report. Get it working exactly as you would like it to work. Get all the facets working as they should. Make sure the classic report returns exactly the data you are interested in. Give the report a static ID (e.g. EMP_R).

2. Create the kind of component you actually want, using the same query as the classic report. I’m going to call this a chart just to be able to refer to it, but it could be any region type that supports refresh.

3. Create a dynamic action that refreshes the chart after the classic report refreshes.

   1. At this point changing a facet will change the results of the classic report. That, in turn, will refresh the chart, but the results of the chart won’t change.

4. This is the hardest step, but the solution is below…so just get the idea. Create a function that returns a table type. The function will return this table type containing only the rows returned by the classic report. This table type needs to include one or more attributes that allow you to identify the rows that are returned. Generally, any row returned should be able to be uniquely identified by one or more columns. Usually they can be identified by a single primary key column. For example, if your data is about employees (the classic EMP table), you may only need to return the EMPNO. Even if the query is very complicated, a single primary key column may likely be all you need. You can review the code below to see how this works. This function will use APEX_EXEC. I’m going to call this function “ait_util.get_faceted_search_number_data”.

5. To the chart region query you will either add a join on get_faceted_search_number_data or you will add this to the where clause of the query. It will look something like this:

select e.empno,
       e.ename,
       ...
       d.dname
       ...
  from emp e
  join dept d on d.deptno = e.empno
  join ait_util.get_faceted_search_number_data(...) facet_results on facet_results.column_value = e.empno
  where ...

or (this method can also be used if you define the region directly on a table or view, not a SQL query)

select e.empno,
       e.ename,
       ...
       d.dname
       ...
  from emp e
  join dept d on d.deptno = e.empno
  where empno in (select column_value from ait_util.get_faceted_search_number_data(...) )
    and ...

This will limit the chart query to just the rows being displayed in the classic report.

6. Now you can “hide” the classic report (assuming you don’t want it to show). The classic report still needs to exist on the page, though. You can hide it using an page onload dynamic action or by adding an attribute to the region: style=”display:none” .

7. Note: ultimately, your classic report query only needs to have the columns in the select portion of the query that are used for facets, plus the primary key column used to limit the rows of the chart. If you have some large calculation or other potentially slow part of the query that is not used to reduce the rows returned, it does not need to be in the classic report.

The key to this, of course, is the function ait_util.get_faceted_search_number_data. I think the original post suggested creating an object type with multiple attributes. In the example above it would return a table type of an object, e.g. T_EMPLOYEE_TABLE returning object T_EMPLOYEE, with at least the EMPNO attribute. This is great and particularly important if you don’t have a way to identify the rows by a single column/attribute. In that case you will need to be able to return more than one attribute. But usually, it will be a primary key.

The Details

Steps 4 & 5 above are all about using the faceted search classic report to drive the results of the chart region (or any other region type). It’s funny because I thought we did an APEX Instant Tip on exactly this at some point in the past, but I don’t see one. In any case, I’ve made this super easy to do. The package below provides two functions, one for row identifiers that are varchar2 and the other for row identifiers that are numbers. With these functions you don’t need to create any object types. The package relies on APEX_T_VARCHAR2 and APEX_T_NUMBER. Just install the package spec and body below and you can follow the steps above to drive the results of any region type based upon a faceted search.

create or replace package "AIT_UTIL" as

--==============================================================================
-- comments about function
-- select column_value
--   from ait_util.get_faceted_search_vc2_data(
--                                    p_page_id => :APP_PAGE_ID,
--                                    p_region_static_id => 'EMP_R',
--                                    p_pk_column_name => 'EMPNO')
--==============================================================================
function get_faceted_search_vc2_data( 
    p_page_id           in number,
    p_region_static_id  in varchar2,
    p_pk_column_name    in varchar2 ) 
  return apex_t_varchar2 pipelined ;

--==============================================================================
-- comments about function
-- select column_value
--   from ait_util.get_faceted_search_number_data(
--                                    p_page_id => :APP_PAGE_ID,
--                                    p_region_static_id => 'EMP_R',
--                                    p_pk_column_name => 'EMPNO')
--==============================================================================
function get_faceted_search_number_data( 
    p_page_id           in number,
    p_region_static_id  in varchar2,
    p_pk_column_name    in varchar2 ) 
  return apex_t_number pipelined ;  

end "AIT_UTIL";
/

create or replace package body "AIT_UTIL" as

--==============================================================================
-- Public API, see specification
--==============================================================================
function get_faceted_search_vc2_data( 
    p_page_id           in number,
    p_region_static_id  in varchar2,
    p_pk_column_name    in varchar2 ) 
  return apex_t_varchar2 pipelined 
  is

    l_region_id   number;
    l_context     apex_exec.t_context;

    type t_col_index is table of pls_integer index by varchar2(255);
    l_col_index t_col_index;

    ---------------------------------------------------------------------------
    procedure get_column_indexes( p_columns wwv_flow_t_varchar2 ) is
    begin
      for i in 1 .. p_columns.count loop
          l_col_index( p_columns( i ) ) := apex_exec.get_column_position( 
                                               p_context => l_context, 
                                               p_column_name => p_columns( i ) );
      end loop;
    end get_column_indexes;

  begin
    -- 1. get the region ID of the Faceted Search region
    select region_id
      into l_region_id
      from apex_application_page_regions
     where application_id = v('APP_ID')
       and page_id        = p_page_id
       and static_id      = p_region_static_id;

    -- 2. Get a cursor (apex_exec.t_context) for the current region data
    l_context := apex_region.open_query_context(
                     p_page_id      => p_page_id,
                     p_region_id    => l_region_id );

    get_column_indexes( wwv_flow_t_varchar2( p_pk_column_name ) );

    while apex_exec.next_row( p_context => l_context ) loop
        pipe row(apex_exec.get_varchar2( p_context => l_context, p_column_idx => l_col_index( p_pk_column_name ) ) );
    end loop;

    apex_exec.close( l_context );

    return;
  exception
    when no_data_needed then
      apex_exec.close( l_context );
      return;
    when others then
      apex_exec.close( l_context );
      raise;
end get_faceted_search_vc2_data;


--==============================================================================
-- Public API, see specification
--==============================================================================
function get_faceted_search_number_data( 
    p_page_id           in number,
    p_region_static_id  in varchar2,
    p_pk_column_name    in varchar2 ) 
  return apex_t_number pipelined 
  is

    l_region_id   number;
    l_context     apex_exec.t_context;

    type t_col_index is table of pls_integer index by varchar2(255);
    l_col_index t_col_index;

    ---------------------------------------------------------------------------
    procedure get_column_indexes( p_columns wwv_flow_t_varchar2 ) is
    begin
      for i in 1 .. p_columns.count loop
          l_col_index( p_columns( i ) ) := apex_exec.get_column_position( 
                                               p_context => l_context, 
                                               p_column_name => p_columns( i ) );
      end loop;
    end get_column_indexes;

  begin
    -- 1. get the region ID of the Faceted Search region
    select region_id
      into l_region_id
      from apex_application_page_regions
     where application_id = v('APP_ID')
       and page_id        = p_page_id
       and static_id      = p_region_static_id;

    -- 2. Get a cursor (apex_exec.t_context) for the current region data
    l_context := apex_region.open_query_context(
                     p_page_id      => p_page_id,
                     p_region_id    => l_region_id );

    get_column_indexes( wwv_flow_t_varchar2( p_pk_column_name ) );

    while apex_exec.next_row( p_context => l_context ) loop
        pipe row(apex_exec.get_number( p_context => l_context, p_column_idx => l_col_index( p_pk_column_name ) ) );
    end loop;

    apex_exec.close( l_context );

    return;
  exception
    when no_data_needed then
      apex_exec.close( l_context );
      return;
    when others then
      apex_exec.close( l_context );
      raise;
end get_faceted_search_number_data;


end "AIT_UTIL";
/

Some Nuance

Keep in mind that your classic report is going to run—even though you may hide the results. Hence, you want it to run as quickly as possible. The classic report and the chart, interactive report, interactive grid, etc. don’t have to have the exact same query. The classic report must have the columns associated with the facets in the select clause, and it should only return the primary key values that you ultimately want in the the target region (e.g. the chart). That means it’s predicate (where clause) should have everything you want in it, but it’s possible you don’t need every join, especially outer joins. Additionally, you may not need every column in the select clause. Take this interactive report as an example:

select e.empno,
       e.ename,
       e.mgr,
       my_slow_function(p_empno => e.empno) credit_score, -- scalar subquery not helpful here
       (select my_other_slow_function(p_dept_mgr_id => d.mgr_id) from dual) dept_mgr_info,
       e.deptno
  from emp e
  join dept d on d.deptno = e.deptno

you can use shared LOVs for e.mgr and e.deptno to display the content. You may not want to have facets on credit_score and dept_mgr_info. In this case, your classic report could simply be

select empno,
       mgr,
       deptno
  from emp

That will give you the ability to have facets on Manager and Department (using shared LOVs), and it won’t have the overhead of the join or the expensive slow functions. In the end, your IR query would be

select e.empno,
       e.ename,
       e.mgr,
       my_slow_function(p_empno => e.empno) credit_score, -- scalar subquery not helpful here
       (select my_other_slow_function(p_dept_mgr_id => d.mgr_id) from dual) dept_mgr_info,
       e.deptno
  from emp e
  join dept d on d.deptno = e.deptno
  join ait_util.get_faceted_search_number_data(
                                    p_page_id => :APP_PAGE_ID,
                                    p_region_static_id => 'EMP_R',
                                    p_pk_column_name => 'EMPNO') fs_data
       on fs_data.column_value = e.empno

If you are basing the region on a table or view, not a SQL query, you can just add this to the where clause of the region:

e.empno in (select column_value from ait_util.get_faceted_search_number_data(
                                    p_page_id => :APP_PAGE_ID,
                                    p_region_static_id => 'EMP_R',
                                    p_pk_column_name => 'EMPNO') )

You can get more details on this topic by watching APEX Instant Tips episode 75.

You can see what I’m talking about in the image below. I’ve made an exaggerated example; the Job column does not match the heading.

To solve the problem, you need to trick APEX into thinking the page has been resized. Whenever you do something to dynamically format the page, typically via a dynamic action, you can add an additional line of javascript code (or an additional true action to run this line of code).

$(window).trigger("apexwindowresized");

That will trigger the event that tells APEX to realign things…like Interactive Report columns.

The sample maps application has a Search and Show page that manages to recenter the map. It uses about 25 lines of javascript (in an after refresh dynamic action) to make it happen:

var lMapRegion   = apex.region("airport-map-region"),
    // important: Use the layer name exactly as specified in the "name" attribute in Page Designer
    lLayerId     = lMapRegion.call("getLayerIdByName", "Airport"),
    lCurrentZoom = lMapRegion.call("getMapCenterAndZoomLevel").zoom,
    lAirportId   = apex.item("P121_ID").getValue(),
    lFeature     = lMapRegion.call("getFeature", lLayerId, lAirportId ),
    lPosition;

if ( lFeature.geometry ) {
    lPosition    = lFeature.geometry.coordinates;

    // close all Info Windows, which might currently be open
    lMapRegion.call( "closeAllInfoWindows" );

    // focus the map to the chosen feature
    lMapRegion.call( "setCenter", lPosition );

    // if the current zoom level is below 8, zoom in. Otherwise do nothing.
    if ( lCurrentZoom < 12 ) {
        lMapRegion.call( "setZoomLevel", 12 );
    }
    setTimeout( function() {lMapRegion.call( "displayPopup", "infoWindow", lLayerId, lAirportId.toString(), false )}, 500 );
}

Unfortunately, those 25 lines of javascript don’t work for polygons (and perhaps other layer types). Fortunately, there is a single line of javascript that works for all types:

apex.region("your_region_static-ic").reset();

With that line of javascript you don’t even need to refresh the region. It will refresh and recenter the region. For more details, check out APEX Instant Tips Episode 154. Many thanks to Marwa for teaching me this tip!

I admit there is a downside to this method. The region will zoom out to a location and then zoom into the location you want. It looks cool the first few times it happens, but gets old after a while. The solution is simple enough that I’m willing to live with it…until I have someone that insists on a different solution.

Unfortunately, APEX charts do not do this by default. I found this great blog post by Tomáš Kucharzyk that describes how to change the colors of APEX charts and how to do a lot of other very cool things. It does not, however, mention how to tie it to the APEX CSS variables. After reviewing the blog post, though, I came up with the following two blocks of code. Both go in the Initialization Javascript Function of the chart attributes.

This code works for some chart types (multi-series charts):

function(options) {
  let listOfPatterns = [    
    "smallChecker", "smallTriangle", "smallCrosshatch", "smallDiagonalLeft",
    "smallDiamond", "smallDiagonalRight", "largeChecker", "largeCrosshatch", "largeDiagonalLeft", "largeDiagonalRight", "largeDiamond",
    "largeTriangle", "auto"
  ];

  let listOfColors = [
    "--u-color-1", "--u-color-2", "--u-color-3","--u-color-4", "--u-color-5", "--u-color-6","--u-color-7", "--u-color-8", "--u-color-9",
    "--u-color-10", "--u-color-11", "--u-color-12","--u-color-13", "--u-color-14","--u-color-1", "--u-color-2", "--u-color-3","--u-color-4", "--u-color-5", "--u-color-6","--u-color-7", "--u-color-8", "--u-color-9",
    "--u-color-10", "--u-color-11", "--u-color-12","--u-color-13", "--u-color-14"
    ];

  options.dataFilter = function (data) {
    for (let i = 0; i < data.series.length; i++) {
      let color = getComputedStyle(document.documentElement).getPropertyValue(listOfColors[i % listOfColors.length]).trim();  
      data.series[i].color = color;
      data.series[i].borderColor = color;
      //data.series[i].pattern = listOfPatterns[i % listOfPatterns.length];
    }
    return data;
};
return options;
}

This works for single series charts:

function(options) {
  let listOfPatterns = [    
    "smallChecker", "smallTriangle", "smallCrosshatch", "smallDiagonalLeft",
    "smallDiamond", "smallDiagonalRight", "largeChecker", "largeCrosshatch", "largeDiagonalLeft", "largeDiagonalRight", "largeDiamond",
    "largeTriangle", "auto"
  ];

  let listOfColors = [
    "--u-color-1", "--u-color-2", "--u-color-3","--u-color-4", "--u-color-5", "--u-color-6","--u-color-7", "--u-color-8", "--u-color-9",
    "--u-color-10", "--u-color-11", "--u-color-12","--u-color-13", "--u-color-14","--u-color-1", "--u-color-2", "--u-color-3","--u-color-4", "--u-color-5", "--u-color-6","--u-color-7", "--u-color-8", "--u-color-9",
    "--u-color-10", "--u-color-11", "--u-color-12","--u-color-13", "--u-color-14"
    ];

  options.dataFilter = function (data) {
    for (let i = 0; i < data.series.length; i++) {
        for (let j = 0; j < data.series[i].items.length; j++) {
            let color = getComputedStyle(document.documentElement).getPropertyValue(listOfColors[j % listOfColors.length]).trim();  
            data.series[i].items[j].color = color;
            data.series[i].items[j].borderColor = color;
            //data.series[i].pattern = listOfPatterns[i % listOfPatterns.length];
        }
      }
    return data;
    };
return options;
}

In both cases I left in some code from Tomas’s blog to change the fill pattern. You can enable the pattern by uncommenting the commented line in the code above.

The nice thing about this approach is that if you ever change the theme, or the color palette, all of your charts that have this code will automatically have the new colors applied.

By changing the color of “Color 1” in the color palette, my chart’s bottom color changes automatically.

Exercise

If you implement the custom patterns found in Tomas’s blog, you can do the same thing by referencing the theme colors via the variables instead of hard coding them in his javascript file. That’s an exercise left to the reader, but it is very straightforward.

If you are over the age of 50 and attempting to impress your viewpoint on someone between the age of 17 and 35 you should first stop talking and listen to their viewpoint. You’ll probably learn something. If you don’t know what TLDR means, this article is definitely for you.

Disclaimer

This blog is usually about a topic on which I have some expertise. The content is thoroughly researched. You can generally rely on it. Today’s post is based primarily upon observation and my own understanding of the human condition. There is no science here. Even my terms are at best loosely defined. I’d love to have this theory vetted or refuted by someone with actual expertise and a willingness to do the research required. I anticipate and welcome criticism.

Background

On July 1, 2022 my “Wisdom of the Week” was about Generational Knowledge Inversion (GKI). (You can watch the video if you prefer.) GKI is my hypothesis that, for the first time in the existence of humans, parents should anticipate that their children will, at some point in the parents’ lifetime, have more “relevant knowledge” than the parent. I do not have a concrete definition of relevant knowledge. Notionally, though, it is knowledge that, at the current point in time, has some usefulness. For example, I was once very proficient at using a slide rule and I know how to drive a manual transmission car. Knowing the foundational mathematics that govern how a slide rule works (logarithms, exponents, etc.) is certainly relevant knowledge. Perhaps knowing how and why a slide rule works is valuable knowledge. Being good at using one, though, is no longer relevant. Right now, for most Americans, knowing how to drive a manual car is not relevant and in just a few years it will go the way of the slide rule. A little thought reveals a plethora of examples from the last century: using a phone book, the Dewey Decimal System, shorthand, rewinding a cassette tape that has had the magnetic strip get pulled out of it. You get the idea.

I came upon the theory of GKI through my interactions with my own children. Most parents experience a moment when their children exclaim, “You’re not listening to me!” I am no exception. From the outside, though, I witnessed my mother engaged in a disagreement with my daughter (probably 20 years old at the time), and this exclamation came ringing back into my ears. I later suggested to my mother that her grandchildren are, in fact, experts in many of the topics that they discuss…and that she should consider listening to their viewpoint (or expertise) before trying to impress her viewpoint upon them. She might learn something. A couple months later, my mother unexpectedly announced to me, “You know, after spending more time with [my granddaughter] I’ve realized that when we disagree I should just stop talking and listen. I always learn something new.” It was in that moment that I realized that if my 78 year old mother was learning from her grandchildren, I too should stop talking and listen to them.

Generational Knowledge Inversion

Why is it so hard for us to come to that conclusion? Why don’t we all just instinctively stop talking and listen when our adult children speak? For about 300,000 years humans have roamed the earth. In nearly all of that time, parents, in general, could assume that they possessed more relevant knowledge of the world than their offspring. If we look at a completely unscientific graph of a person’s relevant knowledge it might look something like this:

At birth everything we see is new and relevant. We rapidly gain relevant knowledge. As we age, though, most of what we see is something we have already learned. Throughout most of human existence the graph was ever increasing, but the rate of increase was continually lessoning.

A person’s offspring would have almost the identical graph. Perhaps over centuries the total accumulation of knowledge might increase ever so slightly. A parent’s knowledge, however, could reliably be considered to be greater than that the offspring throughout the lifetime of the parent.

There were exceptions, of course. Perhaps Isaac Newton had more relevant knowledge than his parents. In general, though, all 300,000 years of human evolution have prepared parents to assume they have more relevant knowledge than their children…and their children’s generation.

Three elements of the past contributed to this. The world changed very slowly. Once gained, relevant knowledge rarely became irrelevant during a lifetime. That contributed to a graph that was ever increasing. Secondly, communities were small and local. What was relevant was typically relevant throughout the community and learned from the community. Limited travel and intrinsic commonality within a community dictated that a parent’s experiences would be directly relevant to the life of their children. Thirdly, the information available to a child generation was essentially the same that was available to the parental generation. This began to change with the printing press, but the change was small. And, typically, the older generation had access to, and the facility to utilize, the additional information before, or at least, at the same time as the younger generation.

For those born after 1960 (myself included), all of these elements have radically changed. Relevant knowledge gained in our youth rapidly dissipates into anachronistic trivia. New knowledge is abundant. The boundaries of space are overcome by instant communications with virtually anyone on the planet. Our children grew up in the information age, giving them an immense edge in accessing and assimilating relevant knowledge. My children learned elements of physics, chemistry, and biology in high school that were unknown while I was in college. The graph has shifted:

Interestingly, I postulate that members of my specific generation, born between 1960 and 1980, are in the unique position that we may never surpass our parents, but our children will surpass both their parents and their grandparents.

Pseudoscience

Here we have all the makings of a full-on pseudoscientific article: multiple graphs without any data to support them, corresponding text to support the pretty graphs but still lacking any data. Since proposing this theory nearly 3 years ago, I have had many people ask me, or more accurately, say to me, “But, you don’t really think your children know more than you, right?” My children are now ages 23, 26, and 30. On any topic that is not my area of expertise, I state emphatically: Yes, my children likely have more relevant knowledge than I do. That doesn’t mean they always have more relevant knowledge than I do. I go into most conversations, however, knowing that they may, or likely do have more relevant knowledge than I. Interestingly, I have found that even in areas where I have significant expertise, my children often contribute novel ideas and insights to the topic. I have been primarily discussing a parent-child relationship, but the same holds true simply across generations. I work with many people a generation or two younger than me. I consistently find that I should listen to their ideas and viewpoint before espousing my own. It occasionally saves me some embarrassment and I invariably learn something.

Whether this pseudoscience is accurate or not is somewhat irrelevant. My own experience is that I can shift my blue line (in the graph above) by listening more (and first). I’m not suggesting that I can keep my blue line above the red line, but I hope I can at least keep it rising instead of falling.

Finally, I admit that I am wildly imperfect at this. 300,000 years of evolution tug at me to think that I will always have more relevant knowledge than those in subsequent generations. Recognizing the fallacy, though, is a start.

TLDR = Too Long, Didn’t Read

TLDR

Use “Blank with Attributes” as a parent region to arrange subregions.

Use “Blank with Attributes (No Grid)” almost never :) If you wish to manually arrange everything in the region, this is the region type for you.

Use “Standard” for just about everything else (on a non-modal page)…with lots of exceptions. Most of the other templates have specific use cases and their names make it clear why you would use them.

“But wait!” you exclaim, “What if I don’t want the title bar on Standard region? Shouldn’t I use ‘Blank with Attributes’?” This is the TLDR, you’ll have to keep reading for answers.

But…no, you should use a variation of the Standard region. Again, you’ll have to keep reading.

The APEX Grid

APEX uses a 12 column grid to arrange things on a page. 12 is divisible by 1, 2, 3, 4, and 6. This provides good symmetry for arranging up to 6 components (or all 12) across the page or within a region, with the notable exceptions of 5 and 7 components. For this reason I try to avoid 5 and 7 components on a single row. I’m specifically using the word “component” because this applies to regions, items, buttons, etc.

In a similar fashion, most regions templates support a grid. When the region template supports a grid it will also have 12 columns. Hence, if you have two regions on the same row, you will have 24 columns in which to arrange components within those 2 regions. If these two regions have no padding and are each defined as 6 columns wide, the 24 total columns will each represent ½ of the page columns and they will align with the page columns. If the two side-by-side regions have any padding or are not each 6 columns wide, each region’s 12 column grid will be slightly different (or potentially radically different) than the 12 page columns.

The notable exception to this is the “Blank with Attributes (No Grid)” template. This template just has one big open space. You will see that items, buttons, etc, do not show attributes to indicate column, column span, etc. Of course, you can create additional templates that don’t support a grid. In recent versions of APEX this is accomplished in the region template in the “Slots” attribute section.

You can view the grid layout on any page by selecting Show Layout Columns in the developer toolbar.

If you enable this on a region with the Standard template (and at least one component in the region) you can see that the 12 region columns don’t align precisely with the 12 page columns.

With two Standard regions you start to see real differences. (Note: I intentionally did not add an item to the second region to demonstrate that you must have a component in the region in order to see the layout columns.)

Blank with Attributes

I recommend using the “Blank with Attributes” region template primarily for arranging other regions. I do not recommend it for containing content of its own.

Arranging Content

“Blank with Attributes” does not have padding and adds very little to the page. It does not even send the region title to the page (not even as hidden or otherwise not shown text). Hence, this template is ideal as a parent region that is just used to establish the placement on the page for subregions.

Not for Content

For these same reasons, I do not recommend “Blank with Attributes” for actual content. This region template doesn’t apply the same font (etc) conventions that are used in the “Standard” template. It also does not send the region title to the page, so screen readers and other accessibility features are not well-supported.

Standard

The “Standard” template should be used for most content. There are a lot of templates that have specific uses, and when it makes sense, you should, of course, use those templates. Regions using the "Standard” template have a variety of features that provide a unified look and feel, abide by theme colors, and work well with the adaptive and accessibility features of modern browsers.

I Don’t Want a Region Title

If you are using breadcrumbs, having a region title on the primary region of the page is often redundant and wastes valuable space. In these cases people often default to using “Blank with Attributes.” I prefer to use the “Standard” template with modifications to the template options.

The template options above mimic a “Blank with Attributes” template but maintain the “Standard” template’s font and other settings. This provides a unified look and feel to the application. It also continues to provide adaptive and accessibility features of modern browsers. You can play around with these settings to determine exactly how you want to define the template for your main content.

Making Things Easy

Once you have settled on the appropriate settings for your main content you want to make it easy for your development team to apply this standard. In order to do this, I recommend that you copy the “Standard” template and name it something explicit, e.g. “Stoked Standard”. Modify the new template and apply the template options you have determined.

After creating the new template, edit the application theme and change the default templates:

Of Course…

You will likely still use the original “Standard” template. Make sure your developers know that it’s OK to use it. In fact, you may actually decide you want to leave “Standard” in most of the Region Defaults. The “Component Defaults” are what are used when you use the create page wizard or when you first add a region to the page in the component tree pain. The “Region Defaults” are used when you change to a specific region type. Often this is an additional region. Your application standards my drive slightly different default settings. The good news is that, by having defined templates, getting the right settings is as easy as selecting a template—just a click away.

One Downside

There is one downside. Because you have copied the "Standard” template, when you upgrade APEX and then you refresh the theme in your application, the new “Standard” template will not be applied to your copy, which is now your default template. Generally, all you have to do is copy each block of HTML from the newly refreshed “Standard” template to your copy.

Conclusion

By giving a little thought to your page layout and template choices early in the design process you can save time for the life of the project. The APEX team puts a lot of effort into providing a unified look and feel, implementing accessibility, and generally applying modern best practices. With just a little upfront work all of our applications can benefit from their efforts.

-- this is slow
select id,
       parent_id,
       sys_connect_by_path(id,'.') cb_path,
       connect_by_isleaf is_leaf,
       c1
       ...
       c200,
       (select my_function(c1) from dual) my_f,
       ...
  from my_table
  start with parent_id is null  -- ** set parent id column
  connect by nocycle prior id = parent_id
  order siblings by seq_no

Looking at the explain plan and a trace, I found that the database was reading the entire table many times. I guessed that I might be able to get the database to do a single read of the table if I could limit the “connect by” portion to use only an index, and then, once the hierarchy is established, join in the rest of the data in a single pass.

-- this is much faster
-- assumes you have a single compound index on id,parent_id
-- and another unique key index on id
with cb_data as
(select id,
       parent_id,
       sys_connect_by_path(id,'.') cb_path,
       connect_by_isleaf is_leaf
  from my_table
  start with parent_id is null  -- ** set parent id column
  connect by nocycle prior id = parent_id
  order siblings by seq_no
)
select id,
       parent_id,
       cb_path,
       is_leaf,
       c1
       ...
       c200,
       (select my_function(c1) from dual) my_f,
       ...
  from cb_data
  join my_table mt on mt.id = cb_data.id

In the new query, the hierarchical portion, cb_data, contains only 3 columns: id, parent_id, seq_no. I created an index with just these three columns. If I run just the hierarchical portion of the query the database does not read the table at all. It only reads the index. When I run the entire query, the database reads only the index to establish the results of cb_data and then does a single pass of my_table to return the final results. The new query returns the same results but, in my case, runs in 4 seconds. That’s a solid improvement over the original 104 seconds.

The key is to have a single index that contains all of the columns used in the CTE (cb_data above). If you require any additional columns in the CTE to accomplish the connect by, ensure they are in the index. I have not done extensive testing related to the order of the columns. My initial impression is that id, parent_id, seq_no provides good performance.

I hope this helps others as well. Comment to let me know if you try it and have similar results.

TLDR

Jump to the solution at the bottom and skip the why and how.

What is a FULL OUTER JOIN?

It’s easiest to describe the results. Let’s say we have two tables as shown below:

If I want to query the database view USER_TAB_COLS to get the results above, A FULL OUTER JOIN will do it. A FULL OUTER JOIN will get all of the data from two data sets, aligning those that match and putting nulls where they do not…but it’s not super easy.

How to Get There

If I run the following query:

select column_name
  from user_tab_cols
  where table_name = 'CAR'

I will get one row for each the columns for the CAR table: 7 rows. And, of course, if I change the table_name to TRUCK I will get 7 rows, but there will be 2 different rows.

If I want all of the columns that exist in both tables I would use an INNER JOIN:

select t1.column_name car_column, t2.column_name truck_column
  from user_tab_cols t1
  inner join user_tab_cols t2
    on t2.column_name = t1.column_name
    and t2.table_name = 'TRUCK'
  where t1.table_name = 'CAR'

I will get one row for each the columns that are in both tables: 5 rows.

But what if I want the results of the table above? In this case I need to have one row for every row that is in either table, but if they match, they should be on the same row. This is where the outer join comes in, but it’s not as simple as you might think. If I just change it to a LEFT OUTER JOIN I get the following:

select t1.column_name car_column, t2.column_name truck_column
  from user_tab_cols t1
  left outer join user_tab_cols t2
    on t2.column_name = t1.column_name
    and t2.table_name = 'TRUCK'
  where t1.table_name = 'CAR'

That happens because the where clause will ONLY bring back the rows “where t1.table_name = ‘CAR’”. I still sometimes think that just using a FULL OUTER JOIN will fix this. But the following query brings back the same 7 rows.

select t1.column_name car_column, t2.column_name truck_column
  from user_tab_cols t1
  full outer join user_tab_cols t2
    on t2.column_name = t1.column_name
    and t2.table_name = 'TRUCK'
  where t1.table_name = 'CAR'

For the same reason as the left outer join, the query above can only bring back 7 rows. This is where things get complicated with a FULL OUTER JOIN. I need a WHERE clause that will allow for any row in either table. And this is where things get a little strange. I would think that this would bring back everything I want:

select t1.column_name car_column, t2.column_name truck_column
  from user_tab_cols t1
  full outer join user_tab_cols t2
    on t2.column_name = t1.column_name
    and t2.table_name = 'TRUCK'
  where (t1.table_name = 'CAR' or t1.table_name is null)
    and (t2.table_name = 'TRUCK' or t2.table_name is null)

But it doesn’t! I still only get 7 rows—the same rows returned with a LEFT OUTER JOIN. If I want to get all 9 rows, I need to fully understand the FULL OUTER JOIN. Well, I’ll admit, I don’t. I just know how to get it to work:

select t1.column_name car_column, t2.column_name truck_column
  from user_tab_cols t1
  full outer join user_tab_cols t2
    on t2.column_name = t1.column_name
    and t2.table_name = 'TRUCK'
    and t1.table_name = 'CAR' -- <= this is key
  where (t1.table_name = 'CAR' or t1.table_name is null)
    and (t2.table_name = 'TRUCK' or t2.table_name is null)

That’s right. You need that extra AND condition in the FULL OUTER JOIN. It seems strange that an AND brings back more rows, but it does. The query above gives all 9 rows to match the very first table in this blog post.

This is great, but that query is slow. It takes over 2 seconds in my environment. That’s because the database has to look through the whole user_tab_cols view to do all of its work.

The Solution

I can speed things up by telling the database to only consider the rows I care about in each table/view (in this case I’m using the same view, USER_TAB_COLS, twice). I can do this with a CTE (a WITH clause):

with 
t1 as (
    select table_name, column_name
      from user_tab_cols
      where table_name = 'CAR'
),
t2 as (
    select table_name, column_name
      from user_tab_cols
      where table_name = 'TRUCK'
)
  select t1.column_name car_column, t2.column_name truck_column
  from t1
  full outer join t2
      on t2.column_name = t1.column_name
-- Now you don't need the following 4 lines
--      and t2.table_name = 'TRUCK'        
--      and t1.table_name = 'CAR' -- <= this is key
--  where (t1.table_name = 'CAR' or t1.table_name is null)
--    and (t2.table_name = 'TRUCK' or t2.table_name is null)

It runs in just 10% of the time—less than .2 seconds in my environment.

In my experience, this is how you should write a FULL OUTER JOIN.

1. Use CTEs (with clauses) to define the data set of each table in the FULL OUTER JOIN.

2. Create the main query with just a FULL OUTER JOIN—no where clause required.

Really, that’s the gist of this blog post, but I will elaborate. Number 11 of my post on Writing Fast Queries is that joins (and where clauses) should have indexed columns. Joins almost always involve a foreign key (FK). Every FK should have an associated index. Always. Sometimes we miss them, but there is an easy way to find them.

1. Navigate to SQL Workshop > Utilities > Object Reports.

2. Under the heading “Exception Reports”, select “Unindexed Foreign Keys”.

   

3. If there are any results, create the recommended indexes.

4. This is an interactive report…so you can subscribe to it.
   Enable “Skip if No Data Found” so that you only receive the report if there is an issue.

   

That’s it.

Bonus: There are several other exception reports. You may want to subscribe to some of those as well.

• Authentication (AuthN) uniquely identifies who the user is.

• Authorization (AuthZ) determines what the user can do.

TLDR

If you use a verify function or other method within the Authentication Scheme with social sign-on (Google, Azure, Facebook, OIDC, etc.) to invalidate a user that passes the social sign-on (for example, the user's email address is not in your domain), the user will not get any feedback as to why they are not able to authenticate. They will just get redirected back to the login screen (which they successfully logged into already). Instead, use an application level Authorization Scheme and modify the error message as described below.

The Longer Story

It seems simple but people, myself included, often embed some authorization into our authentication process. In many cases you have no choice. If you do your own authN, for example via APEX workspace users, database users, a table of users and passwords, even a corporate LDAP server, those users are the only users you can positively identify. If you can't identify them, they can't authenticate to your application. Let's take the case of LDAP users, though. Your company may include many users in the LDAP server that are not allowed to use the application you have developed. Should your authN scheme reject those users, or should there be an authZ scheme that rejects them. If we follow the strict guidance above, it should be an authZ scheme (not the authN scheme). This is even more striking if you use a public authN mechanism, for example Google or Facebook authentication. You may authenticate a user that has nothing to do with your application at all. Should you reject the user at the point of authentication, or should the user be rejected via authorization...or both?

This is probably a good time to mention that if you are a more visual learner, you can watch APEX Instant Tips Episode #132 for much of the same info.

I admit, there are solid arguments to rejecting the authentication if the user is not a valid user of your system. Perhaps I use Azure or Google to authenticate my users...and my users all must have an email address in the @inielsen.net domain. One could argue that any user with an email address in a different domain is "not a user" and, therefor, should not be able to authenticate. As described in the TLDR, there is a practical reason, however, to allow the user to authenticate and then stop the user at the point of application authorization instead of at the point of authentication. If you use the Authentication Scheme the user will not get any feedback as to why they are not able to authenticate. The user simply gets redirected back to the login screen. By using an application level Authorization Scheme the user will get an error page. You can customize the error they receive, allowing you to tell the user why they can't use the application.

In short, instead of repeatedly seeing this (with no indication why)

your user will successfully login but then receive a customized message like this:

How To...

Step 1: Configure your AuthN Scheme without any additional checks--no extra session verify function or anything beyond the standard authentication.

Step 2: Create an AuthZ scheme that does the check you would like. It will look something like this:

Step 3: Edit the Application Definition > Security. Add you application level AuthZ scheme:

Step 4: Configure the additional error message...the portion that will show below the error message in the image directly above. Navigate to Shared Components > Globalization > Text Messages. Create a new text message with the name APEX.AUTHORIZATION.ACCESS_DENIED.APPLICATION. (For more on this topic see APEX Cataclysmic Failure Messages.)

It will look something like this:

The End

That's all folks. Happy authenticating...or authorizing.

One of my favorite ways to accomplish this is by using the APEX "Weighted Page Performance" report. You click the person with the wrench at the top right of the APEX builder, and then "Monitor Activity."

Then choose "By Weighted Page Performance."

I suggest setting "Since" to "1 Week."

If you are interested in a specific application you can set that as well. The key column here is "Weighted Average." It is the primary order by column, ordered descending for a reason. This column takes into account both how often the page is utilized and how long the page takes to build. You can see the first row above has a fast execution time (Average Elapsed), so there is not much to do there. But the second and third rows are quite slow.

If users rarely visit a page, and it is slow, it may not be that critical to look at. But if a page is just a little slow, but used a LOT, then you may want to look at it soon. A high weighted average indicates two things: the amount of time your users are "wasting" waiting, and the overall impact on the system (how much compute, read/write, etc. the database is using).

Those pages are definitely targets for improvement. Checking this report regularly will give you areas of concern. It's worth adding a performance improvement task to your next development sprint for any slow pages near the top of this list. I love including a message about a code promotion that include "Improved performance of the Assignment Creation page" and getting a response "Oh right! I've been meaning to open a bug about that but you’ve already fixed it!"

Of course, you want to find out about these regularly, so create a report subscription.

Choose Actions > Subscription

and set up a subscription to send the report to yourself once a week.

Notice I'm doing this in the production environment. If you don't have access to this report in production, ask someone who does to create a subscription with your email address.

And, if you can't do that, create an interactive report in an application you have access to in production. Then subscribe to that report. The report query should be something like this:

select 
       application_id, 
       page_id, 
       application_name,
       page_name,
       count (*)                page_events,
       avg(ELAPSED_TIME)                average_ELAPSED_TIMEsed_time, 
       avg(ELAPSED_TIME)*count(*)       weighted_average,
       median(ELAPSED_TIME)             median_ELAPSED_TIMEsed_time,
       median(ELAPSED_TIME)*count(*)    weighted_median,
       (median(ELAPSED_TIME)*count(*)) - (avg(ELAPSED_TIME)*count(*)) median_to_avg_delta,
       max(ELAPSED_TIME)                maximum_ELAPSED_TIMEsed_time,
       min(ELAPSED_TIME)                minimum_ELAPSED_TIMEsed_time,
       max(ELAPSED_TIME) - min(ELAPSED_TIME)    maximum_minimum_delta,
       median(content_length)  median_content_length
from apex_workspace_activity_log l
where 
    VIEW_DATE >= (sysdate - nvl(7,1)) 
group by application_id, page_id, application_name, page_name

Go ahead and modify that query to your liking.

If you've made it this far please do this today and let me know if you did. I'm always pleased to hear that someone actually implemented a suggestion.