Tuesday, August 30, 2016

Fix Interactive Report headers issue when using a Region Display Selector

When you have multiple Interactive Reports (IR) on your page and use a Region Display Selector to mimic tabs, you might notice some weird behaviour in the IR headings if you switch tabs. The headings are not positioned correctly and you get an extra empty row under the headings. It just looks weird and ugly. But if you resize your browser window, it all looks fine again (until you switch to another tab..)

So can we fix this by creating a Dynamic Action that mimics that "browser window resize" event?
Yes we can!

Create a Dynamic Action that fires on Click of the jQuery selector li.apex-rds-item a. That should fire a JavaScript snippet : 
apex.event.trigger(this.triggeringElement, "apexwindowresized");

So now a click on a tab not only switches from one IR to another but also fires that event that will "autofix" the IR headers. A simple solution for an annoying problem.

This applies to APEX 5.0, I assume it will be solved in 5.1.

Thursday, August 25, 2016

Creating an APEX plugin for an Oracle JET component - Part 2

In my previous blogpost I showed how you can embed an Oracle JET component in your APEX application. Now it is time to make a plugin out of the wisdom we gained doing so.
First of all a disclaimer. My intention is to make this plugin and the inner workings as simple as possible. So you can add a lot more functionality, checks etc and therefore add complexity. But this is intended to be as simple as possible.

The plugin consists of three parts: a PL/SQL render function, a snippet of JavaScript and a PL/SQL ajax function.

The render function is defined as :

function render 
( p_region                in  apex_plugin.t_region
, p_plugin                in  apex_plugin.t_plugin
, p_is_printer_friendly   in  boolean 
) return apex_plugin.t_region_render_result 
is

  c_region_static_id      constant varchar2(255)  := apex_escape.html_attribute( p_region.static_id );

begin
  -- Add placeholder div
  sys.htp.p (
     '<div class="a-JET-PictoChart" id="' || c_region_static_id || '_region">' ||
       '<div class="a-JET-PictoChart-container" id="' || c_region_static_id || '_chart"></div>' ||
     '</div>' );
     
  -- Load the JavaScript library   
  apex_javascript.add_library 
  ( p_name      => 'pictoChart'
  , p_directory => p_plugin.file_prefix
  );
  
  -- Initialize the chart
  apex_javascript.add_onload_code
  ( p_code => 'jet.picto.init('||
                  '"#'||c_region_static_id||'_chart", '          || -- pRegionId
                  '"' || apex_plugin.get_ajax_identifier ||'"'   || -- pApexAjaxIdentifier
                 ')'
  );
  
  return null;
end render;

So what it does in these three steps is :
1. Generate a DIV placeholder, just as we saw in that previous post
2. Load the JavaScript file "pictoChart.js",
3. Execute the JavaScript function "jet.picto.init" providing two parameters, the regionId of the DIV and the (internal) identifier of the PL/SQL ajax function.

The contents of the JavaScript file is :

! function (jet, $, server, util, debug) {
    "use strict";
    requirejs.config({
        baseUrl: apex_img_dir + "oraclejet/js/libs",
        paths: {
            "jquery": "jquery/jquery-2.1.3.min",
            "jqueryui-amd": "jquery/jqueryui-amd-1.11.4.min",
            "ojs": "oj/v2.0.0/min",
            "ojL10n": "oj/v2.0.0/ojL10n",
            "ojtranslations": "oj/v2.0.0/resources",
            "promise": "es6-promise/promise-1.0.0.min"
        },
        shim: {
            jquery: {
                exports: ["jQuery", "$"]
            }
        }
    }), jet.picto = {
        init: function (pRegionId, pApexAjaxIdentifier) {
            require(["ojs/ojcore", "jquery", "ojs/ojpictochart"], function (oj, $) {
                server.plugin(pApexAjaxIdentifier, {}, {
                    success: function (pData) {
                        $(pRegionId)
                            .ojPictoChart(pData);
                    }
                });
            });
        }
    }
}(window.jet = window.jet || {}, apex.jQuery, apex.server, apex.util, apex.debug);
// To keep ThemeRoller working properly:
define("jquery", [], function () {
    return apex.jQuery
});

