APEX item Quick Picks as Context Menu

Quick picks are those links below form inputs that serve the role of shortcuts to often-used values. They are meant to increase end-user experience by speeding up interaction with form inputs.

Example of native Quick Picks for Textfield and Select list

In this article, I will describe the existing approach to quick picks which is known only in an APEX page designer. This approach makes quick picks consuming less space in form and optionally can provide extra functionality – ie. clearing field value.

Quick picks transformed to field menu with extra functionality clearing field value.

If you want to learn how you can transform existing quick picks in your application to menu popup then keep on reading. I will show you how you can achieve such a result with a simple APEX list, two dynamic actions and Pretius APEX Context Menu plug-in.

Quick Picks in APEX application builder

Every Oracle APEX developer is familiar with quick picks because they are being used in everyday APEX development. In the older versions of APEX, they were standard clickable anchors presented below most components.

Quick pick in older Oracle APEX application builder
Source: Oracle APEX Documentation

Starting with APEX 5 new era has started – Page designer was introduced – and as a result, the development process was speeded up again by providing a new way to configure multiple page components. Page designer layout is more compact and there is no space for quick picks we know from earlier versions. It doesn’t mean they have disappeared. They are still available in some application builder pages as ordinary anchors – ie., to set a condition of list entry:

Old fashion quick picks in Oracle APEX Application Builder

In the case of page designer they are still there but wrapped into a single button with a dropdown menu. They don’t take extra space and they are very convenient to use – only when APEX developer needs them.

Quick Picks in Oracle Application Express Page Designer

So, if they are used in page designer, then there must be a way to use them in your application. To make it work you can use native menu widget API but the implementation might give you a headache. Or you can use my recent plugin Pretius APEX Context Menu which simplifies the implementation of APEX menu popup.

Preliminary assumptions

I assume:

  • you will be reproducing instructions at apex.oracle.com using APEX 19.1 [1],
  • you have created page 1110 with example region on which you will implement this guide,
  • you have installed Pretius APEX Context menu v1.1.0 in your application.

Universal Theme classes between APEX 5.1, 18.x and 19.x migh differ a little bit. Still this implementation guide will work on every APEX version starting from APEX 5.1 and ending on 19.1 after some classes adjustment. For example floating template is not available in APEX 5.1. Keep this in mind!

side note [1]

Example implementation for an existing page

In the previous article, I have described a changelog for version 1.1.0. Those changes were made to extend the possible usage of the plugin. Transforming quick picks into menu popup is a good example.

To make it the simple implementation guide let me use the example for two fields only:

  • text-field
  • select-list

Those items will be created on page 1110 in an existing region. The result of this guide will be similar to this example demo page at apex.oracle.com.

Create APEX items
  1. Create Page Item P1110_PLUGIN_TEXTFIELD
  2. Set Appearance / Template to Option – Floating
  3. Set Quick Picks / Show Quick Picks to Yes
  4. Create three quick picks, for each set
    • Label X to Quick Pick X
    • Value X to X
  1. Create Page Item P1110_PLUGIN_SELECT_LIST
  2. Set Appearance / Template to Option – Floating
  3. Set Quick Picks / Show Quick Picks to Yes
  4. Create three quick picks, for each set
    1. Label X to Quick Pick X
    2. Value X to X

where X is a number starting from 1 to 3.

Create APEX list

Go to Shared Components / List and click the button Create. Wizard for creating APEX list will appear and you have to follow these steps:

  1. Select Create List / From Scratch
  2. Click button Next
  3. Set Name to QUICK_PICK_MENU
  4. Set Type to Static
  5. Click button Next
  6. Create two entries:
    1. set List Entry Label to Clear and Target Page ID or custom URL to javascript: void(0);
    2. set List Entry Label to Separator
      and Target Page ID or custom URL to javascript: void(0);
  7. Click button Next
  8. Review summary and click button Create List

As a result, the new list is created, now go to editing list QUICK_PICK_MENU. At this point, you need to finish the list configuration on entry-level.

Clear entry:

  1. Edit entry Clear
  2. Set Entry / Image/Class to fa-eraser
  3. Set User Defined Attributes / Attribute 1 to CLEAR
  4. Click button Apply Changes

Separator entry:

  1. Edit entry Separator
  2. Set User Defined Attributes / Attribute 7 to separator
  3. Click button Apply Changes

A newly created APEX list is ready to be used in the plugin implementation. Now we need to define dynamic actions which will transform existing quick picks into menu popup.

Dynamic Actions

To make the implementation generic (which means you won’t change properties of APEX items) you need to implement two dynamic actions.

First dynamic action will be executed for Page Load event and its purpose is to

  • create a button which will invoke quick pick menu for a given field
  • hide existing quick picks
  • prepare JSON object that will be used by the plugin to compute a menu entries (quick picks) and will provide a reference to a button which will be the plugin triggering element
  • trigger custom event which will initialize the plugin.

Follow these steps:

  1. Create a dynamic action called Transform quick picks
  2. Set Execution Options / Sequence to 20 [2]
  3. Set When / Event to Page Load
  4. Change default show true action to Execute JavaScript Code
    1. Set Affected Elements / Selection Type to Item(s)
    2. Set Affected Elements / Item(s) to P1110_PLUGIN_TEXTFIELD,P1110_PLUGIN_SELECT_LIST
    3. Set Settings / Code to
