Saturday, 23 June 2012

Two Apex 4.2 Noteworthy APIs

Well, yesterday oracle released the first early adopter of application express, having had a chance to have a little play around, these are the ones that caught my attention:



There are currently some interactive reports utility functions/procedures as part of the apex_util package. These will now be deprecated, and functionality will be added to a package named APEX_IR.

The most exciting addition is the ability to get the derived IR query (from added filters/sorts). Without any published API docs, I can only assume this is through the function get_report. Further, I set up an example on page 2 of the sample database application. Created a new popup page with a dynamic region with the following source:


 l_report apex_ir.t_report;


    l_report := apex_ir.get_report(
        p_region_id => 6506762112827941367,
        p_page_id => 2);

    htp.p('<br />');htp.p('<br />');
    htp.p('<p><strong>BIND VARIABLES:</strong>');
    htp.p('<br />');
    htp.p('<br />');
    for i in 1..l_report.binds.COUNT LOOP
        htp.p('name: ' || l_report.binds(i).name || '<br />');
        htp.p('value: ' || l_report.binds(i).value || '<br />');



Where I got the p_region_id by querying the APEX_APPLICATION_PAGE_REGIONS data dictionary.

Then I added a button to page 2, to the right of the interactive report search "Show Source" pointing to that new page.




Well, any experienced apex developer will no doubt have used the undocumented htmldb_Get object to perform some form of AJAX request. I know I often use it to submit values of items to session state. With 4.2 comes some additions to the javascript API.

The new objects include:


The one I am most interested in is the apex.server.process. So how do we use it? Typing in the function name into the javascript console, reveals the following:

function ( pName, pData, pOptions ) {
    return _call( "APPLICATION_PROCESS=" + pName, pData, pOptions );

Obviously, pName is the name of the process if you want to submit, pData would be session items you would like to set, and can include the x0n variables you may be used to.

If you dig into the source a bit deeper, you will see that to set page items can be set by passing in an array of page item names with the property name: pageItems. Alternatively, if you want some other derived value you would pass respective values to p_arg_names and p_arg_values (arrays). Also you can set the x0n variables, which are referred to in the app process by wwv_flow.g_x0n. These are all passed into the pData object (2nd parameter).

Then there is the pOptions object. These are the properties you would expect to see in the jQuery AJAX API. Some cases I can imagine you would like to specify is the success/error callback(s), and specifying the dataType in case you would like to return text that is not JSON (as JSON is the default dataType specified).

So, some examples:

Submitting a page item, with the current value:

apex.server.process('ProcessName', {pageItems: ['P2_TEST'], x01: 'temp value'});

If you are returning text from the server, that is not json, i would suggest changing the type in the pOptions.

var respObj = apex.server.process('ProcessName', {pageItems: ['P2_TEST'], x01: 'temp value'}, {dataType: 'text'});

Otherwise, you will get a Parse Error / Syntax Error (as it is not in valid JSON).

Submitting session state to both a current page item, and an item not on the page (e.g. app item).

var respObj = apex.server.process('ProcessName', {p_arg_names: ['TEST_ITEM'], p_arg_values: ['Some value'], pageItems: ['P2_TEST'], x01: 'temp value'}, {dataType: 'text'});

On demand process used for testing:


    htp.p('App Item: ' || :TEST_ITEM || ' Page Item: ' || :P2_TEST || ' x Item: ' || wwv_flow.g_x01 );


Anyways, seems good. This is not based on any docs, so there may be some better recommendations come out in time. Happy coding!