Giters

Pretius / Pretius-APEX-Context-Menu

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Pretius APEX Context Menu

Pretius APEX Context Menu is dynamic action plugin implementing APEX popup menu based on defined APEX list. The plugin can be attached to any HTML element and renders entries according to authorisation scheme result. Menu entries can be extended by overriding behaviour, dynamically adding submenu and by adding new entries.

Preview

Preview gif

Table of Contents

License

MIT

Demo application

https://apex.oracle.com/pls/apex/f?p=PRETIUS_APEX_CONTEXT_MENU:1

Features at Glance

  • compatible with Oracle APEX 5.1, 18.x, 19.x
  • basic usage doesn't require JavaScript knowledge
  • uses native APEX menu widget
  • based on APEX list
    • supports authorization schemes
    • supports basic conditions
  • list entries can be extended on runtime
    • to override action on click
    • to disable entry
    • to hide entry
    • to add submenu defined outside APEX list
  • can be bind with any DOM element

Roadmap

  • not yet available

Install

Installation package

  • PRETIUS_APEX_CONTEXT_MENU.sql - the plugin package specification
  • PRETIUS_APEX_CONTEXT_MENU.plb - the plugin package body
  • dynamic_action_plugin_com_pretius_apex_contextmenu.sql - the plugin installation file for Oracle APEX 5.1 or higher

Install procedure

To successfully install the plugin follow those steps:

  1. Install package PRETIUS_APEX_CONTEXT_MENU in Oracle APEX Schema
  2. Install the plugin file dynamic_action_plugin_com_pretius_apex_contextmenu.sql

APEX list integration

Conditions

The plugin checks entry defined conditions. For conditions types

  • PLSQL_EXPRESION
  • PLSQL_EXPRESSION
  • FUNC_BODY_RETURNING_BOOLEAN
  • EXISTS
  • NOT_EXISTS
  • NEVER

result is evaluated and if condition is not met then entry is not rendered. If entry condition is other type than listed above then entry is not rendered.

Authorization schemes

The plugin checks entry defined authorization scheme. If current result is true then entry is rendered.

User defined attributes for list entry

The plugin uses user defined attributes to change behaviour of the list entry. See table below

Property Description
Attribute 01 id used to identify entry
Attribute 02 when set to true then entry is disabled
Attribute 03 when set to true then entry is not rendered
Attribute 04 reserved by APEX navigation template to set title. Not working (?)
Attribute 05 reserved by APEX navigation template to set shortcut (?). Not working (?)
Attribute 06 provided text is used as accelerator text displayed right to entry label.
Attribute 07 when set to separator then display as horizontal separator
Attribute 08 not used
Attribute 09 not used
Attribute 10 not used

Usage Guide

Basic usage

  1. Create APEX List POPUP_MENU
  2. Create entries and define according to your needs (authorisation scheme, action etc)
  3. Create new button BTN_POPUP_MENU
  4. Create dynamic action
    1. Set Event to Click
    2. Set Selection Type to Button
    3. Set Button to BTN_POPUP_MENU
    4. Set Advanced \ Event Scope to Dynamic
    5. Set Advanced \ Static Container (jQuery Selector) to body
  5. Create True action
    1. Set Action to Pretius APEX Context Menu [Plug-In]
    2. Set List name to POPUP_MENU
  6. Save & run page

Clicking the button BTN_POPUP_MENU will create popup menu.

Contextual menu

The plugin can be implemented to alter default context menu (right mouse button click).

  1. Create APEX List POPUP_MENU
  2. Create entries and define according to your needs (authorisation scheme, action etc)
  3. Create dynamic action
    1. Set Event to Custom
    2. Set Custom Event to contextmenu
    3. Set Selection Type to JavaScript Expression
    4. Set JavaScript Expression to document
    5. Set Advanced \ Event Scope to Dynamic
    6. Set Advanced \ Static Container (jQuery Selector) to body
  4. Create True action
    1. Set Action to Pretius APEX Context Menu [Plug-In]
    2. Set List name to POPUP_MENU
    3. [Optional] Set Affected Elements to narrow area in which context menu will be available. For example region.
  5. Save & run page

Contextual menu can be applied to any element by specyfing Selection Type = jQuery Selector. Contextual menu can be positioned differently:

  • when Selection Type = JavaScript Expression and JavaScript Expression = document then menu is positioned to right click event position properties event.pageX and event.pageY
    • when Affected Elements is defined then menu is available only for area defined by given Affected Elements
  • When Selection Type = jQuery Selector then menu is positioned to given jQuery Selector

Advanced usage

Please read inline help text for attribute Override Behaviour for detailed information about JSON object extending existing list entry.

  1. Create APEX List POPUP_MENU_EXTEND
  2. Create entry
    1. Set List Entry Label to Extended behaviour
    2. Set Target type to URL
    3. Set URL Target to javascript: void(0);
    4. Set User defined Attribute 1 to EXTENDED_BEHAVIOUR
  3. Create new button BTN_POPUP_MENU_EXTEND
  4. Create dynamic action
    1. Set Event to Click
    2. Set Selection Type to Button
    3. Set Button to BTN_POPUP_MENU_EXTEND
  5. Create True action
    1. Set Action to Pretius APEX Context Menu [Plug-In]
    2. Set List name to POPUP_MENU_EXTEND
    3. In Settings check Override Behaviour
    4. Set Override behaviour to *
  6. Save & run page

Alter entry behaviour

* JavaScript code for point 5.iv

return {
  "EXTENDED_BEHAVIOUR": {
    "action": function( pMenuOptions, pTriggeringElement ){
      //Code to be executed when users clicks on entry
      alert('Altered action');
      return void(0);
    },
    "disabled": function( pMenuOptions, pEntry ) {
      return false;
    },
    "hide": function(pMenuOptions){
      return false;
    }
  }
};

Add submenu

* JavaScript code for point 5.iv

return {
  "EXTENDED_BEHAVIOUR": {
    "items": [
      {
        "type": "action",
        "labelKey": "Action 1",
        "action": function( pMenuOptions, pTriggeringElement ){
          alert("Action 1");
        }
      },
      {
        "type": "action",
        "labelKey": "Action 2",
        "action": function( pMenuOptions, pTriggeringElement ){
          alert("Action 2");
        }
      },
      {
        "type": "action",
        "labelKey": "Action 3",
        "action": function( pMenuOptions, pTriggeringElement ){
          alert("Action 3");
        }
      }
    ]
  }
};

List entry properties for APEX menu widget are described in official API. The plugin supports properties as follows:

Property Is supported
type Yes
id Yes
label Yes
labelKey Yes
offLabel No
offLabelKey No
onLabel No
onLabelKey No
hide Yes
disabled Yes
iconType No
icon Yes
iconStyle Yes
href Yes
action Yes
set No
get No
accelerator Yes
menu* No
choices No
choices[].label No
choices[].labelKey No
choices[].value No
choices[].disabled No
choices[].accelerator No
current No

* menu property is implemented via property items to avoid unnecessary nested objects. See Inline Help Text for attribute Override behaviour for example implmentation.

Plugin Settings

Detailed information about how to use every attribute of the plugin is presented in built-in help texts in APEX Application Builder.

Helptexts gif

Plugin Events

The plugin doesn't expose any extra events. To handle APEX menu events please refer official API.

Translations

The plugin does't use elements that can't be translated via APEX native translation capabilities.

Changelog

1.1.0

Changelog for version v1.1.0 is described in details in this blog post

  • support for accessibility,
  • Plugin attribute settings has new been enhanced with new options to select,
    • Display at Mouse Position
    • Narrow to Affected Elements
    • Stop Event Propagation
  • JavaScript attributes Override Behaviour and Add Extra Enties,
    • have extended access to dynamic actions attributes
      • this.action - the action object containing details such as the action name and additional attribute values,
      • this.browserEvent - the event object of event that triggered the event [3],
      • this.data - optional additional data that can be passed from the event handler,
    • have extended access to the plugin widget attributes
      • this.element - a jQuery reference to the DOM object of the element that invoked a menu,
      • this.id - unique identifier generated by the plugin to identify a menu container.
  • Plugin debugging supports all levels: LOG, LEVEL6 and APP_TRACE,
  • Plugin error handling is more descriptive.

1.0.0

Initial Release

Known issues

  • not yet available

Related articles

About Author

Author Website Github Twitter E-mail
Bartosz Ostrowski www.ostrowskibartosz.pl @bostrowski @bostrowsk1 bostrowski@pretius.com

About Pretius

Pretius Sp. z o.o. Sp. K.

Address Website E-mail
Przy Parku 2/2 Warsaw 02-384, Poland http://www.pretius.com office@pretius.com

Free support

Pretius provides free support for the plugins at the GitHub platform. We monitor raised issues, prepare fixes, and answer your questions. However, please note that we deliver the plug-ins free of charge, and therefore we will not always be able to help you immediately.

Interested in better support?

Bug reporting and change requests

Have you found a bug or have an idea of additional features that the plugin could cover? Firstly, please check the Roadmap and Known issues sections. If your case is not on the lists, please open an issue on a GitHub page following these rules:

  • issue should contain login credentials to the application at apex.oracle.com where the problem is reproduced;
  • issue should include steps to reproduce the case in the demo application;
  • issue should contain description about its nature.

Implementation issues

If you encounter a problem during the plug-in implementation, please check out our demo application. We do our best to describe each possible use case precisely. If you can not find a solution or your problem is different, contact us: apex-plugins@pretius.com.

Become a contributor!

We consider our plugins as genuine open source products, and we encourage you to become a contributor. Help us improve plugins by fixing bugs and developing extra features. Comment one of the opened issues or register a new one, to let others know what you are working on. When you finish, create a new pull request. We will review your code and add the changes to the repository.

By contributing to this repository, you help to build a strong APEX community. We will prioritize any issues raised by you in this and any other plugins.

Comercial support

We are happy to share our experience for free, but we also realize that sometimes response time, quick implementation, SLA, and instant release for the latest version are crucial. That’s why if you need extended support for our plug-ins, please contact us at apex-plugins@pretius.com. We offer:

  • enterprise-level assistance;
  • support in plug-ins implementation and utilization;
  • dedicated contact channel to our developers;
  • SLA at the level your organization require;
  • priority update to next APEX releases and features listed in the roadmap.

About

License:MIT License

Languages

Language:JavaScript 65.9%Language:PLSQL 33.9%Language:CSS 0.2%