The first function call (requirejs.config) is again the same is we did earlier. Please note that the paths mentioned in here might differ in your environment. You could define those paths as (Application level) Component Settings, but for simplicity I keep them hardcoded in this example.
Notice there is a "jet" namespace defined and within that namespace a nested "picto" namespace. So we could easily extend this file (after renaming it) to other chart types. The "init" method defines the required files and then calls apex.server.plugin passing the PL/SQL ajax function as a parameter. After this ajax function is called, the result - a JSON object - is passed to the ojPictoChart function.
On the last line, as Kyle Hu correctly commented in my previous post, we have to define jquery in order to make ThemeRoller work (again).
So in fact, the JavaScript is very straightforward: in the end just an ajax call passing the result into the ojPictoChart function.

So what is the magic of the last piece, the ajax PL/SQL function? Here it is::

function ajax
( p_region    in  apex_plugin.t_region
, p_plugin    in  apex_plugin.t_plugin 
) return apex_plugin.t_region_ajax_result
is
  c       sys_refcursor;
  l_query varchar2(32767);
begin  
  l_query := p_region.source;
  open c for l_query;
  apex_json.open_object;
  apex_json.write('items', c);

  -- add settings
  apex_json.write('animationOnDisplay' , p_region.attribute_01);
  apex_json.write('columnCount'        , p_region.attribute_02);
  apex_json.write('layout'             , p_region.attribute_03);

  apex_json.close_object;
  return null;
end ajax;

Thus it just takes the region source - a SQL statement -, executes it returning a JSON object. And to these results three of the available options, defined as plugin attributes, are added. Again, as simple as possible. So no validation on the correctness of the SQL (as all APEX Developers can write a correct SQL statement, right). And just a minor part of the available options are exposed in the plugin.

When you create a region based on this plugin you have to provide it with a correct SQL statement - one that will return a valid JSON object according to the pictoChart docs. For example:

select ename||' - '||job||'@'||dname "name"
,      'human' "shape"
,      1 "count"
,      case job
       when 'PRESIDENT' then 'black'
       when 'ANALYST'   then 'blue'
       when 'CLERK'     then 'green'
       when 'MANAGER'   then 'red'
       when 'SALESMAN'  then 'yellow'
       end "color"
from   emp
       join dept on emp.deptno = dept.deptno
order by 2 desc, 4

And if you set the settings as :


You'll get as a beautiful result:
So knowing this, it wouldn't be hard to rebuild the plugin by yourself. But for the lazy readers out there, you can download it here too.
Or probably build another plugin for another JET component!

Saturday, August 20, 2016

Creating an APEX plugin for an Oracle JET component - Part 1

In APEX 5.1 (still Early Adaptor 1 at this moment), Oracle JET - Javascript Extension Toolkit -  is included to facilitate charting.
The APEX Development Team recently mentioned that not only the Data Visualisations part of JET will be included in APEX 5.1, but the complete installation of JET. The whole package. That won't do the size of the downloadable install file any good, but more important is: what can we do with it?

A number of the Data Visualisations will be exposed in APEX for the declarative definition of charts as we are used to now using the Anycharts library. But there are more Data Visualisations - check the JET Cookbook for all examples - and other components that might be of interest for an APEX application. So how can we use these in our apps?

As an example, I would like to use the PictoChart component in my application.
Fist of all - as we don't have APEX 5.1 yet - we need to download the Oracle JET library and install the files on either your web server or upload all of them into the APEX Static Files. As there are a lot of files - and I mean, really a lot - I would recommend storing the files on your web server.

Next, if you follow the steps of the JET Cookbook, you'll notice that they all make heavy use of the Knockout Javascript library. Knockout is extremely powerful, but also rather complex for most APEX developers. And in an APEX environment we don't really need it. So can we use Oracle JET components without Knockout, as there is no example on the (official) JET pages?
But there is an un(der)documented feature, which is the "initializer" call of an Oracle JET component, click here to open that part of the documentation of the PictoChart component. That looks more familiar to us, as it is just an (old fashioned) Javascript call with a JSON object as a parameter! So how do we get that on an APEX Page?

First of all we need to include RequireJS into our application by referencing

    #IMAGE_PREFIX#jet/js/libs/require/require.js

in the "File URLs" property of our Page. Of course, the exact location is dependent on where you stored the JET library. Next we have to tell RequireJS where all the Oracle JET files are that we need to load. Therefore we call (in the "Execute when Page Loads" property of the page) :

    requirejs.config({
        baseUrl: apex_img_dir + "oraclejet/js/libs",
        paths: {
            "jquery"         : "jquery/jquery-2.1.3.min",
            "jqueryui-amd"   : "jquery/jqueryui-amd-1.11.4.min",
            "ojs"            : "oj/v2.0.0/min",
            "ojL10n"         : "oj/v2.0.0/ojL10n",
            "ojtranslations" : "oj/v2.0.0/resources",
            "promise"        : "es6-promise/promise-1.0.0.min"
        },
        shim: {
            jquery: {
                exports: ["jQuery", "$"]
            }
        }
    })

Now, also in the "Execute when Page Loads" property of the page, we can call the initializer of the PictoChart component :

    require(['ojs/ojcore', 'jquery', 'ojs/ojpictochart'],
      function (oj, $) {
        $("#pc1").ojPictoChart(
           {items: [
              { name  : 'Have  Sleep Problems'
              , shape : 'human'
              , count : 7
              , color : '#ed6647'
              },
              { name  : 'Sleep Well'
              , shape : 'human'
              , count: 3
              }]
           , animationOnDisplay: 'zoom'
           , columnCount: 5          
        });    
    }); 

and finally we need to define component with the id "pc1" above mentioned into where the PictoChart is rendered by creating a region serving static content:

<div  id="picto-container">
  <div id='pc1'style="vertical-align:middle; margin-right:15px">
  </div>
  <div style="display:inline-block; vertical-align:middle; font-weight:bold">
    <span style="color:#333333; font-size:1.1em">7 out of 10 college students</span><br>
    <span style="color:#ed6647; font-size:1.3em">have sleep problems.</span>
  </div>
</div>

As a result we will see the exact same PictoChart as shown above in our APEX Page.
In the next blog post I will show how to convert this hard-coded data into an easy-to-use APEX plugin.

So stay tuned !








Friday, August 12, 2016

Consuming a REST Web Service returning JSON in APEX

In APEX you can define a web service that returns XML as below - all declarative, just a few steps through a wizard.


Then generate a report on top of that web service - again just a few clicks through a wizard. The generated query looks like this:

select xtab."customerName"
     , xtab."customerId"
  from apex_collections c, 
          XMLTable('/Response/S_getCustomerListTableArray/S_getCustomerListArrayItem' passing xmltype001
            COLUMNS "customerName" PATH 'customerName'
                  , "customerId"   PATH 'customerId'
          ) xtab
 where c.collection_name = 'CUSTOMERLIST'

So the result of the web service is stored in an XMLTYPE column. And it's easy to spot where you're definitions for the Response XPath and Output Parameters are used.

But what if your web service returns JSON - as more and more web services will do so? If you switch the Output Format of the web service definition to JSON, the Response XPath property and the Output Parameters are not enterable. And if you generate a report on top of that web service, the resulting query is a - disappointing - 

select c.clob001
from apex_collections c
where c.collection_name = 'CUSTOMERLIST'

and your report will show a JSON dump. Not exactly what you're hoping for. And notice the result is stored in a CLOB.

But since 12c, the JSON support in the Oracle database has improved a lot and we can easily use that in our query. So if we rewrite our query to 

select cust.*
from   apex_collections
,      json_table(clob001, '$.Response.S_getCustomerListTableArray.S_getCustomerListArrayItem[*]'
       columns ( "customerName"   PATH '$.customerName'
               , "customerId"     PATH '$.customerId'
               )) cust
where collection_name = 'CUSTOMERLIST'

we will get the same result as the - old fashioned - XML one! And as you can see the code is very much alike and could be generated by APEX itself just like the XML version.

So I expect that in a future version this functionality will be added to the APEX builder - it shouldn't be that hard to implement! And maybe the apex_collections can have a real "JSON" column as well (in fact it would still be a CLOB with an "IS JSON" check).

The only prerequisite is, you have to run APEX on version 12c of the database. If you want to know more about JSON in the database, there is a serie of blog posts about this, starting here.