$(this.affectedElements).each( function(){
  var 
    button = $('<button type="button" class="a-Button a-Button--popupLOV"></button>'),
    icon = $('<span class="a-Icon icon-popup-lov"></span>'),
    label = $('label[for='+this.id+']').text(),
    visuallyhidden = $('<span class="visuallyhidden">Popup List of Values: '+label+'</span>'),
    item = $(this),
    data;

  //build up button and insert it after item
  button.append( icon.append( visuallyhidden ) ).insertAfter( item );

  data = {
    "item": item,
    "element": button,
    "quickPicks": item.closest('.t-Form-inputContainer').find('.apex-quick-picks').hide()
  };

  apex.event.trigger(document, 'overrideItemQuickPicks', data);

});
Comments to Execute JavaScript Code true action
  • lines from 3 to 6 and line 11 builds up the button which is normally used by Popup LOV APEX item.
  • data variable defined in lines 13-17 is used by dynamic action Initialize Pretius APEX Context Menu

Second dynamic action will listen to the custom event and based on dynamic action data (this.data) will

  • compute menu entries (quick picks)
  • initialize the plugin on the given button (dynamically created)

Follow these steps:

  1. Create a dynamic action called Initialize Pretius APEX Context Menu
  2. Set Execution Options / Sequence to 10 [2]
  3. Set When / Event to Custom
  4. Set When / Custom Event to overrideItemQuickPicks
  5. Set When / Selection Type to JavaScript Expression
  6. Set When / JavaScript Expression to document
  7. Change default Show true action to Pretius APEX Context Menu [Plug-in]

Configure the plugin:

  1. Set Settings / List name to QUICK_PICK_MENU
  2. In Settings attribute check following options: Override Behaviour and Add Extra Entries
  3. Set Settings / Override Behaviour to
return {
  "CLEAR": {
    "action": $.proxy(function( pMenuOptions, pTriggeringElement ){
      $( this ).val(null).trigger('blur')
      return false;
    }, this.data.item.get(0))
  }
};
Comments to Override Behaviour code

Here is used the advantage of the plugin implementation which allows you to override list entry Clear with User Defined Attributes / Attribute 1 set to CLEAR.

  • In line 6 context (this) of action function is changed to APEX item
  • In line 4 value of item is set to null (cleared) and triggering blur event forces floating template to correctly position item label
  1. Set Settings / Extra Entries to
var entries = [];

this.data.quickPicks.find('a').each(function(){
  entries.push(  
    {
      "type": "action", 
      "labelKey": $(this).text(),
      "action": $.proxy(function(){
        $(this)[0].click();
        return false;
      }, this)
    }
  );

});

return entries;
Comments to Extra Entries code

This code iterates through all quick picks defined for an item and it is creating menu entries using defined JSON structure. The returned array is used by the plugin to extend the existing list with new entries – which are quick picks.

  • Line 11 – context of the action function is changed to quick pick anchor
  • Line 9 – will trigger a click event on quick pick anchor which is generated by APEX
<!--example quick pick html-->
<a href="javascript:$s("P1110_NATIVE_SELECT_LIST","1","Quick pick 1");">Quick pick 1</a>
  1. Set Execution Options / Fire on Initialization to No

The reason for those Execution Options / Sequence values for both dynamic actions is that the execution time of registereing dynamic action events occurs on Page Load event. If you want to trigger custom event from Page Load event then custom event must be already registered. Thus sequence matters!

side note [2]

Implementation on Magic Page 0

You might want to enhance quick picks on every page in your application. For this scenario, you can define those two dynamic actions on Magic Page 0. Dynamic action Initialize Pretius APEX Context Menu can be as it is.

In case of dynamic action Transform quick picks you need to change approach for computing quick picks, creating button and referencing items (Execute JavaScript Code true action). You might want to iterate through all items that have quick picks defined instead of giving the exact items names.

Because of that, you will need to change dynamic action Affected Elements / Selection Type from Item(s) to jQuery Selector with Affected Elements / jQuery Selector set to

.apex-quick-picks

Because

this.affectedElements 

will reference quick picks defined for every item. This is different approach and you have to change Execute JavaScript Code / Settings / Code to

$(this.affectedElements).each( function(){
  var 
    button = $('<button type="button" class="a-Button a-Button--popupLOV"></button>'),
    icon = $('<span class="a-Icon icon-popup-lov"></span>'),
    item = $(this).closest('.t-Form-fieldContainer').find('.t-Form-itemWrapper :input'),
    label = $('label[for='+item.attr('id')+']').text(),
    visuallyhidden = $('<span class="visuallyhidden">Popup List of Values: '+label+'</span>'),
    data;

  button.append( icon.append( visuallyhidden ) );

  item.after( button );

  data = {
    "item": item,
    "element": button,
    "quickPicks": $(this).hide()
  };

  apex.event.trigger(document, 'overrideItemQuickPicks', data);

});

That is all you need to do to transform your existing quick picks into menu popup. Your implementation should look like at the demo page.

I will be happy to read your feedback in the comments section!

Ostrowski Bartosz

Oracle APEX Developer @PretiusSoftware

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *