Interactive Grid: Under the Hood

[This article is about a beta release of APEX 5.1 known as Early Adopter 1 so the details are subject to change]

One of the major and eagerly awaited features of APEX 5.1 is Interactive Grid; an editable data table supporting master-detail and much more. You can learn about Interactive Grid by signing up for a workspace at the Early Adopter site, installing the Sample Interactive Grids application, running it and trying out each example. Be sure to read the overview section of each page. I expect in the coming weeks there will be tutorials and other information from a number of people about the features of Interactive Grid and how to use it in various ways. But here I want to talk about its internal architecture.

Why is it important to know about the internal architecture of Interactive Grid? Its not. To use a car analogy most people don’t care to know how their car works. What matters is that it gets them from point A to point B and possibly looks good as well. But some people like to know a little about how the car works, what’s under the hood, even if they never intend to service or build a car themselves. This article is for those who like to know how things work, and I expect there are a fair number of them in the APEX development community.

Continue reading Interactive Grid: Under the Hood

Using Oracle JET from APEX

This post contains statements about possible future functionality. These are not official statements. They are speculative, subject to change, and should not be relied upon.

Reading svenweller’s recent article Integrate Oracle JET into Apex 5.0 got me thinking about this topic. I’m very busy working on Interactive Grid in APEX 5.1 right now but this is an important topic and there is a need to get some information out sooner rather than later. I’m not going to go into how JET and APEX are great, why it makes sense to use them together or provide step-by-step instructions for doing so. See svenweller’s blog for that.

By now most APEX developers have heard that we plan to include Oracle JET based charts in APEX 5.1. It is generally easy to use 3rd party JavaScript libraries with APEX. Here I want to talk about why Oracle JET is a special case and give some tips for making them work together. I want to share what we have learned so far in integrating JET charts with APEX. I should mention that I am not the main person working on the chart feature.

What makes using Oracle JET with APEX tricky is that JET requires you to use RequireJS. So the same issues apply if you were to integrate any code that uses RequireJS with APEX. It is not specific to Oracle JET. Furthermore, you would have similar issues trying to use JET with any traditional web app that isn’t already using RequireJS.

Is RequireJS bad? No. Is APEX somehow at fault? No. What’s going on here? Its complicated…

The traditional way of using JavaScript on a web page is to put it in script tags and call it. Lots of libraries? No problem. Just figure out what order to put all the script tags in. Each script file adds some global symbols for the others to use. Namespace objects are used to reduce the number of globals — its a kind of modularity. This is what APEX does. It is conceptually simple.

Then modules were invented as a way to keep code, well, modular and explicitly define what your module exports and what dependencies you have on other modules. Just one script tag and the module system (in this case RequireJS) does all the loading. The only globals are from the module system (define, require, requirejs). This is also conceptually simple but different concepts.

There is nothing wrong with either of these ways of building web apps. I have nothing against modules. I like using the Node.js module system. But APEX has a long history and simply cannot switch over to using RequireJS modules without breaking existing applications.

These are two very different worlds that don’t mix well. Its hard to ease into using modules because of what happens when the existing non-module code and the new module code wants to share a library.

If you are the creator of a handy library you want to increase your user base by being usable in both worlds. (I’ll use Hammer.js as the example simply because it is a library that both JET and APEX Universal Theme use.) Its easy to do, just add at the bottom of your code something like the following:

// this is just slightly simplified from the actual hammer.js code
if (typeof define == "function" && define.amd) {
    define(function() {
        return Hammer;
    });
} else {
    window.Hammer = Hammer;
}

Now the library can be used in a module system if the page is using one or just define a global for the traditional way.

But if a single page has some code that uses RequireJS and some code that uses the traditional way and both want to use the same library (Hammer.js in our case) there is a problem.

A) If the hammer.js script tag is loaded after require.js it defines an anonymous module as shown above and then as soon as you do anything else with RequireJS you get the error: Mismatched anonymous define() module. The reason is that RequireJS insists that all anonymous modules are loaded from a define or require call. The assumption is that as soon as RequireJS is on the page you are using the new modular way.

B) If the hammer.js script tag is loaded before require.js it defines its global Hammer object so that traditional code can use it. Then when module code uses require(['hammer'...]...) or something equivalent it will get a new copy of the Hammer object. You can prove this with the following code:

require(["hammerjs"], function( h ) { console.log( h === window.Hammer );});

If the the new module code and the global Hammer object were the same it would print true but it prints false. At least there is no error and it seems to work but… Ideally we would like to avoid this. Depending on what the library does it could result in more than just wasted memory.

We had a similar problem with jQuery where after RequireJS was used by JET Charts all our APEX jQuery UI widgets were essentially “gone” because there were two different jQuery objects ( $ !== apex.jQuery ). Note jQuery is a special case in that it defines a named, not anonymous, module so it doesn’t suffer from the error in case (A). You may also say that it is best to always use apex.jQuery rather than $ and you are correct but not everyone follows this rule all the time. And we still don’t want to waste memory on duplicate copies of libraries.

With this background out of the way here are my recommendations.

  • Load require.js as late as possible because problem B is much easier to deal with than problem A. (How to deal with problem B is coming up.)

    RequireJS would like to be the first (and only) script tag on the page but it doesn’t have to be. In order to keep any RequireJS aware libraries such as hammer.js or jQuery from calling define, require.js should be included after them. The best way to do this is to add require.js to a page in page attribute JavaScript: File URLs.

    With this approach you don’t need to throw out hammer.js just to use Oracle JET. Hammer.js is useful when running your app on touch devices.

  • You don’t need to use data-main on the require.js script tag. It is not required, just a convenience. Your code that includes the call to requirejs.config can be handled like any other JavaScript code. If you put it in a file, reference that file in JavaScript: File URLs (after require.js). It can even go inline by putting it in JavaScript: Execute when Page Loads.
  • To get around the problem of loading multiple copies of a library add the following code after the call to requirejs.config and before any calls to require
    define( 'hammerjs', [], function() {
        return Hammer;
    });
    define( 'jquery', [], function() {
        return apex.jQuery;
    });
    

    What this does is define the library module with a name in the RequireJS module system so that it will not be loaded again. It is important to use the same name that the library uses in the config paths object passed to requirejs.config. This can be extended to other libraries if needed.

    Note: If different versions of a library are needed then you may just have to let two copies be loaded. In this case remove the corresponding call to define.

  • You probably don’t need to use knockout. I don’t know for sure if this is true for all JET components but it is true for JET Charts. APEX 5.1 is not using knockout at all. I have nothing against knockout. However, it is of most benefit if it is used pervasively through out an app. Otherwise it is just another another library to load for which there are other ways to do what it does. That said, if you want to use it go ahead.

At this point I don’t know what if anything APEX 5.1 will do to make integrating Oracle JET (or RequireJS in general) easier. For now I hope this helps anyone trying to use JET with APEX 5.0.

How to identify Survey Builder respondent

It has been a while since I have worked on the APEX Survey Builder packaged application but I still get questions about it. One question that comes up repeatedly is how to associate the questionnaire responses with the person that responded. At first this question surprised me somewhat because survey research is about populations not individuals so surveys should be anonymous. To quote Designing an Effective Survey by Mark Kasunic:

“A survey, when conducted properly, allows you to generalize about the beliefs and opinions of many people by studying a subset of them”

Survey research lets you say with confidence “87% of our customers feel that the produce makes them more productive” not that John Snyders thinks he is more productive after using the product.

Continue reading How to identify Survey Builder respondent

APEX Item Submission

In his 3 part series ending with APEX and the Order Items are Submitted, Martin D’Souza did a great job explaining how APEX page items are submitted and why you can’t reorder the DOM in arbitrary ways. If you haven’t read it already it I strongly recommend that you do so. I can’t improve on how he explained it but I have just two things to add.

Why does APEX do this?

I was very confused by this when I first joined the APEX team. I think that others especially people with front end web development experience will also wonder why APEX uses p_arg_names and p_tnn names rather than the more traditional way where you get to name your inputs as you please. For example <input name="phone_number"...>.

Martin explains that the p_arg_names values are used to map the post parameter values back to the APEX item metadata. The other part of the puzzle has to do with how HTTP post parameters are passed into the APEX engine. The interface between the web listener and APEX Engine maps post parameters to PL/SQL procedure formal parameter names. So there is actually a PL/SQL procedure with formal parameters named p_arg_names and p_t01, p_t02…p_t200. The same procedure is used for all apps and all pages so this is why fixed names must be used.

A subtle and unfortunate consequence.

If you have used any APEX applications you have undoubtedly run into the situation shown in the following image where the browser auto complete feature offers suggestions that have nothing to do with the current field.

Auto Complete

How a browser implements the auto complete feature is up to the browser (meaning there is no common specification that must be followed) but the primary method of choosing what values to show is the name attribute. Fields with the same name tend to show the same auto complete choices. The underlying assumption that browsers are making is that web developers choose meaningful names for input fields such as firstName, phone_number, etc. With APEX this assumption fails. Because the name attribute is assigned automatically and sequentially, it is the order of the form item on the page that determines what auto complete values will be shown.

I’m a little surprised that more people haven’t complained about this. Its a tricky problem to solve and it may not even be worth solving. How bothersome do you find this?

APEX Interactive Report Checkbox Row Selection

The question of how to add checkboxes to interactive reports comes up often. Usually the problem is not getting the checkbox to display in a row but in how to do something useful with the checked state. There are many forum or blog posts on this topic but they all seem to be rather dated. Even when the general idea is still applicable they use outdated practices including:

  • Inline event handlers using onchange or onclick attributes. These should be dynamic actions.
  • HTML regions with script tags in them or script tags in the HTML Header page attribute. There are much better ways to get JavaScript on a page now. Consider JavaScript File URLs, Function and Global Variable Declaration, and Execute when Page Loads attributes as well as dynamic actions.
  • Making ajax requests using the htmldb_Get API. This should be replaced with dynamic actions or apex.server.process API calls.

So I thought I would take a stab at solving this problem.

Continue reading APEX Interactive Report Checkbox Row Selection

APEX 5.0 Custom Menus

This topic has been motivated by a few different APEX forum threads as well as direct questions from teammates. Here I will show how to add a menu button to each row of an interactive report that will open a menu and the menu item actions will be specific to the row.

Custom Menu Demo

The above pictured Custom Menu Demo is available to try out and to download. This article assumes some familiarity with APEX and JavaScript.

Simple Popup Menu

Before going into how to create a custom menu let me make sure that we all know how to create a simple list based popup menu.

Continue reading APEX 5.0 Custom Menus