APEX 5.0 Icon List widget

[As of this writing, APEX 5.0 is only available as a pre-production version installed on apex.oracle.com and might change until it gets released.]

There are so many new things in APEX 5.0 that it is difficult to decide where to start. So, for no particular reason, I’ll start with the icon list widget, which is something that I worked on. The first place you will most likely run into the icon list widget is in Page Designer. Edit any page and at the bottom of the Grid Layout tab you will see a gallery of Regions, Items, and Buttons. At first glance it looks like an ordinary list of images somewhat like the Badge or Cards list templates in Universal Theme. But there are important behavioral differences mainly around accessibility.

Icon list behaves like a select list with the difference that options (items) are arranged in a 2D grid and can have rich content such as an icon and label. In fact its WAI-ARIA role is “listbox”. It occupies a single tab stop and then uses arrow keys to select items. This makes it much easier for keyboard users to navigate the page because they don’t have to tab through dozens of items. To address the needs of screen reader users, audible text is added that says how many rows and columns there are.

The other place icon list is used is in various wizards such as the Create an Application and Create a Page wizards. Icon list is designed as a general purpose jQuery UI based widget. It also handles multiple selection, although the APEX builder never uses that.

Because the APEX builder (Application Builder, SQL Workshop etc.) is built with APEX it is not completely unreasonable to see something that the builder does and wonder how you can do the same thing in your application. Any APEX app is made up of standard APEX components but can also include third party plug-ins or other custom code. Sometimes the custom code is so application specific that it could never be used by another application. A good example of that is the Grid Layout tab in Page Designer. The icon list widget is general purpose but it is not a standard APEX component. (We have to prioritize working on what will have the biggest benefit to the most customers.)

The rest of this post will show you how you can add the icon list to your APEX application. Keep in mind that icon list is not a standard APEX component. It is unsupported by Oracle Corporation. What I am showing here may not work in a future release of APEX or may work differently. The code provided here in the demo app and plug-in are provided as-is and without warranty.

I created a demo app that you can try out or download. I won’t describe step by step how to build the app but I will describe some of the new things in APEX 5.0 that make it easier to integrate a JavaScript widget like icon list. So even if you have no need for icon list there may be still something of interest here.

The icon list is used in two different ways. One is as a list template and the other is as an item plug-in.

APEX 5.0 has an awesome new feature of list templates that allows you to associate JavaScript code and CSS with the list template markup. In essence this turn a list template into a reusable widget. In the past when you needed to give the list markup some behavior or style you had to either separately make sure that the right JavaScript and CSS files were loaded on any pages that used the list template or add the script or style tags in the list template. The first option is a maintenance problem and makes it difficult to share the template with others. The second option often causes problems because of duplication if the list template is used more than once on a page. It may also result in invalid or inefficient markup.
With APEX 5.0 you can specify the JavaScript and CSS files and inline code that the list needs right in the list template. The substitution token #PARENT_STATIC_ID# or #LIST_ID# allows the JavaScript code to target the specific list markup. APEX takes care of making sure that the files are loaded on the page at most once.

This can be seen if you install the demo app, go to Shared Components > Templates and open the Icon List template. Notice that the list is given a unique ID in the Before List Entry template using:

id="#PARENT_STATIC_ID#_iconlist"

In the JavaScript section the icon list widget file is loaded with this line:

#IMAGE_PREFIX#libraries/apex/#MIN_DIRECTORY#widget.iconList#MIN#.js

The Execute when Page Loads attribute contains code that turns the list into an icon list.

var e = apex.jQuery("##PARENT_STATIC_ID#_iconlist", apex.gPageContext$);
e.iconList({
    multiple: false,
    navigation: true,
    label: ".item-label"
});

Like any jQuery UI style widget it is created by selecting an element and invoking the widget method with an options object. You can read the source file to learn about all the options and methods the widget has. Notice how the id #PARENT_STATIC_ID#_iconlist is used to locate the list.

The rest of the code selects the first item of the list (something that is nice to do for single selection lists), responds to window size changes, and conditionally enables tooltips.

e.find(".item").first().each(function() {e.iconList("setSelection", apex.jQuery(this));});
apex.jQuery(window).on("apexwindowresized", function() {e.iconList("refresh")});
if (e.hasClass("js-tooltip")) {
    e.tooltip({
        items: "li",
        show: apex.tooltipManager.defaultShowOption(),
        position: { my: "left-20 top-20", at: "right bottom", collision: "flipfit" },
    });
}

When the browser window sizes changes the width of the list region will most likely change and when the icon list widget size changes the “refresh” method must be called (so it can recalculate the rows and columns). What is interesting and new to APEX 5.0 is the undocumented “apexwindowresized” event. This event fires after the user stops resizing the window. This is useful because browsers may send a large number of resize events and processing each and every one of them can be too expensive.

Tooltips are not a built-in feature of the icon list widget but it is easy to use the jQuery UI tooltip widget to provide tooltips for each item as is shown here. What is interesting about this example is that it shows how the new APEX 5.0 template options feature can be used to control behavior as well as style. The template option “Include Tooltip”, which was defined as part of this list template will add the class js-tooltip to the markup (via. the #COMPONENT_CSS_CLASSES# substitution) when that option is checked. The JavaScript code looks for that class and if it is present enables tooltips. There is nothing special about the js- prefix it is just a convention we use to distinguish a CSS class that is only intended to be used by JavaScript.

Take a look at the demo app to see how this list template can be used for navigation. There are demo pages with descriptions of features such as right-to-left direction support and template options to select different sizes.

As the above list template shows icon list can be used for navigation but it is more naturally suited to single or multiple selection of items. To use it this way I created an item plug-in called Icon Select List that can be used as a drop in replacement for the built-in select list item. You can see this used in the demo app and can download the plug-in here (and hopefully soon on the apex plug-ins page).

Like the built-in select list, Icon Select List supports cascading, refreshing, single or multiple selection and submitting the page or redirecting to a URL when the selection changes. In addition it supports customizable item sizes and submitting the page or redirecting to a URL on activation. Activation is performed by pressing the Enter key or double clicking on an item. It also has an advanced context menu feature. For each item it supports these optional list of value columns: icon, extra details, tooltip, CSS class, and url. The url is an advanced option for use with custom JavaScript.

Patrick Wolf has already covered a number of APEX 5.0 plug-in enhancements so I will just mention the ones that were specifically important to icon select list.

Icon select list uses the “declarative load JavaScript and CSS files” feature to load the plug-in files as well as the icon list widget file.

There is a new plug-in attribute called Standard Form Element that icon select list “uses” by not checking the option. This option is for proper accessibility. You should only check this option if the item plug-in uses a standard form element such as input or textarea. If not checked then apex_plugin_util.get_element_attributes will automatically add the aria-labelledby attribute so that the item is correctly labeled for assistive technology. Icon list widget does not use a standard form element. I choose not to call get_element_attributes and instead rendered the aria attribute manually with:

' aria-labelledby="' || p_item.label_id || '" '

Another thing that I found very helpful while creating both the item plug-in and the list template is the new APEX 5.0 Code Editor.

The icon list widget is very flexible in what it allows for markup (it doesn’t even need to include an icon). The important constraints are that CSS is used to make all the items the same size and the items don’t contain interactive elements such as inputs or buttons. Using the list template and plug-in provided here you should be able to modify the markup and CSS to achieve the look you desire.